@warpgogol/werkstatt-shared 0.14.1 → 0.16.0

package/src/typography/rules-tier3-advisory.test.ts

@@ -0,0 +1,290 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Unit tests for Tier 3 advisory typography rules (RFC-1071). Tests cover
+all 5 rules: TYPO-UNICODE-01..02, TYPO-LINK-01..02, TYPO-SENT-01. Each rule
+is tested for positive detection, negative (no finding), and key exclusions.</purpose>
+<non-goals>
+  <item>Do not test text-surface extraction — that is text-surface.test.ts.</item>
+  <item>Do not test command adapter — that is typography.test.ts in werkstatt-site.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1071: initial creation with unit tests for 5 Tier 3 advisory rules.</item>
+</CHANGE_SUMMARY>
+*/
+
+import { describe, it, expect } from "vitest";
+import { TIER3_ADVISORY_RULES, type Tier3AdvisoryRuleId } from "./rules-tier3-advisory.ts";
+import type { TextSegment } from "./text-surface.ts";
+import type { TypographyContext, TypographyRule, TypographyFinding } from "./rules-tier1.ts";
+import { createTypographyContext } from "./rules-tier1.ts";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeSegment(
+  text: string,
+  locale: string,
+  source: "frontmatter" | "body" = "body",
+  raw?: string,
+): TextSegment {
+  return {
+    file: `test.${locale}.md`,
+    line: 1,
+    path: "$body",
+    source,
+    text,
+    raw: raw ?? text,
+    isTableRow: false,
+    locale,
+  };
+}
+
+function makeCtx(
+  locale: string,
+  allowedTokens: ReadonlySet<string> = new Set(),
+): TypographyContext {
+  return createTypographyContext(locale, allowedTokens);
+}
+
+function runRule(
+  ruleId: Tier3AdvisoryRuleId,
+  text: string,
+  locale: string,
+  source: "frontmatter" | "body" = "body",
+  raw?: string,
+): TypographyFinding[] {
+  const rule = TIER3_ADVISORY_RULES.find((r) => r.id === ruleId) as TypographyRule;
+  const segment = makeSegment(text, locale, source, raw);
+  const ctx = makeCtx(locale);
+  return rule.check(segment, ctx);
+}
+
+function expectFinding(
+  ruleId: Tier3AdvisoryRuleId,
+  text: string,
+  locale: string,
+  raw?: string,
+): void {
+  const findings = runRule(ruleId, text, locale, "body", raw);
+  expect(findings.length).toBeGreaterThanOrEqual(1);
+  expect(findings[0].ruleId).toBe(ruleId);
+}
+
+function expectNoFinding(
+  ruleId: Tier3AdvisoryRuleId,
+  text: string,
+  locale: string,
+  source: "frontmatter" | "body" = "body",
+  raw?: string,
+): void {
+  const findings = runRule(ruleId, text, locale, source, raw);
+  expect(findings).toHaveLength(0);
+}
+
+// ---------------------------------------------------------------------------
+// Verify all rules have tier 3 and severity warning
+// ---------------------------------------------------------------------------
+
+describe("TIER3_ADVISORY_RULES — metadata", () => {
+  it("has 5 rules", () => {
+    expect(TIER3_ADVISORY_RULES).toHaveLength(5);
+  });
+
+  it("all rules have tier 3 and severity warning", () => {
+    for (const rule of TIER3_ADVISORY_RULES) {
+      expect(rule.tier).toBe(3);
+      expect(rule.severity).toBe("warning");
+    }
+  });
+
+  it("has expected rule IDs", () => {
+    const ids = TIER3_ADVISORY_RULES.map((r) => r.id);
+    expect(ids).toContain("TYPO-UNICODE-01");
+    expect(ids).toContain("TYPO-UNICODE-02");
+    expect(ids).toContain("TYPO-LINK-01");
+    expect(ids).toContain("TYPO-LINK-02");
+    expect(ids).toContain("TYPO-SENT-01");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TYPO-UNICODE-01: Zero-width characters
+// ---------------------------------------------------------------------------
+
+describe("TYPO-UNICODE-01 — zero-width characters", () => {
+  it("detects U+200B (zero-width space)", () => {
+    expectFinding("TYPO-UNICODE-01", "Hello\u200BWorld", "en");
+  });
+
+  it("detects U+200C (zero-width non-joiner)", () => {
+    expectFinding("TYPO-UNICODE-01", "Hello\u200CWorld", "en");
+  });
+
+  it("detects U+200D (zero-width joiner)", () => {
+    expectFinding("TYPO-UNICODE-01", "Hello\u200DWorld", "en");
+  });
+
+  it("detects U+FEFF (BOM)", () => {
+    expectFinding("TYPO-UNICODE-01", "Hello\uFEFFWorld", "en");
+  });
+
+  it("does not flag clean text", () => {
+    expectNoFinding("TYPO-UNICODE-01", "Hello World", "en");
+  });
+
+  it("reports correct character name in message", () => {
+    const findings = runRule("TYPO-UNICODE-01", "Hello\u200BWorld", "en");
+    expect(findings[0].message).toContain("U+200B");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TYPO-UNICODE-02: Soft hyphen
+// ---------------------------------------------------------------------------
+
+describe("TYPO-UNICODE-02 — soft hyphen", () => {
+  it("detects U+00AD (soft hyphen)", () => {
+    expectFinding("TYPO-UNICODE-02", "Hello\u00ADWorld", "en");
+  });
+
+  it("does not flag clean text", () => {
+    expectNoFinding("TYPO-UNICODE-02", "Hello World", "en");
+  });
+
+  it("does not flag HTML entity &shy; (ASCII, not U+00AD)", () => {
+    expectNoFinding("TYPO-UNICODE-02", "Hello&shy;World", "en");
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TYPO-LINK-01: Link text is a bare URL
+// ---------------------------------------------------------------------------
+
+describe("TYPO-LINK-01 — bare URL link text", () => {
+  it("detects [https://example.com](https://example.com)", () => {
+    const raw = "[https://example.com](https://example.com)";
+    const text = "[https://example.com]"; // extractor strips ](url)
+    expectFinding("TYPO-LINK-01", text, "en", raw);
+  });
+
+  it("detects [http://example.com](http://example.com)", () => {
+    const raw = "[http://example.com](http://example.com)";
+    const text = "[http://example.com]";
+    expectFinding("TYPO-LINK-01", text, "en", raw);
+  });
+
+  it("does not flag descriptive link text", () => {
+    const raw = "[Learn more](https://example.com)";
+    const text = "[Learn more]";
+    expectNoFinding("TYPO-LINK-01", text, "en", "body", raw);
+  });
+
+  it("does not flag frontmatter segments", () => {
+    const raw = "[https://example.com](https://example.com)";
+    const text = "[https://example.com]";
+    expectNoFinding("TYPO-LINK-01", text, "en", "frontmatter", raw);
+  });
+
+  it("does not flag bare URLs inside inline code spans", () => {
+    const raw = "`[https://example.com](https://example.com)`";
+    const text = "\uE002"; // extractor replaces code spans with placeholder
+    expectNoFinding("TYPO-LINK-01", text, "en", "body", raw);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TYPO-LINK-02: Link text is a generic phrase
+// ---------------------------------------------------------------------------
+
+describe("TYPO-LINK-02 — generic link text", () => {
+  it("detects 'click here'", () => {
+    const raw = "[click here](https://example.com)";
+    const text = "[click here]";
+    expectFinding("TYPO-LINK-02", text, "en", raw);
+  });
+
+  it("detects 'hier klicken'", () => {
+    const raw = "[hier klicken](https://example.com)";
+    const text = "[hier klicken]";
+    expectFinding("TYPO-LINK-02", text, "de", raw);
+  });
+
+  it("detects 'тут'", () => {
+    const raw = "[тут](https://example.com)";
+    const text = "[тут]";
+    expectFinding("TYPO-LINK-02", text, "uk", raw);
+  });
+
+  it("detects 'here' case-insensitive", () => {
+    const raw = "[HERE](https://example.com)";
+    const text = "[HERE]";
+    expectFinding("TYPO-LINK-02", text, "en", raw);
+  });
+
+  it("detects 'hier' (German)", () => {
+    const raw = "[hier](https://example.com)";
+    const text = "[hier]";
+    expectFinding("TYPO-LINK-02", text, "de", raw);
+  });
+
+  it("does not flag descriptive link text", () => {
+    const raw = "[Learn more about our services](https://example.com)";
+    const text = "[Learn more about our services]";
+    expectNoFinding("TYPO-LINK-02", text, "en", "body", raw);
+  });
+
+  it("does not flag 'here' within a longer phrase", () => {
+    const raw = "[See here for details](https://example.com)";
+    const text = "[See here for details]";
+    expectNoFinding("TYPO-LINK-02", text, "en", "body", raw);
+  });
+
+  it("does not flag frontmatter segments", () => {
+    const raw = "[click here](https://example.com)";
+    const text = "[click here]";
+    expectNoFinding("TYPO-LINK-02", text, "en", "frontmatter", raw);
+  });
+
+  it("does not flag generic phrases inside inline code spans", () => {
+    const raw = "`[click here](https://example.com)`";
+    const text = "\uE002";
+    expectNoFinding("TYPO-LINK-02", text, "en", "body", raw);
+  });
+});
+
+// ---------------------------------------------------------------------------
+// TYPO-SENT-01: Sentence longer than 40 words
+// ---------------------------------------------------------------------------
+
+function makeLongSentence(wordCount: number): string {
+  return Array.from({ length: wordCount }, (_, i) => `word${i}`).join(" ") + ".";
+}
+
+describe("TYPO-SENT-01 — long sentence", () => {
+  it("detects a sentence with 41 words", () => {
+    const text = makeLongSentence(41);
+    expectFinding("TYPO-SENT-01", text, "en");
+  });
+
+  it("does not flag a sentence with 40 words", () => {
+    const text = makeLongSentence(40);
+    expectNoFinding("TYPO-SENT-01", text, "en");
+  });
+
+  it("does not flag a short sentence", () => {
+    expectNoFinding("TYPO-SENT-01", "This is a short sentence.", "en");
+  });
+
+  it("does not flag frontmatter segments", () => {
+    const text = makeLongSentence(41);
+    expectNoFinding("TYPO-SENT-01", text, "en", "frontmatter");
+  });
+
+  it("counts words correctly with Unicode punctuation", () => {
+    const words = Array.from({ length: 41 }, (_, i) => `word${i}`).join(", ");
+    const text = words + ".";
+    expectFinding("TYPO-SENT-01", text, "en");
+  });
+});

package/src/typography/rules-tier3-advisory.ts

@@ -0,0 +1,239 @@
+/*
+<MODULE_CONTRACT>
+<purpose>Tier 3 advisory typography rules (RFC-1071). Implements 5 rules across
+3 families: UNICODE (2), LINK (2), SENT (1). All rules emit severity: "warning"
+and do not block commits. Rules operate on TextSegment objects produced by the
+text-surface extractor (RFC-1068). UNICODE rules check segment.text; LINK rules
+check segment.raw (which preserves markdown link syntax stripped from segment.text);
+SENT rules check segment.text via splitSentences.</purpose>
+<non-goals>
+  <item>Do not extract text — that is text-surface.ts.</item>
+  <item>Do not handle file I/O or command registration — that is the command adapter.</item>
+  <item>Do not auto-fix — autofix is RFC-1072.</item>
+  <item>Do not validate Tier 1 or Tier 2 rules — that is rules-tier1.ts and rules-tier2-*.ts.</item>
+</non-goals>
+</MODULE_CONTRACT>
+<CHANGE_SUMMARY>
+  <item>RFC-1071: initial creation with 5 Tier 3 advisory rules.</item>
+</CHANGE_SUMMARY>
+*/
+
+import type { TextSegment } from "./text-surface.ts";
+import { finding, type TypographyFinding, type TypographyRule } from "./rules-tier1.ts";
+import { splitSentences } from "../semantic/extract.ts";
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+export type Tier3AdvisoryRuleId = `TYPO-${"UNICODE" | "LINK" | "SENT"}-${string}`;
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const INLINE_CODE_SPAN = /`[^`]*`/g;
+
+function stripInlineCodeSpans(raw: string): string {
+  return raw.replace(INLINE_CODE_SPAN, "");
+}
+
+function countWords(text: string): number {
+  const words = text.split(/\s+/).filter((w) => w.length > 0);
+  let count = 0;
+  for (const word of words) {
+    const stripped = word.replace(/\p{P}/gu, "");
+    if (stripped.length > 0) count++;
+  }
+  return count;
+}
+
+// ---------------------------------------------------------------------------
+// TYPO-UNICODE-01: Zero-width characters
+// ---------------------------------------------------------------------------
+
+const ZERO_WIDTH = /[\u200B\u200C\u200D\uFEFF]/gu;
+
+const UNICODE_01: TypographyRule = {
+  id: "TYPO-UNICODE-01",
+  family: "UNICODE",
+  tier: 3,
+  severity: "warning",
+  check(segment: TextSegment): TypographyFinding[] {
+    const findings: TypographyFinding[] = [];
+    let match: RegExpExecArray | null;
+    const regex = new RegExp(ZERO_WIDTH.source, "gu");
+    while ((match = regex.exec(segment.text)) !== null) {
+      const charName =
+        match[0] === "\u200B"
+          ? "U+200B (zero-width space)"
+          : match[0] === "\u200C"
+            ? "U+200C (zero-width non-joiner)"
+            : match[0] === "\u200D"
+              ? "U+200D (zero-width joiner)"
+              : "U+FEFF (zero-width no-break space / BOM)";
+      findings.push(
+        finding(
+          "TYPO-UNICODE-01",
+          segment,
+          match[0],
+          match.index,
+          `Invisible character ${charName} in text.`,
+          "Remove the zero-width character from the source.",
+        ),
+      );
+    }
+    return findings;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TYPO-UNICODE-02: Soft hyphen (U+00AD)
+// ---------------------------------------------------------------------------
+
+const SOFT_HYPHEN = /\u00AD/gu;
+
+const UNICODE_02: TypographyRule = {
+  id: "TYPO-UNICODE-02",
+  family: "UNICODE",
+  tier: 3,
+  severity: "warning",
+  check(segment: TextSegment): TypographyFinding[] {
+    const findings: TypographyFinding[] = [];
+    let match: RegExpExecArray | null;
+    const regex = new RegExp(SOFT_HYPHEN.source, "gu");
+    while ((match = regex.exec(segment.text)) !== null) {
+      findings.push(
+        finding(
+          "TYPO-UNICODE-02",
+          segment,
+          match[0],
+          match.index,
+          "Soft hyphen (U+00AD) in text — invisible in most editors but affects rendering.",
+          "Remove the soft hyphen from the source.",
+        ),
+      );
+    }
+    return findings;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TYPO-LINK-01: Link text is a bare URL
+// ---------------------------------------------------------------------------
+
+const BARE_URL_LINK = /\[https?:\/\/[^\]]+\]\(/giu;
+
+const LINK_01: TypographyRule = {
+  id: "TYPO-LINK-01",
+  family: "LINK",
+  tier: 3,
+  severity: "warning",
+  check(segment: TextSegment): TypographyFinding[] {
+    if (segment.source !== "body") return [];
+    const findings: TypographyFinding[] = [];
+    const cleaned = stripInlineCodeSpans(segment.raw);
+    let match: RegExpExecArray | null;
+    const regex = new RegExp(BARE_URL_LINK.source, "giu");
+    while ((match = regex.exec(cleaned)) !== null) {
+      findings.push(
+        finding(
+          "TYPO-LINK-01",
+          segment,
+          match[0],
+          match.index,
+          "Link text is a bare URL — use descriptive link text instead.",
+          "Replace the URL in link text with a descriptive phrase.",
+        ),
+      );
+    }
+    return findings;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TYPO-LINK-02: Link text is a generic phrase
+// ---------------------------------------------------------------------------
+
+const LINK_TEXT_EXTRACTOR = /\[([^\]]+)\]\([^)]*\)/gu;
+const GENERIC_LINK_PHRASES = /^(click here|hier klicken|тут|here|hier)$/i;
+
+const LINK_02: TypographyRule = {
+  id: "TYPO-LINK-02",
+  family: "LINK",
+  tier: 3,
+  severity: "warning",
+  check(segment: TextSegment): TypographyFinding[] {
+    if (segment.source !== "body") return [];
+    const findings: TypographyFinding[] = [];
+    const cleaned = stripInlineCodeSpans(segment.raw);
+    let match: RegExpExecArray | null;
+    const regex = new RegExp(LINK_TEXT_EXTRACTOR.source, "gu");
+    while ((match = regex.exec(cleaned)) !== null) {
+      const linkText = match[1];
+      if (GENERIC_LINK_PHRASES.test(linkText)) {
+        findings.push(
+          finding(
+            "TYPO-LINK-02",
+            segment,
+            match[0],
+            match.index,
+            `Link text "${linkText}" is generic — use descriptive link text instead.`,
+            `Replace "${linkText}" with a phrase that describes the link target.`,
+          ),
+        );
+      }
+    }
+    return findings;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// TYPO-SENT-01: Sentence longer than 40 words
+// ---------------------------------------------------------------------------
+
+const SENTENCE_WORD_LIMIT = 40;
+
+const SENT_01: TypographyRule = {
+  id: "TYPO-SENT-01",
+  family: "SENT",
+  tier: 3,
+  severity: "warning",
+  check(segment: TextSegment): TypographyFinding[] {
+    if (segment.source !== "body") return [];
+    const findings: TypographyFinding[] = [];
+    const sentences = splitSentences(segment.text, segment.locale);
+    let searchOffset = 0;
+    for (const sentence of sentences) {
+      const wordCount = countWords(sentence);
+      if (wordCount > SENTENCE_WORD_LIMIT) {
+        const sentenceStart = segment.text.indexOf(sentence, searchOffset);
+        const column = sentenceStart >= 0 ? sentenceStart : 0;
+        if (sentenceStart >= 0) searchOffset = sentenceStart + sentence.length;
+        findings.push(
+          finding(
+            "TYPO-SENT-01",
+            segment,
+            sentence,
+            column,
+            `Sentence has ${wordCount} words (limit: ${SENTENCE_WORD_LIMIT}) — consider splitting for readability.`,
+            "Split the long sentence into shorter ones.",
+          ),
+        );
+      }
+    }
+    return findings;
+  },
+};
+
+// ---------------------------------------------------------------------------
+// Export
+// ---------------------------------------------------------------------------
+
+export const TIER3_ADVISORY_RULES: readonly TypographyRule[] = [
+  UNICODE_01,
+  UNICODE_02,
+  LINK_01,
+  LINK_02,
+  SENT_01,
+];