@startsimpli/ui 0.4.51 → 0.4.53

package/src/components/validation/__tests__/ValidationChecklist.test.tsx

@@ -0,0 +1,84 @@
+import * as React from 'react';
+import { render, screen, fireEvent } from '@testing-library/react';
+import { ValidationChecklist } from '../ValidationChecklist';
+import type { ContentCheck } from '../checks';
+
+const checks: ContentCheck[] = [
+  { id: 'blog-words', label: 'Blog word count', status: 'pass', detail: '450 words' },
+  { id: 'linkedin-words', label: 'LinkedIn word count', status: 'warn', detail: '100 words' },
+  { id: 'no-hype', label: 'No hype words', status: 'fail', detail: 'revolutionary' },
+];
+
+describe('ValidationChecklist', () => {
+  it('renders every check with its label and detail', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.getByText('Blog word count')).toBeInTheDocument();
+    expect(screen.getByText('— 450 words')).toBeInTheDocument();
+    expect(screen.getByText('No hype words')).toBeInTheDocument();
+  });
+
+  it('summarises passing count in the overall pill', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.getByText('1/3 passing')).toBeInTheDocument();
+  });
+
+  it('renders the judge verdict, scores, and expandable issues', () => {
+    render(
+      <ValidationChecklist
+        checks={checks}
+        judgeVerdict={{
+          verdict: 'revise',
+          summary: 'Reads well but sourcing is thin.',
+          scores: { clarity: 8, accuracy: 6 },
+          issues: [{ guardrail: 'sourcing', severity: 'high', problem: 'Unsupported claim', fix: 'Add a citation' }],
+        }}
+      />,
+    );
+    expect(screen.getByText('AI judge')).toBeInTheDocument();
+    expect(screen.getByText('revise')).toBeInTheDocument();
+    expect(screen.getByText('Reads well but sourcing is thin.')).toBeInTheDocument();
+    expect(screen.getByText('clarity')).toBeInTheDocument();
+
+    // issues collapsed by default, expand on click
+    expect(screen.queryByText('Unsupported claim')).not.toBeInTheDocument();
+    fireEvent.click(screen.getByText('1 issue'));
+    expect(screen.getByText('Unsupported claim')).toBeInTheDocument();
+    expect(screen.getByText('Fix: Add a citation')).toBeInTheDocument();
+  });
+
+  it('is read-only when no onOverride is provided', () => {
+    render(<ValidationChecklist checks={checks} />);
+    expect(screen.queryByText('Override checks (with reason)')).not.toBeInTheDocument();
+  });
+
+  it('drives the override flow when onOverride is provided', () => {
+    const onOverride = jest.fn();
+    render(<ValidationChecklist checks={checks} onOverride={onOverride} />);
+
+    fireEvent.click(screen.getByText('Override checks (with reason)'));
+    const textarea = screen.getByLabelText('Reason for overriding checks');
+    // empty reason keeps the confirm disabled
+    expect(screen.getByRole('button', { name: 'Override' })).toBeDisabled();
+
+    fireEvent.change(textarea, { target: { value: 'Client approved the exception.' } });
+    fireEvent.click(screen.getByRole('button', { name: 'Override' }));
+    expect(onOverride).toHaveBeenCalledWith({ overridden: true, reason: 'Client approved the exception.' });
+  });
+
+  it('shows an overridden banner and can clear the override', () => {
+    const onOverride = jest.fn();
+    render(
+      <ValidationChecklist
+        checks={checks}
+        override={{ overridden: true, reason: 'Approved by editor.' }}
+        onOverride={onOverride}
+      />,
+    );
+    expect(screen.getByText('Checks overridden')).toBeInTheDocument();
+    expect(screen.getByText('Approved by editor.')).toBeInTheDocument();
+    expect(screen.getByText('Overridden')).toBeInTheDocument();
+
+    fireEvent.click(screen.getByText('Clear'));
+    expect(onOverride).toHaveBeenCalledWith({ overridden: false });
+  });
+});

package/src/components/validation/__tests__/checks.test.ts

@@ -0,0 +1,191 @@
+import {
+  runContentChecks,
+  overallStatus,
+  wordCount,
+  tagCount,
+  extractUrls,
+  hostOf,
+  DEFAULT_HYPE_WORDS,
+  type ContentCheck,
+} from '../checks';
+
+/** Build a string of exactly `n` whitespace-delimited words. */
+const words = (n: number) => Array.from({ length: n }, (_, i) => `w${i}`).join(' ');
+const find = (checks: ContentCheck[], id: string) => checks.find((c) => c.id === id);
+
+describe('word/tag helpers', () => {
+  it('wordCount handles empty, whitespace, and normal input', () => {
+    expect(wordCount(undefined)).toBe(0);
+    expect(wordCount('')).toBe(0);
+    expect(wordCount('   ')).toBe(0);
+    expect(wordCount('one two   three')).toBe(3);
+    expect(wordCount(words(462))).toBe(462);
+  });
+
+  it('tagCount splits on commas and ignores empties', () => {
+    expect(tagCount(undefined)).toBe(0);
+    expect(tagCount('')).toBe(0);
+    expect(tagCount('a, b, c')).toBe(3);
+    expect(tagCount('a,,b, ,c,')).toBe(3);
+  });
+});
+
+describe('runContentChecks — field presence', () => {
+  it('emits no checks for an empty fields object (no approvedHosts)', () => {
+    expect(runContentChecks({})).toEqual([]);
+  });
+
+  it('only emits a check for a field that is present', () => {
+    const checks = runContentChecks({ blog: words(450) });
+    expect(checks.map((c) => c.id).sort()).toEqual(['blog-words', 'no-hype']);
+  });
+});
+
+describe('word-count bands', () => {
+  it('blog: in-band 400–500 passes, outside warns, with a "N words" detail', () => {
+    expect(find(runContentChecks({ blog: words(450) }), 'blog-words')).toMatchObject({ status: 'pass', detail: '450 words' });
+    expect(find(runContentChecks({ blog: words(300) }), 'blog-words')).toMatchObject({ status: 'warn', detail: '300 words' });
+    expect(find(runContentChecks({ blog: words(600) }), 'blog-words')!.status).toBe('warn');
+    // inclusive edges
+    expect(find(runContentChecks({ blog: words(400) }), 'blog-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ blog: words(500) }), 'blog-words')!.status).toBe('pass');
+  });
+
+  it('linkedin: default band 150–250', () => {
+    expect(find(runContentChecks({ linkedin: words(200) }), 'linkedin-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ linkedin: words(100) }), 'linkedin-words')!.status).toBe('warn');
+  });
+
+  it('headline: default band 8–12 words', () => {
+    expect(find(runContentChecks({ headline: words(10) }), 'headline-words')!.status).toBe('pass');
+    expect(find(runContentChecks({ headline: words(5) }), 'headline-words')!.status).toBe('warn');
+    expect(find(runContentChecks({ headline: words(20) }), 'headline-words')!.status).toBe('warn');
+  });
+
+  it('honours a custom band override', () => {
+    const c = find(runContentChecks({ blog: words(100) }, { blogWords: [50, 150] }), 'blog-words');
+    expect(c!.status).toBe('pass');
+  });
+});
+
+describe('tag count and meta length', () => {
+  it('tags: default band 4–6', () => {
+    expect(find(runContentChecks({ tags: 'a,b,c,d,e' }), 'tags-count')).toMatchObject({ status: 'pass', detail: '5 tags' });
+    expect(find(runContentChecks({ tags: 'a,b' }), 'tags-count')!.status).toBe('warn');
+    expect(find(runContentChecks({ tags: 'a,b,c,d,e,f,g' }), 'tags-count')!.status).toBe('warn');
+  });
+
+  it('meta description: default band 150–160 chars', () => {
+    const inBand = 'x'.repeat(155);
+    const tooShort = 'x'.repeat(120);
+    expect(find(runContentChecks({ metaDescription: inBand }), 'meta-length')).toMatchObject({ status: 'pass', detail: '155 chars' });
+    expect(find(runContentChecks({ metaDescription: tooShort }), 'meta-length')!.status).toBe('warn');
+  });
+});
+
+describe('[link] placeholder', () => {
+  it('passes when present, warns when absent', () => {
+    expect(find(runContentChecks({ linkedin: 'read more [link] now' }), 'link-placeholder')!.status).toBe('pass');
+    expect(find(runContentChecks({ linkedin: 'no placeholder here' }), 'link-placeholder')).toMatchObject({
+      status: 'warn',
+      detail: 'no [link] found',
+    });
+  });
+
+  it('is skipped when requireLink is false', () => {
+    expect(find(runContentChecks({ linkedin: 'no placeholder' }, { requireLink: false }), 'link-placeholder')).toBeUndefined();
+  });
+});
+
+describe('no-hype', () => {
+  it('fails when a hype word appears (case-insensitive) across headline/blog/linkedin', () => {
+    const c = find(runContentChecks({ headline: 'A REVOLUTIONARY launch', blog: words(450) }), 'no-hype');
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('revolutionary');
+  });
+
+  it('detects multi-word and hyphenated hype phrases', () => {
+    expect(find(runContentChecks({ blog: 'the best-in-class widget' }), 'no-hype')!.status).toBe('fail');
+    expect(find(runContentChecks({ blog: 'the most attractive option' }), 'no-hype')!.status).toBe('fail');
+  });
+
+  it('passes clean prose', () => {
+    expect(find(runContentChecks({ blog: 'a measured, factual paragraph about widgets' }), 'no-hype')!.status).toBe('pass');
+  });
+
+  it('honours a custom hype list', () => {
+    expect(find(runContentChecks({ blog: 'totally banana content' }, { hypeWords: ['banana'] }), 'no-hype')!.status).toBe('fail');
+    // default hype words no longer apply when overridden
+    expect(find(runContentChecks({ blog: 'revolutionary content' }, { hypeWords: ['banana'] }), 'no-hype')!.status).toBe('pass');
+  });
+
+  it('ships a non-empty default hype list', () => {
+    expect(DEFAULT_HYPE_WORDS.length).toBeGreaterThan(5);
+    expect(DEFAULT_HYPE_WORDS).toContain('game-changing');
+  });
+});
+
+describe('approved sources', () => {
+  const approvedHosts = ['example.com', 'gov.uk'];
+
+  it('is skipped entirely when approvedHosts is omitted', () => {
+    expect(find(runContentChecks({ sources: 'https://example.com/a' }), 'approved-sources')).toBeUndefined();
+  });
+
+  it('passes when every host is approved (www. stripped)', () => {
+    const c = find(runContentChecks({ sources: 'https://www.example.com/a https://gov.uk/b' }, { approvedHosts }), 'approved-sources');
+    expect(c!.status).toBe('pass');
+  });
+
+  it('fails when any host is not on the allow-list', () => {
+    const c = find(runContentChecks({ sources: 'https://example.com/a https://sketchy.io/x' }, { approvedHosts }), 'approved-sources');
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('sketchy.io');
+    expect(c!.detail).not.toContain('example.com');
+  });
+
+  it('fails forum/social hosts even if listed', () => {
+    const c = find(
+      runContentChecks({ sources: 'https://reddit.com/r/x' }, { approvedHosts: ['reddit.com'] }),
+      'approved-sources',
+    );
+    expect(c!.status).toBe('fail');
+    expect(c!.detail).toContain('reddit.com');
+  });
+
+  it('warns when there is no URL to check', () => {
+    expect(find(runContentChecks({ sources: 'no links here' }, { approvedHosts }), 'approved-sources')).toMatchObject({
+      status: 'warn',
+      detail: 'no sources to check',
+    });
+    // sources field absent but allow-list present → still a warn (nothing to check)
+    expect(find(runContentChecks({}, { approvedHosts }), 'approved-sources')!.status).toBe('warn');
+  });
+
+  it('extractUrls + hostOf normalise correctly', () => {
+    expect(extractUrls('see https://a.com/x and http://b.org')).toEqual(['https://a.com/x', 'http://b.org']);
+    expect(extractUrls('none')).toEqual([]);
+    expect(hostOf('https://www.Example.com/path')).toBe('example.com');
+    expect(hostOf('not a url')).toBe('');
+  });
+});
+
+describe('overallStatus', () => {
+  const mk = (status: ContentCheck['status']): ContentCheck => ({ id: status, label: status, status });
+
+  it('fail beats warn beats pass; empty is pass', () => {
+    expect(overallStatus([])).toBe('pass');
+    expect(overallStatus([mk('pass'), mk('pass')])).toBe('pass');
+    expect(overallStatus([mk('pass'), mk('warn')])).toBe('warn');
+    expect(overallStatus([mk('warn'), mk('fail')])).toBe('fail');
+  });
+
+  it('rolls up a realistic mixed run', () => {
+    const checks = runContentChecks(
+      { blog: words(450), linkedin: 'a revolutionary post [link]', tags: 'a,b,c,d,e' },
+      {},
+    );
+    // blog pass, linkedin word-count warn (2 words), link pass, hype fail, tags pass
+    expect(overallStatus(checks)).toBe('fail');
+  });
+});

package/src/components/validation/checks.ts

@@ -0,0 +1,240 @@
+/**
+ * Deterministic content checks (768w.16.10.1) — pure + framework-free.
+ *
+ * A Foundry tenant reviews AI-generated content before accepting it. The n8n
+ * pipeline that produced the content also ran a set of deterministic
+ * auto-checks (word-count bands, hype-word scan, approved-source allow-list)
+ * and stored their result on the record. This module re-implements the SAME
+ * logic so the client can RECOMPUTE the checks against the reviewer's *edited*
+ * content — validation reflects the current draft, not the stale original.
+ *
+ * Keep this identical to the n8n judge's deterministic logic so client +
+ * pipeline always agree. No React, no DOM — importable from a Node/LLM route.
+ */
+
+/** A single check's outcome. Green / amber / red, encoded redundantly in the UI. */
+export type CheckStatus = 'pass' | 'warn' | 'fail';
+
+/** One deterministic check result. */
+export interface ContentCheck {
+  /** Stable id for the check (e.g. `blog-words`, `no-hype`). */
+  id: string;
+  /** Human label shown in the checklist. */
+  label: string;
+  status: CheckStatus;
+  /** Short human explanation (e.g. "462 words", "unapproved: reddit.com"). */
+  detail?: string;
+}
+
+/**
+ * The content fields a record can expose for checking. All optional — a check
+ * is only emitted for a field that is present (an app without a `blog` field
+ * never gets a spurious blog check). `tags` and `sources` are flat strings
+ * (comma-separated tags, whitespace/URL-bearing sources) to match how the
+ * pipeline stores them.
+ */
+export interface ContentFields {
+  blog?: string;
+  linkedin?: string;
+  headline?: string;
+  tags?: string;
+  metaDescription?: string;
+  sources?: string;
+}
+
+/** An inclusive `[min, max]` band. */
+export type Band = [min: number, max: number];
+
+/**
+ * Tunable thresholds. Everything has a sensible default EXCEPT `approvedHosts`:
+ * the source allow-list is deliberately app-injected (no hardcoded list here),
+ * so the approved-sources check is skipped entirely when it is omitted.
+ */
+export interface ContentChecksConfig {
+  /** Blog word-count band (default 400–500). */
+  blogWords?: Band;
+  /** LinkedIn word-count band (default 150–250). */
+  linkedinWords?: Band;
+  /** Headline word-count band (default 8–12). */
+  headlineWords?: Band;
+  /** Tag-count band (default 4–6). */
+  tagsCount?: Band;
+  /** Meta-description character band (default 150–160). */
+  metaChars?: Band;
+  /** Require a `[link]` placeholder in the LinkedIn post (default true). */
+  requireLink?: boolean;
+  /** Override the hype-word blocklist. */
+  hypeWords?: string[];
+  /** Approved source hosts (no `www.`). REQUIRED to run the source check. */
+  approvedHosts?: string[];
+}
+
+/**
+ * The default hype/marketing-fluff blocklist. If ANY appears in the content the
+ * hype check FAILS. Matches the n8n judge's list — keep the two in sync.
+ */
+export const DEFAULT_HYPE_WORDS: string[] = [
+  'game-changing',
+  'gamechanging',
+  'revolutionary',
+  'world-leading',
+  'world leading',
+  'unprecedented',
+  'undisputed',
+  'transformational',
+  'groundbreaking',
+  'ground-breaking',
+  'best-in-class',
+  'unmatched',
+  'unrivalled',
+  'unrivaled',
+  'on earth',
+  'most attractive',
+];
+
+/** Forum / social hosts that are never an acceptable source, allow-list or not. */
+const FORUM_SOCIAL = /reddit|quora|facebook|twitter|forum/i;
+
+const DEFAULTS = {
+  blogWords: [400, 500] as Band,
+  linkedinWords: [150, 250] as Band,
+  headlineWords: [8, 12] as Band,
+  tagsCount: [4, 6] as Band,
+  metaChars: [150, 160] as Band,
+};
+
+/** Count words in a string — whitespace-delimited, empty → 0. */
+export function wordCount(text: string | null | undefined): number {
+  if (!text) return 0;
+  return text.trim().split(/\s+/).filter(Boolean).length;
+}
+
+/** Count comma-separated tags in a flat string, ignoring empties. */
+export function tagCount(tags: string | null | undefined): number {
+  if (!tags) return 0;
+  return tags
+    .split(',')
+    .map((t) => t.trim())
+    .filter(Boolean).length;
+}
+
+/** pass when `n` is inside the inclusive band, else warn. */
+function bandStatus(n: number, [min, max]: Band): CheckStatus {
+  return n >= min && n <= max ? 'pass' : 'warn';
+}
+
+/** Pull http(s) URLs out of a free-text sources string. */
+export function extractUrls(text: string | null | undefined): string[] {
+  if (!text) return [];
+  return text.match(/https?:\/\/[^\s"'<>)\]]+/gi) ?? [];
+}
+
+/** Normalise a URL to its bare host (lowercased, `www.` stripped). '' if unparseable. */
+export function hostOf(url: string): string {
+  try {
+    return new URL(url).hostname.toLowerCase().replace(/^www\./, '');
+  } catch {
+    return '';
+  }
+}
+
+/**
+ * Recompute every deterministic content check over `fields`. Pure. A check is
+ * emitted only when its underlying field is present; the approved-sources check
+ * is emitted only when `config.approvedHosts` is supplied.
+ */
+export function runContentChecks(fields: ContentFields, config: ContentChecksConfig = {}): ContentCheck[] {
+  const checks: ContentCheck[] = [];
+  const {
+    blogWords = DEFAULTS.blogWords,
+    linkedinWords = DEFAULTS.linkedinWords,
+    headlineWords = DEFAULTS.headlineWords,
+    tagsCount = DEFAULTS.tagsCount,
+    metaChars = DEFAULTS.metaChars,
+    requireLink = true,
+    hypeWords = DEFAULT_HYPE_WORDS,
+    approvedHosts,
+  } = config;
+
+  // Word-count bands.
+  if (fields.headline !== undefined) {
+    const n = wordCount(fields.headline);
+    checks.push({ id: 'headline-words', label: 'Headline length', status: bandStatus(n, headlineWords), detail: `${n} words` });
+  }
+  if (fields.blog !== undefined) {
+    const n = wordCount(fields.blog);
+    checks.push({ id: 'blog-words', label: 'Blog word count', status: bandStatus(n, blogWords), detail: `${n} words` });
+  }
+  if (fields.linkedin !== undefined) {
+    const n = wordCount(fields.linkedin);
+    checks.push({ id: 'linkedin-words', label: 'LinkedIn word count', status: bandStatus(n, linkedinWords), detail: `${n} words` });
+  }
+
+  // Tag count.
+  if (fields.tags !== undefined) {
+    const n = tagCount(fields.tags);
+    checks.push({ id: 'tags-count', label: 'Tag count', status: bandStatus(n, tagsCount), detail: `${n} tags` });
+  }
+
+  // Meta description length (characters).
+  if (fields.metaDescription !== undefined) {
+    const len = fields.metaDescription.trim().length;
+    checks.push({ id: 'meta-length', label: 'Meta description length', status: bandStatus(len, metaChars), detail: `${len} chars` });
+  }
+
+  // `[link]` placeholder present in the LinkedIn post.
+  if (requireLink && fields.linkedin !== undefined) {
+    const has = fields.linkedin.includes('[link]');
+    checks.push({
+      id: 'link-placeholder',
+      label: '[link] placeholder in LinkedIn',
+      status: has ? 'pass' : 'warn',
+      detail: has ? undefined : 'no [link] found',
+    });
+  }
+
+  // No hype words — scan headline + blog + linkedin, lowercased.
+  const hasProse = fields.headline !== undefined || fields.blog !== undefined || fields.linkedin !== undefined;
+  if (hasProse) {
+    const haystack = [fields.headline, fields.blog, fields.linkedin]
+      .filter((s): s is string => typeof s === 'string')
+      .join('\n')
+      .toLowerCase();
+    const found = hypeWords.filter((w) => haystack.includes(w.toLowerCase()));
+    checks.push({
+      id: 'no-hype',
+      label: 'No hype words',
+      status: found.length > 0 ? 'fail' : 'pass',
+      detail: found.length > 0 ? found.join(', ') : undefined,
+    });
+  }
+
+  // Approved sources — only when the app supplied an allow-list.
+  if (approvedHosts !== undefined) {
+    const approved = new Set(approvedHosts.map((h) => h.toLowerCase().replace(/^www\./, '')));
+    const hosts = extractUrls(fields.sources).map(hostOf).filter(Boolean);
+    if (hosts.length === 0) {
+      checks.push({ id: 'approved-sources', label: 'Approved sources', status: 'warn', detail: 'no sources to check' });
+    } else {
+      const bad = Array.from(new Set(hosts.filter((h) => !approved.has(h) || FORUM_SOCIAL.test(h))));
+      checks.push({
+        id: 'approved-sources',
+        label: 'Approved sources',
+        status: bad.length > 0 ? 'fail' : 'pass',
+        detail: bad.length > 0 ? `unapproved: ${bad.join(', ')}` : `${hosts.length} source${hosts.length === 1 ? '' : 's'} ok`,
+      });
+    }
+  }
+
+  return checks;
+}
+
+/**
+ * Roll a list of checks up to one status: fail if any fails, else warn if any
+ * warns, else pass (empty → pass).
+ */
+export function overallStatus(checks: ContentCheck[]): CheckStatus {
+  if (checks.some((c) => c.status === 'fail')) return 'fail';
+  if (checks.some((c) => c.status === 'warn')) return 'warn';
+  return 'pass';
+}

package/src/components/validation/index.ts

@@ -0,0 +1,36 @@
+/**
+ * @startsimpli/ui validation toolkit (768w.16.10.1).
+ *
+ * Surfaces a Foundry tenant's machine review of AI-generated content — the AI
+ * judge verdict plus deterministic auto-checks — as a pass/warn/fail checklist,
+ * and RECOMPUTES the deterministic checks over the reviewer's *edited* content
+ * (so validation tracks the current draft, not the stale original).
+ *
+ * `checks.ts` is pure + framework-free (importable in a Node/LLM/n8n context);
+ * `ValidationChecklist` is presentational + BYO-data. Light-weight (React +
+ * lucide only), so it rides the main components barrel like the health blocks —
+ * no dedicated subpath (unlike document-editor, which is subpathed only because
+ * it drags react-markdown).
+ */
+export {
+  runContentChecks,
+  overallStatus,
+  wordCount,
+  tagCount,
+  extractUrls,
+  hostOf,
+  DEFAULT_HYPE_WORDS,
+  type ContentCheck,
+  type ContentFields,
+  type ContentChecksConfig,
+  type CheckStatus,
+  type Band,
+} from './checks';
+
+export { ValidationChecklist } from './ValidationChecklist';
+export type {
+  ValidationChecklistProps,
+  JudgeVerdict,
+  JudgeIssue,
+  ValidationOverride,
+} from './ValidationChecklist';