agent-simple-english 0.1.0

package/src/cli/main.ts

@@ -0,0 +1,201 @@
+#!/usr/bin/env bun
+import { readFile } from "node:fs/promises"
+import { Effect, Either } from "effect"
+import { loadConfig } from "../config/load.ts"
+import { loadDictionary } from "../dictionary/load.ts"
+import { classifyPath } from "../engine/kinds.ts"
+import { lint } from "../engine/lint.ts"
+import type { LintKind, LintReport } from "../engine/types.ts"
+import { TaggerService, WinkTaggerLive } from "../tagger/wink.ts"
+import { hookInternalFailure, runHookMode } from "./hook.ts"
+import { runSessionCommand } from "./session-command.ts"
+
+const KINDS: readonly LintKind[] = ["prose-file", "slash-source", "hash-source", "commit-message"]
+
+interface CliArgs {
+  readonly json: boolean
+  readonly configPath: string | undefined
+  readonly kind: string | undefined
+  readonly kindMissingValue: boolean
+  readonly paths: readonly string[]
+}
+
+const parseArgs = (args: readonly string[]): Effect.Effect<CliArgs, Error> =>
+  Effect.gen(function* () {
+    let json = false
+    let configPath: string | undefined
+    let kind: string | undefined
+    let kindMissingValue = false
+    const paths: string[] = []
+    for (let i = 0; i < args.length; i++) {
+      const arg = args[i] as string
+      if (arg === "--json") {
+        json = true
+      } else if (arg === "--config") {
+        configPath = args[++i]
+        if (configPath === undefined) {
+          yield* Effect.fail(new Error("--config requires a file path"))
+        }
+      } else if (arg === "--kind") {
+        const value = args[i + 1]
+        if (value === undefined || value.startsWith("--")) {
+          kindMissingValue = true
+        } else {
+          kind = value
+          i++
+        }
+      } else if (arg.startsWith("--kind=")) {
+        kind = arg.slice("--kind=".length)
+      } else {
+        paths.push(arg)
+      }
+    }
+    return { json, configPath, kind, kindMissingValue, paths }
+  })
+
+const isLintKind = (value: string): value is LintKind =>
+  (KINDS as readonly string[]).includes(value)
+
+interface FileViolation {
+  readonly file: string
+  readonly ruleId: string
+  readonly severity: string
+  readonly message: string
+  readonly suggestions?: readonly string[]
+  readonly line: number
+  readonly column: number
+  readonly suggestion?: string
+}
+
+interface CliReport {
+  readonly violations: readonly FileViolation[]
+  readonly summary: { readonly total: number; readonly hard: number }
+}
+
+const readStdin = Effect.promise(async () => {
+  const chunks: Buffer[] = []
+  for await (const chunk of process.stdin) {
+    chunks.push(chunk as Buffer)
+  }
+  return Buffer.concat(chunks).toString("utf8")
+})
+
+const readInput = (path: string) =>
+  path === "-"
+    ? readStdin.pipe(Effect.map((text) => ({ path: "<stdin>", text })))
+    : Effect.tryPromise({
+        try: () => readFile(path, "utf8"),
+        catch: (cause) => new Error(`cannot read ${path}: ${cause}`),
+      }).pipe(Effect.map((text) => ({ path, text })))
+
+const toCliReport = (reports: readonly { path: string; report: LintReport }[]): CliReport => {
+  const violations = reports.flatMap(({ path, report }) =>
+    report.violations.map((violation) => ({ file: path, ...violation })),
+  )
+  return {
+    violations,
+    summary: {
+      total: violations.length,
+      hard: violations.filter((violation) => violation.severity === "hard").length,
+    },
+  }
+}
+
+const render = (report: CliReport, json: boolean): string => {
+  if (json) {
+    return JSON.stringify(report, null, 2)
+  }
+  return report.violations
+    .map((v) => `${v.file}:${v.line}:${v.column} [${v.severity}] ${v.ruleId} ${v.message}`)
+    .join("\n")
+}
+
+const args = process.argv.slice(2)
+
+const hookProgram = Effect.gen(function* () {
+  const output = yield* runHookMode(yield* readStdin).pipe(Effect.provide(WinkTaggerLive))
+  console.log(JSON.stringify(output))
+  return 0
+}).pipe(
+  Effect.catchAllCause((cause) =>
+    Effect.sync(() => {
+      console.log(JSON.stringify(hookInternalFailure(cause)))
+      return 0
+    }),
+  ),
+)
+
+const sessionProgram = Effect.gen(function* () {
+  console.log(yield* runSessionCommand(args.slice(1)))
+  return 0
+})
+
+const lintProgram = Effect.gen(function* () {
+  const tagger = yield* TaggerService
+  const { json, configPath, kind, kindMissingValue, paths } = yield* parseArgs(args)
+  if (kindMissingValue) {
+    return yield* Effect.fail(
+      new Error(`--kind requires a value; expected one of: ${KINDS.join(", ")}`),
+    )
+  }
+  if (kind !== undefined && !isLintKind(kind)) {
+    return yield* Effect.fail(
+      new Error(`unknown kind "${kind}"; expected one of: ${KINDS.join(", ")}`),
+    )
+  }
+  const config = yield* loadConfig(configPath)
+  const loadedDictionary = yield* Effect.either(
+    loadDictionary(process.env.SIMPLE_ENGLISH_DICTIONARY),
+  )
+  const dictionary = Either.getOrUndefined(loadedDictionary)
+  if (Either.isLeft(loadedDictionary)) {
+    yield* Effect.sync(() => console.error(loadedDictionary.left.message))
+  }
+  const inputs =
+    paths.length === 0
+      ? [{ path: "<stdin>", text: yield* readStdin }]
+      : yield* Effect.forEach(paths, readInput)
+
+  const report = toCliReport(
+    inputs.map(({ path, text }) => {
+      const classification = classifyPath(path)
+      return {
+        path,
+        report: lint(kind ?? classification.kind, text, {
+          ...config,
+          dictionary,
+          tagger,
+          sourceDialect: classification.sourceDialect,
+        }),
+      }
+    }),
+  )
+
+  const output = render(report, json)
+  if (output !== "") {
+    console.log(output)
+  }
+  return report.summary.hard > 0 ? 1 : 0
+})
+
+const program: Effect.Effect<number, Error> =
+  args[0] === "hook"
+    ? hookProgram
+    : args[0] === "session"
+      ? sessionProgram
+      : lintProgram.pipe(Effect.provide(WinkTaggerLive))
+
+const handled = program.pipe(
+  Effect.catchAll((error) =>
+    Effect.sync(() => {
+      console.error(error.message)
+      return 2
+    }),
+  ),
+)
+
+const exitCode = await Effect.runPromise(handled).catch((error) => {
+  console.error(String(error))
+  return 2
+})
+process.exit(exitCode)

package/src/cli/session-command.ts

@@ -0,0 +1,78 @@
+import { resolve } from "node:path"
+import { Effect, Either } from "effect"
+import { formatFailedStatusSummary, formatStatusSummary } from "../adapter/rule-summary.ts"
+import { loadConfig } from "../config/load.ts"
+import { loadDictionary } from "../dictionary/load.ts"
+import {
+  type SessionControl,
+  getSessionControl,
+  setSessionEnabled,
+  setSessionStrict,
+} from "./session-state.ts"
+
+const USAGE = "Usage: /ste [on|off|status|strict|strict off]"
+
+type DictionaryState = "loaded" | "not loaded" | `failed (${string})`
+
+function modeName(control: SessionControl): "disabled" | "enabled" | "strict" {
+  if (!control.enabled) return "disabled"
+  return control.strict ? "strict" : "enabled"
+}
+
+const readControl = (sessionId: string) =>
+  Effect.tryPromise({
+    try: () => getSessionControl(sessionId),
+    catch: (cause) => new Error(`cannot read session state: ${cause}`),
+  })
+
+const updateEnabled = (sessionId: string, enabled: boolean) =>
+  Effect.tryPromise({
+    try: () => setSessionEnabled(sessionId, enabled),
+    catch: (cause) => new Error(`cannot update session state: ${cause}`),
+  })
+
+const updateStrict = (sessionId: string, strict: boolean) =>
+  Effect.tryPromise({
+    try: () => setSessionStrict(sessionId, strict),
+    catch: (cause) => new Error(`cannot update session state: ${cause}`),
+  })
+
+function status(sessionId: string, cwd: string): Effect.Effect<string, Error> {
+  return Effect.gen(function* () {
+    const control = yield* readControl(sessionId)
+    const configResult = yield* Effect.either(loadConfig(undefined, cwd))
+    if (Either.isLeft(configResult)) {
+      return formatFailedStatusSummary(modeName(control), configResult.left.message)
+    }
+    const dictionaryPath = process.env.SIMPLE_ENGLISH_DICTIONARY
+    const dictionaryResult = yield* Effect.either(
+      loadDictionary(dictionaryPath === undefined ? undefined : resolve(cwd, dictionaryPath)),
+    )
+    const dictionary: DictionaryState = Either.isRight(dictionaryResult)
+      ? "loaded"
+      : `failed (${dictionaryResult.left.message})`
+    return formatStatusSummary(configResult.right, modeName(control), dictionary)
+  })
+}
+
+export function runSessionCommand(args: readonly string[]): Effect.Effect<string, Error> {
+  const [sessionId, cwd, ...commandParts] = args
+  if (sessionId === undefined || sessionId.length === 0 || cwd === undefined || cwd.length === 0) {
+    return Effect.fail(new Error(USAGE))
+  }
+  const command = commandParts.join(" ").trim().toLowerCase()
+  if (command === "status") return status(sessionId, cwd)
+  if (command === "on") {
+    return updateEnabled(sessionId, true).pipe(Effect.as("STE enforcement enabled."))
+  }
+  if (command === "off") {
+    return updateEnabled(sessionId, false).pipe(Effect.as("STE enforcement disabled."))
+  }
+  if (command === "strict" || command === "strict on") {
+    return updateStrict(sessionId, true).pipe(Effect.as("STE strict mode enabled."))
+  }
+  if (command === "strict off") {
+    return updateStrict(sessionId, false).pipe(Effect.as("STE strict mode disabled."))
+  }
+  return Effect.fail(new Error(USAGE))
+}

package/src/cli/session-state.ts

@@ -0,0 +1,214 @@
+import { createHash, randomUUID } from "node:crypto"
+import { mkdir, readFile, rename, rm, stat, writeFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { isAbsolute, join } from "node:path"
+
+export interface SessionControl {
+  readonly enabled: boolean
+  readonly strict: boolean
+}
+
+interface SessionState extends SessionControl {
+  readonly version: 3
+  readonly lastProcessedReply?: string
+  readonly pendingFeedback?: string
+}
+
+const DEFAULT_CONTROL: SessionControl = { enabled: true, strict: false }
+const LOCK_STALE_MILLISECONDS = 10_000
+const LOCK_RETRY_MILLISECONDS = 5
+const LOCK_RETRIES = 200
+
+const isFileError = (cause: unknown, code: string): boolean =>
+  typeof cause === "object" && cause !== null && (cause as { code?: string }).code === code
+
+const stateRoot = (): string => {
+  const configured = process.env.XDG_STATE_HOME
+  return configured && isAbsolute(configured) ? configured : join(homedir(), ".local", "state")
+}
+
+const sessionsDirectory = (): string => join(stateRoot(), "simple-english", "sessions")
+
+const sessionKey = (sessionId: string): string =>
+  createHash("sha256").update(sessionId).digest("hex")
+
+const sessionPath = (sessionId: string): string =>
+  join(sessionsDirectory(), `${sessionKey(sessionId)}.json`)
+
+const lockPath = (sessionId: string): string =>
+  join(sessionsDirectory(), `.${sessionKey(sessionId)}.lock`)
+
+function optionalString(state: Record<string, unknown>, name: string): string | undefined {
+  const value = state[name]
+  if (value !== undefined && typeof value !== "string") {
+    throw new Error(`${name} must be a string`)
+  }
+  return value as string | undefined
+}
+
+function decodeState(text: string, path: string): SessionState {
+  const value = JSON.parse(text) as unknown
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    throw new Error(`invalid session state in ${path}`)
+  }
+  const state = value as Record<string, unknown>
+  const pendingFeedback = optionalString(state, "pendingFeedback")
+  if (state.version === 1 && typeof pendingFeedback === "string") {
+    return { version: 3, ...DEFAULT_CONTROL, pendingFeedback }
+  }
+  const lastProcessedReply = optionalString(state, "lastProcessedReply")
+  if (state.version === 2 && lastProcessedReply !== undefined && lastProcessedReply.length > 0) {
+    return {
+      version: 3,
+      ...DEFAULT_CONTROL,
+      lastProcessedReply,
+      ...(pendingFeedback === undefined ? {} : { pendingFeedback }),
+    }
+  }
+  if (
+    state.version !== 3 ||
+    typeof state.enabled !== "boolean" ||
+    typeof state.strict !== "boolean" ||
+    (state.strict && !state.enabled) ||
+    lastProcessedReply === ""
+  ) {
+    throw new Error(`invalid session state in ${path}`)
+  }
+  return {
+    version: 3,
+    enabled: state.enabled,
+    strict: state.strict,
+    ...(lastProcessedReply === undefined ? {} : { lastProcessedReply }),
+    ...(pendingFeedback === undefined ? {} : { pendingFeedback }),
+  }
+}
+
+async function readState(sessionId: string): Promise<SessionState | undefined> {
+  const path = sessionPath(sessionId)
+  try {
+    return decodeState(await readFile(path, "utf8"), path)
+  } catch (cause) {
+    if (isFileError(cause, "ENOENT")) return undefined
+    throw cause
+  }
+}
+
+async function writeState(sessionId: string, state: SessionState): Promise<void> {
+  const directory = sessionsDirectory()
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  const temporaryPath = join(directory, `.${sessionKey(sessionId)}.${randomUUID()}.tmp`)
+  try {
+    await writeFile(temporaryPath, JSON.stringify(state), { encoding: "utf8", mode: 0o600 })
+    await rename(temporaryPath, sessionPath(sessionId))
+  } finally {
+    await rm(temporaryPath, { force: true })
+  }
+}
+
+const wait = (milliseconds: number): Promise<void> =>
+  new Promise((resolve) => setTimeout(resolve, milliseconds))
+
+async function acquireLock(sessionId: string): Promise<() => Promise<void>> {
+  const directory = sessionsDirectory()
+  const path = lockPath(sessionId)
+  await mkdir(directory, { recursive: true, mode: 0o700 })
+  for (let attempt = 0; attempt < LOCK_RETRIES; attempt += 1) {
+    try {
+      await mkdir(path, { mode: 0o700 })
+      return () => rm(path, { recursive: true, force: true })
+    } catch (cause) {
+      if (!isFileError(cause, "EEXIST")) throw cause
+      try {
+        const lockStat = await stat(path)
+        if (Date.now() - lockStat.mtimeMs > LOCK_STALE_MILLISECONDS) {
+          await rm(path, { recursive: true, force: true })
+          continue
+        }
+      } catch (statCause) {
+        if (!isFileError(statCause, "ENOENT")) throw statCause
+      }
+      await wait(LOCK_RETRY_MILLISECONDS)
+    }
+  }
+  throw new Error(`timed out while reading session ${sessionId}`)
+}
+
+async function withStateLock<T>(sessionId: string, operation: () => Promise<T>): Promise<T> {
+  const release = await acquireLock(sessionId)
+  try {
+    return await operation()
+  } finally {
+    await release()
+  }
+}
+
+const currentState = (state: SessionState | undefined): SessionState =>
+  state ?? { version: 3, ...DEFAULT_CONTROL }
+
+export async function getSessionControl(sessionId: string): Promise<SessionControl> {
+  return withStateLock(sessionId, async () => {
+    const { enabled, strict } = currentState(await readState(sessionId))
+    return { enabled, strict }
+  })
+}
+
+export async function setSessionEnabled(sessionId: string, enabled: boolean): Promise<void> {
+  await withStateLock(sessionId, async () => {
+    const state = currentState(await readState(sessionId))
+    await writeState(sessionId, {
+      ...state,
+      enabled,
+      strict: enabled ? state.strict : false,
+      ...(enabled || state.pendingFeedback === undefined ? {} : { pendingFeedback: undefined }),
+    })
+  })
+}
+
+export async function setSessionStrict(sessionId: string, strict: boolean): Promise<void> {
+  await withStateLock(sessionId, async () => {
+    const state = currentState(await readState(sessionId))
+    await writeState(sessionId, {
+      ...state,
+      enabled: strict ? true : state.enabled,
+      strict,
+    })
+  })
+}
+
+export async function hasProcessedReply(
+  sessionId: string,
+  replyIdentity: string,
+): Promise<boolean> {
+  return withStateLock(sessionId, async () => {
+    const state = await readState(sessionId)
+    return state?.lastProcessedReply === replyIdentity
+  })
+}
+
+export async function setReplyFeedback(
+  sessionId: string,
+  replyIdentity: string,
+  pendingFeedback: string | undefined,
+): Promise<SessionControl | undefined> {
+  return withStateLock(sessionId, async () => {
+    const state = currentState(await readState(sessionId))
+    if (!state.enabled || state.lastProcessedReply === replyIdentity) return undefined
+    await writeState(sessionId, {
+      ...state,
+      lastProcessedReply: replyIdentity,
+      ...(state.strict || pendingFeedback === undefined
+        ? { pendingFeedback: undefined }
+        : { pendingFeedback }),
+    })
+    return { enabled: state.enabled, strict: state.strict }
+  })
+}
+
+export async function consumePendingFeedback(sessionId: string): Promise<string | undefined> {
+  return withStateLock(sessionId, async () => {
+    const state = await readState(sessionId)
+    if (state?.pendingFeedback === undefined) return undefined
+    await writeState(sessionId, { ...state, pendingFeedback: undefined })
+    return state.pendingFeedback
+  })
+}

package/src/config/load.ts

@@ -0,0 +1,85 @@
+import { readFile } from "node:fs/promises"
+import { homedir } from "node:os"
+import { isAbsolute, join, resolve } from "node:path"
+import { Effect } from "effect"
+import { mergeConfigs } from "./merge.ts"
+import { ConfigError, type SteConfig, decodeConfig } from "./schema.ts"
+
+const legacyAgentConfigDirectory = (cwd: string): string => {
+  const configured = process.env.PI_CODING_AGENT_DIR
+  if (!configured) return join(homedir(), ".pi", "agent")
+  if (configured === "~") return homedir()
+  const expanded =
+    configured.startsWith("~/") || (process.platform === "win32" && configured.startsWith("~\\"))
+      ? join(homedir(), configured.slice(2))
+      : configured
+  return isAbsolute(expanded) ? expanded : resolve(cwd, expanded)
+}
+
+const xdgConfigDirectory = (): string => {
+  const configured = process.env.XDG_CONFIG_HOME
+  return configured && isAbsolute(configured) ? configured : join(homedir(), ".config")
+}
+
+export const globalConfigPath = (): string =>
+  join(xdgConfigDirectory(), "simple-english", "config.json")
+
+export const projectConfigPath = (cwd: string): string => join(cwd, ".simple-english.json")
+
+export const legacyGlobalConfigPath = (cwd = process.cwd()): string =>
+  join(legacyAgentConfigDirectory(cwd), "simple-english.json")
+
+export const legacyProjectConfigPath = (cwd: string): string =>
+  join(cwd, ".pi", "simple-english.json")
+
+const isMissingFile = (cause: unknown): boolean =>
+  typeof cause === "object" && cause !== null && (cause as { code?: string }).code === "ENOENT"
+
+const readConfigFile = (
+  path: string,
+  optional: boolean,
+): Effect.Effect<SteConfig | undefined, ConfigError> =>
+  Effect.tryPromise({
+    try: () => readFile(path, "utf8"),
+    catch: (cause) => cause,
+  }).pipe(
+    Effect.matchEffect({
+      onFailure: (cause) =>
+        optional && isMissingFile(cause)
+          ? Effect.succeed(undefined)
+          : Effect.fail(new ConfigError(`cannot read config file ${path}: ${cause}`)),
+      onSuccess: (text) =>
+        Effect.try({
+          try: () => JSON.parse(text) as unknown,
+          catch: (cause) => new ConfigError(`invalid JSON in ${path}: ${cause}`),
+        }).pipe(Effect.flatMap((json) => decodeConfig(json, path))),
+    }),
+  )
+
+const readConfigWithFallback = (
+  path: string,
+  fallbackPath: string,
+): Effect.Effect<SteConfig, ConfigError> =>
+  readConfigFile(path, true).pipe(
+    Effect.flatMap((config) =>
+      config === undefined
+        ? readConfigFile(fallbackPath, true).pipe(Effect.map((fallback) => fallback ?? {}))
+        : Effect.succeed(config),
+    ),
+  )
+
+export const loadConfig = (
+  explicitPath?: string,
+  cwd = process.cwd(),
+  includeProjectConfig = true,
+): Effect.Effect<SteConfig, ConfigError> => {
+  if (explicitPath !== undefined) {
+    return readConfigFile(explicitPath, false).pipe(Effect.map((config) => config ?? {}))
+  }
+  const globalConfig = readConfigWithFallback(globalConfigPath(), legacyGlobalConfigPath(cwd))
+  if (!includeProjectConfig) return globalConfig
+  const projectConfig = readConfigWithFallback(projectConfigPath(cwd), legacyProjectConfigPath(cwd))
+  return Effect.all([globalConfig, projectConfig]).pipe(
+    Effect.map(([global, project]) => mergeConfigs(global, project)),
+  )
+}

package/src/config/merge.ts

@@ -0,0 +1,20 @@
+import type { SteConfig } from "./schema.ts"
+
+const isPlainObject = (value: unknown): value is Record<string, unknown> =>
+  typeof value === "object" && value !== null && !Array.isArray(value)
+
+const deepMerge = (
+  base: Record<string, unknown>,
+  over: Record<string, unknown>,
+): Record<string, unknown> => {
+  const merged = { ...base }
+  for (const [key, value] of Object.entries(over)) {
+    const existing = merged[key]
+    merged[key] =
+      isPlainObject(existing) && isPlainObject(value) ? deepMerge(existing, value) : value
+  }
+  return merged
+}
+
+export const mergeConfigs = (global: SteConfig, project: SteConfig): SteConfig =>
+  deepMerge(global as Record<string, unknown>, project as Record<string, unknown>) as SteConfig

package/src/config/schema.ts

@@ -0,0 +1,69 @@
+import { Effect, ParseResult, Schema } from "effect"
+import { type RuleId, ruleIds } from "../engine/rules/registry.ts"
+import type { RuleSetting } from "../engine/types.ts"
+
+export interface SteConfig {
+  readonly rules?: Partial<Readonly<Record<RuleId, RuleSetting>>>
+  readonly maxSentenceWords?: number
+}
+
+const RuleSettingSchema = Schema.Literal("hard", "soft", "off").annotations({
+  message: (issue) => ({
+    message: `must be "hard", "soft", or "off", got ${JSON.stringify(issue.actual)}`,
+    override: true,
+  }),
+})
+
+const RulesSchema = Schema.partial(
+  Schema.Struct(Object.fromEntries(ruleIds.map((id) => [id, RuleSettingSchema]))),
+)
+
+const MaxSentenceWordsSchema = Schema.Int.pipe(Schema.positive()).annotations({
+  message: (issue) => ({
+    message: `must be a positive integer, got ${JSON.stringify(issue.actual)}`,
+    override: true,
+  }),
+})
+
+const SteConfigSchema = Schema.Struct({
+  rules: Schema.optional(RulesSchema),
+  maxSentenceWords: Schema.optional(MaxSentenceWordsSchema),
+})
+
+const decodeUnknown = Schema.decodeUnknown(SteConfigSchema, {
+  onExcessProperty: "error",
+  errors: "all",
+})
+
+export class ConfigError extends Error {
+  readonly _tag = "ConfigError"
+}
+
+const formatError = (error: ParseResult.ParseError, source: string): string => {
+  // Optional fields decode as `T | undefined` unions, so every failure also
+  // reports a useless "Expected undefined" branch; drop those.
+  const issues = ParseResult.ArrayFormatter.formatErrorSync(error).filter(
+    (issue) => !issue.message.startsWith("Expected undefined"),
+  )
+  const lines = [
+    ...new Set(
+      issues.map(
+        (issue) => `${issue.path.length > 0 ? issue.path.join(".") : "config"}: ${issue.message}`,
+      ),
+    ),
+  ]
+  const detail =
+    lines.length > 0
+      ? lines.map((line) => `  ${line}`).join("\n")
+      : `  ${ParseResult.TreeFormatter.formatErrorSync(error)}`
+  return `invalid config in ${source}:\n${detail}`
+}
+
+export const decodeConfig = (
+  input: unknown,
+  source: string,
+): Effect.Effect<SteConfig, ConfigError> =>
+  decodeUnknown(input).pipe(
+    Effect.mapError((error) => new ConfigError(formatError(error, source))),
+    Effect.map((config) => config as SteConfig),
+  )

package/src/dictionary/README.md

@@ -0,0 +1,18 @@
+# Dictionary data format
+
+`data/pi-ste.json` uses the package-owned format that `schema.ts` defines and Effect Schema validates.
+
+- `formatVersion` identifies incompatible format changes.
+- `source` records the source name and pins the repository, commit, and path from which the data was converted.
+- `entries[].unapproved` lists exact case-insensitive word forms or phrases.
+  Forms can contain letters, numbers, internal apostrophes, internal hyphens, and horizontal whitespace between words.
+- `entries[].suggestions` lists approved alternatives.
+- `entries[].partsOfSpeech`, when present, lists the POS tags for which the forms are unapproved.
+
+Unknown properties and unsupported form syntax cause dictionary validation to fail.
+Matching is token based, and a hyphenated form matches only that exact hyphenated token.
+A phrase can span horizontal whitespace or a soft line break in the same Markdown paragraph, but it cannot span Markdown block boundaries or hard line breaks.
+Fenced and indented Markdown code is excluded from matching.
+The rule checks an entry with `partsOfSpeech` only when an injected tagger returns one of those tags for the form's first token.
+The rule checks an entry without `partsOfSpeech` by word or phrase alone.
+See [`THIRD_PARTY_NOTICES.md`](../../THIRD_PARTY_NOTICES.md) for the bundled data's exact source, conversion scope, and license details.