@startsimpli/ui 0.4.52 → 0.4.54

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';