@warpgogol/werkstatt-shared 0.14.1 → 0.15.0

package/src/typography/fix.ts

@@ -0,0 +1,148 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Mechanical fix engine for typography violations (RFC-1072). Provides the
+FixAction discriminated union, the FIXABLE_RULE_IDS whitelist, and the applyFixes
+pure function that transforms findings into fixed segment text. Only rules
+whitelisted in FIXABLE_RULE_IDS populate the fix field on TypographyFinding.</purpose>
+<non-goals>
+  <item>Do not read or write files — that is the command adapter in werkstatt-site.</item>
+  <item>Do not run convergence guards — the command adapter re-runs typography.validate.</item>
+  <item>Do not fix rules outside the whitelist — those require human judgment.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1072: initial creation with FixAction type, FIXABLE_RULE_IDS, and applyFixes.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { TextSegment } from "./text-surface.ts";
+import type { TypographyFinding, TypographyContext } from "./rules-tier1.ts";
+
+// ---------------------------------------------------------------------------
+// FixAction: discriminated union for mechanical fix actions
+// ---------------------------------------------------------------------------
+
+/**
+ * Discriminated union for mechanical fix actions.
+ * Stored on `TypographyFinding.fix` (replacing `null` from RFC-1068).
+ * Only rules whitelisted in FIXABLE_RULE_IDS populate this field;
+ * all other rules keep `fix: null`.
+ */
+export type FixAction =
+  | { type: "replace"; old: string; new: string }
+  | { type: "insert"; at: number; text: string }
+  | { type: "delete"; at: number; length: number };
+
+// ---------------------------------------------------------------------------
+// Whitelist of fixable rule IDs (RFC-1072)
+// ---------------------------------------------------------------------------
+
+/**
+ * Rules that are safe for mechanical fixing. Only PUNCT, SPACE, APOS, and ABBR
+ * families are fixable — other families require human judgment.
+ */
+export const FIXABLE_RULE_IDS: readonly string[] = [
+  "TYPO-PUNCT-01",
+  "TYPO-SPACE-01",
+  "TYPO-SPACE-02",
+  "TYPO-APOS-01",
+  "TYPO-APOS-02",
+  "TYPO-ABBR-01",
+  "TYPO-ABBR-02",
+] as const;
+
+const FIXABLE_SET: ReadonlySet<string> = new Set(FIXABLE_RULE_IDS);
+
+/**
+ * Check if a rule ID is in the fixable whitelist.
+ */
+export function isFixable(ruleId: string): boolean {
+  return FIXABLE_SET.has(ruleId);
+}
+
+// ---------------------------------------------------------------------------
+// Segment identity key (for Map<TextSegment, string>)
+// ---------------------------------------------------------------------------
+
+function segmentKey(segment: TextSegment): string {
+  return `${segment.file}:${segment.line}:${segment.path}`;
+}
+
+// ---------------------------------------------------------------------------
+// Apply a single fix action to segment text
+// ---------------------------------------------------------------------------
+
+function applyAction(text: string, action: FixAction, column: number): string {
+  switch (action.type) {
+    case "replace": {
+      // Replace the match at the given column
+      const before = text.slice(0, column);
+      const after = text.slice(column + action.old.length);
+      return before + action.new + after;
+    }
+    case "insert": {
+      // Insert text at the specified position (relative to segment text)
+      const before = text.slice(0, action.at);
+      const after = text.slice(action.at);
+      return before + action.text + after;
+    }
+    case "delete": {
+      // Delete `length` characters starting at `at`
+      const before = text.slice(0, action.at);
+      const after = text.slice(action.at + action.length);
+      return before + after;
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// applyFixes: apply all fixes to findings, returning fixed segment text
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply mechanical fixes to findings. Each finding must have a non-null `fix`
+ * (populated by the rule when whitelisted in FIXABLE_RULE_IDS).
+ *
+ * The function groups findings by segment, then applies all fixes within a
+ * segment in reverse column order (to avoid offset shifts). Returns a Map keyed
+ * by segment identity, with the full fixed segment text as the value.
+ *
+ * Findings with `fix: null` (non-whitelisted rules) are skipped.
+ */
+export function applyFixes(
+  findings: TypographyFinding[],
+  _context: TypographyContext,
+): { fixedSegments: Map<string, string>; fixCount: number } {
+  // Group findings by segment key
+  const bySegment = new Map<string, { segment: TextSegment; findings: TypographyFinding[] }>();
+
+  for (const f of findings) {
+    if (f.fix === null) continue;
+    const key = segmentKey(f.segment);
+    let entry = bySegment.get(key);
+    if (!entry) {
+      entry = { segment: f.segment, findings: [] };
+      bySegment.set(key, entry);
+    }
+    entry.findings.push(f);
+  }
+
+  const fixedSegments = new Map<string, string>();
+  let fixCount = 0;
+
+  for (const [key, { segment, findings: segFindings }] of bySegment) {
+    // Sort findings by column in descending order to apply from right to left
+    const sorted = [...segFindings].sort((a, b) => b.column - a.column);
+
+    let text = segment.text;
+    for (const f of sorted) {
+      if (f.fix === null) continue;
+      text = applyAction(text, f.fix, f.column);
+      fixCount++;
+    }
+
+    fixedSegments.set(key, text);
+  }
+
+  return { fixedSegments, fixCount };
+}

package/src/typography/index.ts

@@ -0,0 +1,54 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Barrel export for the typography module (RFC-1068, RFC-1069, RFC-1070,
+RFC-1071). Provides the text-surface extractor, Tier 1, Tier 2, and Tier 3 rule
+engines, and locale defaults for the typography.validate command and future
+typography rule families.</purpose>
+<non-goals>
+  <item>Do not implement command adapters — that lives in werkstatt-site.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1068: initial creation.</item>
+  <item>RFC-1069: added Tier 2 structure rules export.</item>
+  <item>RFC-1070: added Tier 2 locale rules export.</item>
+  <item>RFC-1071: added Tier 3 advisory rules export.</item>
+  <item>RFC-1072: added fix module export (FixAction, FIXABLE_RULE_IDS, applyFixes, isFixable).</item>
+</CHANGE_SUMMARY>
+*/
+
+export {
+  extractTextSurface,
+  TECHNICAL_KEYS,
+  deriveFileLocale,
+  type TextSegment,
+  type TextSegmentSource,
+  type TextSurfaceOptions,
+  type YamlError,
+  type ExtractTextSurfaceResult,
+} from "./text-surface.ts";
+
+export {
+  TIER1_RULES,
+  DEFAULT_ALLOWED_TOKENS,
+  createTypographyContext,
+  type TypographyRuleId,
+  type TypographyRuleFamily,
+  type TypographyFinding,
+  type TypographyRule,
+  type TypographyContext,
+} from "./rules-tier1.ts";
+
+export { TIER2_STRUCTURE_RULES } from "./rules-tier2-structure.ts";
+
+export { TIER2_LOCALE_RULES, type Tier2LocaleRuleId } from "./rules-tier2-locale.ts";
+
+export { TIER3_ADVISORY_RULES, type Tier3AdvisoryRuleId } from "./rules-tier3-advisory.ts";
+
+export {
+  LOCALE_DEFAULTS,
+  getLocaleDefaults,
+  type LocaleTypographyDefaults,
+} from "./locale-defaults.ts";
+
+export { type FixAction, FIXABLE_RULE_IDS, isFixable, applyFixes } from "./fix.ts";

package/src/typography/locale-defaults.ts

@@ -0,0 +1,97 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Locale-specific typography defaults for the typography rule engine.
+Exports abbreviation sets, number format defaults, and apostrophe policy keyed
+by locale code (RFC-1068, RFC-1070).</purpose>
+<non-goals>
+  <item>Do not define typography rules — only locale-specific data.</item>
+  <item>Do not read system.md or site configuration.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1068: initial creation with de, uk, en abbreviation sets.</item>
+  <item>RFC-1070: added numberFormat and apostrophePolicy to LocaleTypographyDefaults.</item>
+</CHANGE_SUMMARY>
+*/
+
+export interface LocaleTypographyDefaults {
+  /** Abbreviations ending with a period, used for TYPO-CASE-02 exclusion. */
+  abbreviations: ReadonlySet<string>;
+  /** Number format defaults for TYPO-NUM rules. Added by RFC-1070. */
+  numberFormat: {
+    decimalSeparator: "," | ".";
+    thousandsSeparator: "." | "," | " " | "\u202F";
+  };
+  /** Apostrophe policy for TYPO-APOS rules. Added by RFC-1070. */
+  apostrophePolicy: "straight" | "modifier";
+}
+
+const DE_ABBREVIATIONS = new Set([
+  "z. B.",
+  "u. a.",
+  "d. h.",
+  "bzw.",
+  "ca.",
+  "inkl.",
+  "exkl.",
+  "ggf.",
+  "evtl.",
+  "vgl.",
+  "usw.",
+  "etc.",
+  "Nr.",
+  "Abs.",
+  "Std.",
+  "Min.",
+  "Str.",
+  "vs.",
+  "lit.",
+  "Art.",
+  "Inc.",
+  "e.V.",
+]);
+
+const UK_ABBREVIATIONS = new Set([
+  "напр.",
+  "тис.",
+  "грн",
+  "т. ч.",
+  "ст.",
+  "п.",
+  "р.",
+  "див.",
+  "Див.",
+  "нім.",
+  "Inc.",
+  "e.V.",
+]);
+
+const EN_ABBREVIATIONS = new Set(["e.g.", "i.e.", "etc.", "vs.", "No.", "Inc.", "e.V."]);
+
+export const LOCALE_DEFAULTS: Record<string, LocaleTypographyDefaults> = {
+  de: {
+    abbreviations: DE_ABBREVIATIONS,
+    numberFormat: { decimalSeparator: ",", thousandsSeparator: "." },
+    apostrophePolicy: "straight",
+  },
+  uk: {
+    abbreviations: UK_ABBREVIATIONS,
+    numberFormat: { decimalSeparator: ",", thousandsSeparator: "\u202F" },
+    apostrophePolicy: "straight",
+  },
+  en: {
+    abbreviations: EN_ABBREVIATIONS,
+    numberFormat: { decimalSeparator: ".", thousandsSeparator: "," },
+    apostrophePolicy: "straight",
+  },
+};
+
+export function getLocaleDefaults(locale: string): LocaleTypographyDefaults {
+  return (
+    LOCALE_DEFAULTS[locale] ?? {
+      abbreviations: new Set(),
+      numberFormat: { decimalSeparator: ".", thousandsSeparator: "," },
+      apostrophePolicy: "straight",
+    }
+  );
+}