@anthusai/papyrus 2.0.3 → 3.1.0

package/components/use-editorial-checks.ts

@@ -0,0 +1,131 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import {
+  feedbackFor,
+  publishWarnings,
+  type EditorialCheckResult,
+  type EditorialFinding,
+  type FeedbackDecision,
+  type RewriteResult,
+  type Span,
+} from "../lib/editorial-checks";
+import type { EditorialChecksBackend } from "../lib/editorial-checks-backend";
+import { DEFAULT_EDITORIAL_SETTINGS, type EditorialSettings } from "../lib/editorial-checks-settings";
+import type { CheckStatus } from "./editorial-findings-panel";
+
+const CHECK_PAUSE_MS = 2000;
+
+/**
+ * Editorial checks for one article body. A result only applies to the exact body
+ * it was computed for: if the editor typed while the check ran, the result is
+ * dropped and the next pause checks again.
+ */
+export function useEditorialChecks({
+  backend,
+  body,
+  section,
+  itemId,
+}: {
+  /** null turns editorial checks off. */
+  backend: EditorialChecksBackend | null;
+  body: string | null;
+  section: string;
+  itemId: string | null;
+}) {
+  const enabled = backend !== null;
+  const [settings, setSettings] = useState<EditorialSettings>(DEFAULT_EDITORIAL_SETTINGS);
+  const [result, setResult] = useState<EditorialCheckResult | null>(null);
+  const [checkedBody, setCheckedBody] = useState<string | null>(null);
+  const [status, setStatus] = useState<CheckStatus>({ state: "idle" });
+  const [dismissed, setDismissed] = useState<Set<string>>(() => new Set());
+  const [activeFindingId, setActiveFindingId] = useState<string | null>(null);
+  const [selection, setSelection] = useState<Span>({ start: 0, end: 0 });
+  const latestBody = useRef(body);
+  latestBody.current = body;
+  const sequence = useRef(0);
+
+  useEffect(() => {
+    if (!enabled) return;
+    backend?.loadSettings().then(({ settings: loaded }) => setSettings(loaded)).catch(() => undefined);
+  }, [backend, enabled]);
+
+  useEffect(() => {
+    if (!enabled || !itemId) return;
+    backend?.dismissedFindingIds(itemId).then(setDismissed).catch(() => undefined);
+  }, [backend, enabled, itemId]);
+
+  const check = useCallback(async () => {
+    const text = latestBody.current;
+    if (!backend || text === null || !text.trim()) return;
+    const run = ++sequence.current;
+    setStatus({ state: "checking" });
+    try {
+      const checked = await backend.check(text, section.trim() || null);
+      if (run !== sequence.current) return;
+      if (latestBody.current !== text) {
+        setStatus({ state: "idle" });
+        return;
+      }
+      setResult(checked);
+      setCheckedBody(text);
+      setStatus({ state: "idle" });
+    } catch (error) {
+      if (run === sequence.current) setStatus({ state: "error", message: error instanceof Error ? error.message : "The check failed." });
+    }
+  }, [backend, section]);
+
+  useEffect(() => {
+    if (!enabled || !settings.checkWhileTyping || body === null || body === checkedBody) return;
+    const timer = window.setTimeout(() => void check(), CHECK_PAUSE_MS);
+    return () => window.clearTimeout(timer);
+  }, [body, check, checkedBody, enabled, settings.checkWhileTyping]);
+
+  const record = useCallback(
+    (finding: EditorialFinding, decision: FeedbackDecision, reason: string | null = null) => {
+      if (!result || checkedBody === null) return;
+      void backend?.recordFeedback(feedbackFor(result, checkedBody, finding, decision, itemId, reason)).catch(() => undefined);
+    },
+    [backend, checkedBody, itemId, result],
+  );
+
+  const dismiss = useCallback(
+    (finding: EditorialFinding, reason: string) => {
+      record(finding, "dismissed", reason);
+      setDismissed((current) => new Set(current).add(finding.id));
+    },
+    [record],
+  );
+
+  const suggest = useCallback(
+    (target: { finding: EditorialFinding } | { selection: Span }, note: string | null): Promise<RewriteResult> =>
+      backend
+        ? backend.suggest(latestBody.current ?? "", section.trim() || null, target, note)
+        : Promise.reject(new Error("Editorial checks are off.")),
+    [backend, section],
+  );
+
+  const current = result && checkedBody === body;
+  return {
+    enabled,
+    settings,
+    result,
+    /** Findings whose spans still match the body on screen. */
+    inlineResult: current ? result : null,
+    status,
+    dismissed,
+    activeFindingId,
+    setActiveFindingId,
+    selection,
+    setSelection,
+    check,
+    suggest,
+    dismiss,
+    accept: (finding: EditorialFinding) => record(finding, "accepted"),
+    fixed: (finding: EditorialFinding) => {
+      record(finding, "fixed");
+      setDismissed((current) => new Set(current).add(finding.id));
+    },
+    openWarnings: enabled && settings.publishWarning && result ? publishWarnings(result.findings, dismissed) : [],
+  };
+}

package/lib/editorial-checks-backend.ts

@@ -0,0 +1,16 @@
+import type { EditorialCheckResult, EditorialFeedbackInput, EditorialFinding, RewriteResult, Span } from "./editorial-checks";
+import type { EditorialSettings } from "./editorial-checks-settings";
+
+/** What the article editor needs from editorial checks: the plugin's GraphQL API, or the demo. */
+export type EditorialChecksBackend = {
+  loadSettings: () => Promise<{ settings: EditorialSettings; exists: boolean }>;
+  dismissedFindingIds: (itemId: string) => Promise<Set<string>>;
+  check: (body: string, section: string | null) => Promise<EditorialCheckResult>;
+  suggest: (
+    body: string,
+    section: string | null,
+    target: { finding: EditorialFinding } | { selection: Span },
+    note: string | null,
+  ) => Promise<RewriteResult>;
+  recordFeedback: (input: EditorialFeedbackInput) => Promise<void>;
+};

package/lib/editorial-checks-client.ts

@@ -0,0 +1,194 @@
+"use client";
+
+import { generateClient } from "aws-amplify/data";
+import type { EditorialCheckResult, EditorialFeedbackInput, EditorialFinding, RewriteResult, Span } from "./editorial-checks";
+import type { EditorialChecksBackend } from "./editorial-checks-backend";
+import { DEFAULT_EDITORIAL_SETTINGS, type EditorialSettings } from "./editorial-checks-settings";
+
+export { DEFAULT_EDITORIAL_SETTINGS, type EditorialSettings };
+
+type GraphQLResult<T> = { data?: T; errors?: { message?: string }[] };
+
+async function call<T>(query: string, variables: Record<string, unknown> = {}): Promise<T> {
+  const client = generateClient({ authMode: "userPool" });
+  const result = (await client.graphql({ query, variables })) as GraphQLResult<T>;
+  if (result.errors?.length) throw new Error(result.errors[0]?.message ?? "Editorial checks request failed.");
+  if (!result.data) throw new Error("Editorial checks returned no data.");
+  return result.data;
+}
+
+/** AWSJSON comes back as a JSON string. */
+function parsed<T>(value: unknown): T {
+  return (typeof value === "string" ? JSON.parse(value) : value) as T;
+}
+
+export async function checkEditorial(body: string, section: string | null): Promise<EditorialCheckResult> {
+  const data = await call<{ checkEditorial: unknown }>(
+    `query CheckEditorial($body: String!, $format: String, $section: String) { checkEditorial(body: $body, format: $format, section: $section) }`,
+    { body, format: "markus", section },
+  );
+  return parsed<EditorialCheckResult>(data.checkEditorial);
+}
+
+export async function suggestRewrites(
+  body: string,
+  section: string | null,
+  target: { finding: EditorialFinding } | { selection: Span },
+  note: string | null,
+): Promise<RewriteResult> {
+  const data = await call<{ suggestEditorialRewrite: unknown }>(
+    `query SuggestEditorialRewrite($body: String!, $format: String, $section: String, $finding: AWSJSON, $selection: AWSJSON, $note: String) {
+      suggestEditorialRewrite(body: $body, format: $format, section: $section, finding: $finding, selection: $selection, note: $note)
+    }`,
+    {
+      body,
+      format: "markus",
+      section,
+      finding: "finding" in target ? JSON.stringify(target.finding) : null,
+      selection: "selection" in target ? JSON.stringify(target.selection) : null,
+      note,
+    },
+  );
+  return parsed<RewriteResult>(data.suggestEditorialRewrite);
+}
+
+export async function recordFeedback(input: EditorialFeedbackInput): Promise<void> {
+  await call(
+    `mutation CreateEditorialFeedback($input: CreateEditorialFeedbackInput!) { createEditorialFeedback(input: $input) { id } }`,
+    { input },
+  );
+}
+
+export async function dismissedFindingIds(itemId: string): Promise<Set<string>> {
+  const ids = new Set<string>();
+  let nextToken: string | null | undefined;
+  do {
+    const data = await call<{ listEditorialFeedbackByItem: { items: { findingId: string; decision: string }[]; nextToken?: string | null } }>(
+      `query ListEditorialFeedbackByItem($itemId: String!, $nextToken: String) {
+        listEditorialFeedbackByItem(itemId: $itemId, limit: 500, nextToken: $nextToken) { items { findingId decision } nextToken }
+      }`,
+      { itemId, nextToken },
+    );
+    for (const item of data.listEditorialFeedbackByItem.items) if (item.decision === "dismissed") ids.add(item.findingId);
+    nextToken = data.listEditorialFeedbackByItem.nextToken;
+  } while (nextToken);
+  return ids;
+}
+
+// --- administration ---------------------------------------------------------------
+
+export type EditorialPolicyRecord = {
+  id: string;
+  policyKey: string;
+  scope: string;
+  version: number;
+  title: string;
+  guidance: string;
+  severity: "info" | "warn" | "error";
+  enabled: boolean;
+  detectors: unknown[];
+  examples: { violates?: string[]; complies?: string[] } | null;
+  rewriteGuidance: string | null;
+  source: string;
+};
+
+const POLICY_FIELDS = "id policyKey scope version title guidance severity enabled detectors examples rewriteGuidance source";
+
+function policyFromRow(row: Record<string, unknown>): EditorialPolicyRecord {
+  return {
+    ...(row as unknown as EditorialPolicyRecord),
+    detectors: parsed<unknown[]>(row.detectors ?? "[]"),
+    examples: row.examples ? parsed<EditorialPolicyRecord["examples"]>(row.examples) : null,
+  };
+}
+
+function policyInput(policy: EditorialPolicyRecord): Record<string, unknown> {
+  return {
+    ...policy,
+    detectors: JSON.stringify(policy.detectors),
+    examples: policy.examples ? JSON.stringify(policy.examples) : null,
+  };
+}
+
+export async function listPolicies(): Promise<EditorialPolicyRecord[]> {
+  const policies: EditorialPolicyRecord[] = [];
+  let nextToken: string | null | undefined;
+  do {
+    const data = await call<{ listEditorialPolicies: { items: Record<string, unknown>[]; nextToken?: string | null } }>(
+      `query ListEditorialPolicies($nextToken: String) { listEditorialPolicies(limit: 500, nextToken: $nextToken) { items { ${POLICY_FIELDS} } nextToken } }`,
+      { nextToken },
+    );
+    policies.push(...data.listEditorialPolicies.items.map(policyFromRow));
+    nextToken = data.listEditorialPolicies.nextToken;
+  } while (nextToken);
+  return policies.sort((a, b) => a.scope.localeCompare(b.scope) || a.title.localeCompare(b.title));
+}
+
+export async function savePolicy(policy: EditorialPolicyRecord, isNew: boolean): Promise<void> {
+  const operation = isNew ? "createEditorialPolicy" : "updateEditorialPolicy";
+  const inputType = isNew ? "CreateEditorialPolicyInput" : "UpdateEditorialPolicyInput";
+  await call(`mutation SavePolicy($input: ${inputType}!) { ${operation}(input: $input) { id } }`, { input: policyInput(policy) });
+}
+
+export async function deletePolicy(id: string): Promise<void> {
+  await call(`mutation DeleteEditorialPolicy($input: DeleteEditorialPolicyInput!) { deleteEditorialPolicy(input: $input) { id } }`, { input: { id } });
+}
+
+export async function loadSettings(): Promise<{ settings: EditorialSettings; exists: boolean }> {
+  const data = await call<{ getEditorialCheckSettings: { settings: unknown } | null }>(
+    `query GetEditorialCheckSettings { getEditorialCheckSettings(id: "settings") { settings } }`,
+  );
+  const stored = data.getEditorialCheckSettings ? parsed<Partial<EditorialSettings>>(data.getEditorialCheckSettings.settings) : {};
+  return {
+    settings: { ...DEFAULT_EDITORIAL_SETTINGS, ...stored, lanes: { ...DEFAULT_EDITORIAL_SETTINGS.lanes, ...(stored.lanes ?? {}) } },
+    exists: data.getEditorialCheckSettings !== null,
+  };
+}
+
+export async function saveSettings(settings: EditorialSettings, exists: boolean): Promise<void> {
+  const operation = exists ? "updateEditorialCheckSettings" : "createEditorialCheckSettings";
+  const inputType = exists ? "UpdateEditorialCheckSettingsInput" : "CreateEditorialCheckSettingsInput";
+  await call(`mutation SaveSettings($input: ${inputType}!) { ${operation}(input: $input) { id } }`, {
+    input: { id: "settings", settings: JSON.stringify(settings) },
+  });
+}
+
+export async function importStarterPack(name: string): Promise<{ created: number; skipped: number }> {
+  const data = await call<{ importEditorialStarterPack: unknown }>(
+    `mutation ImportStarterPack($name: String!) { importEditorialStarterPack(name: $name) }`,
+    { name },
+  );
+  return parsed(data.importEditorialStarterPack);
+}
+
+export async function tryPolicy(policy: Record<string, unknown>, text: string): Promise<EditorialCheckResult> {
+  const data = await call<{ tryEditorialPolicy: unknown }>(
+    `query TryEditorialPolicy($policy: AWSJSON!, $text: String!) { tryEditorialPolicy(policy: $policy, text: $text, format: "markus") }`,
+    { policy: JSON.stringify(policy), text },
+  );
+  return parsed(data.tryEditorialPolicy);
+}
+
+export type DraftedQuestions = { detectors: Record<string, unknown>[]; notes: string[]; model: string };
+
+export async function draftQuestions(title: string, guidance: string): Promise<DraftedQuestions> {
+  const data = await call<{ draftEditorialQuestions: unknown }>(
+    `query DraftEditorialQuestions($title: String!, $guidance: String!) { draftEditorialQuestions(title: $title, guidance: $guidance) }`,
+    { title, guidance },
+  );
+  return parsed(data.draftEditorialQuestions);
+}
+
+export async function recalibrate(): Promise<{ updated: number; detectors: { policyId: string; detectorId: string; labels: number; note?: string }[] }> {
+  const data = await call<{ recalibrateEditorialPolicies: unknown }>(`mutation Recalibrate { recalibrateEditorialPolicies }`);
+  return parsed(data.recalibrateEditorialPolicies);
+}
+
+/** The plugin's GraphQL API, signed in as the editor. */
+export const graphqlEditorialBackend: EditorialChecksBackend = {
+  loadSettings,
+  dismissedFindingIds,
+  check: checkEditorial,
+  suggest: suggestRewrites,
+  recordFeedback,
+};

package/lib/editorial-checks-demo.ts

@@ -0,0 +1,147 @@
+/**
+ * Demo-mode editorial checks: no backend, a few stock phrases, canned rewrites.
+ * The shapes match Limatus results so the editor, the preview marks and the
+ * rewrite flow behave as they do against the real plugin.
+ */
+import type { EditorialCheckResult, EditorialFinding, EditorialSegment, RewriteResult, Span } from "./editorial-checks";
+import type { EditorialChecksBackend } from "./editorial-checks-backend";
+import { DEFAULT_EDITORIAL_SETTINGS } from "./editorial-checks-settings";
+
+type DemoRule = { policyId: string; phrase: RegExp; severity: EditorialFinding["severity"]; message: string; replacement?: string };
+
+const RULES: DemoRule[] = [
+  { policyId: "promotional-language", phrase: /\bgame[- ]changing\b/gi, severity: "warn", message: "Say what changed instead of calling it game-changing." },
+  { policyId: "plain-words", phrase: /\butilize\b/gi, severity: "info", message: "Prefer the plain word.", replacement: "use" },
+  { policyId: "formulaic-openers", phrase: /\bIn today's [a-z-]+ world\b/gi, severity: "info", message: "Formulaic opener: start with the point." },
+];
+
+/** Demo rewrites keyed by a phrase in the target; anything else gets a clearly labelled placeholder. */
+const CANNED: Record<string, string[]> = {
+  "game-changing": ["Our caching layer cuts build times for teams.", "Teams get faster builds from our caching layer."],
+  "Builds finish in 4 minutes": ["Builds now take 4 minutes, down from 9.", "A build takes 4 minutes instead of 9."],
+};
+
+export function demoPlainText(source: string): string {
+  return source
+    .replace(/^#{1,6}\s+/, "")
+    .replace(/!\[([^\]]*)\]\([^)]*\)/g, "$1")
+    .replace(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replace(/\s?\[@[^\]]+\]/g, "")
+    .replace(/(\*\*|__|\*|_|~~|`)/g, "")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+function hash(text: string): string {
+  let value = 0;
+  for (let i = 0; i < text.length; i += 1) value = (value * 31 + text.charCodeAt(i)) >>> 0;
+  return value.toString(16).padStart(8, "0");
+}
+
+/** Paragraph and sentence segments of a body, by blank lines and sentence-ending punctuation. */
+export function demoSegments(body: string): EditorialSegment[] {
+  const segments: EditorialSegment[] = [{ id: "doc", kind: "document", start: 0, end: body.length, textHash: hash(body) }];
+  const fence = /^(```|~~~)/;
+  let inFence = false;
+  for (const match of body.matchAll(/[^\n]+(?:\n[^\n]+)*/g)) {
+    const raw = match[0];
+    const start = match.index ?? 0;
+    if (fence.test(raw.trim())) inFence = !inFence;
+    if (inFence || fence.test(raw.trim()) || /^(:::|::|>|\||---)/.test(raw.trim())) continue;
+    const block = raw.trim().startsWith("#") ? "heading" : /^([-*+]|\d+\.)\s/.test(raw.trim()) ? "listItem" : "paragraph";
+    const sourceStart = start + raw.length - raw.replace(/^(#{1,6}|[-*+]|\d+\.)\s+/, "").length;
+    const text = demoPlainText(raw);
+    const paragraphId = `p-${hash(text)}`;
+    segments.push({ id: paragraphId, kind: "paragraph", block, start: sourceStart, end: start + raw.length, textHash: hash(text), text });
+    const sentencePattern = /[^.!?]+[.!?]+(?=\s|$)|[^.!?]+$/g;
+    for (const sentence of body.slice(sourceStart, start + raw.length).matchAll(sentencePattern)) {
+      const leading = sentence[0].length - sentence[0].trimStart().length;
+      const sStart = sourceStart + (sentence.index ?? 0) + leading;
+      const sText = sentence[0].trim();
+      if (!sText) continue;
+      segments.push({
+        id: `s-${hash(sText)}`,
+        kind: "sentence",
+        block,
+        parentId: paragraphId,
+        start: sStart,
+        end: sStart + sText.length,
+        textHash: hash(sText),
+        text: demoPlainText(sText),
+      });
+    }
+  }
+  return segments;
+}
+
+export function demoCheck(body: string): EditorialCheckResult {
+  const segments = demoSegments(body);
+  const sentences = segments.filter((segment) => segment.kind === "sentence");
+  const findings: EditorialFinding[] = [];
+  for (const rule of RULES) {
+    for (const match of body.matchAll(rule.phrase)) {
+      const start = match.index ?? 0;
+      const end = start + match[0].length;
+      const sentence = sentences.find((segment) => segment.start <= start && end <= segment.end);
+      if (!sentence) continue;
+      findings.push({
+        id: `f-${hash(`${rule.policyId}|${sentence.text}|${match[0]}`)}${hash(String(start)).slice(0, 8)}`,
+        policyId: rule.policyId,
+        policyVersion: 1,
+        detectorId: `${rule.policyId}-demo`,
+        lane: "rules",
+        severity: rule.severity,
+        status: "violation",
+        segmentId: sentence.id,
+        span: { start, end },
+        excerpt: match[0],
+        excerptText: match[0],
+        message: rule.message,
+        ...(rule.replacement ? { replacement: rule.replacement } : {}),
+      });
+    }
+  }
+  return {
+    schemaVersion: 1,
+    offsetUnit: "utf16",
+    document: { hash: `demo:${hash(body)}`, length: body.length },
+    pack: { packId: "demo", version: "1" },
+    segments,
+    protected: [],
+    findings: findings.sort((a, b) => a.span.start - b.span.start),
+    coverage: [],
+    lanes: { rules: { status: "ran", detectors: RULES.length }, classifier: { status: "disabled" } },
+  };
+}
+
+export function demoSuggest(body: string, target: { finding: EditorialFinding } | { selection: Span }): RewriteResult {
+  let span: Span;
+  if ("finding" in target) {
+    const sentence = demoSegments(body).find((s) => s.kind === "sentence" && s.start <= target.finding.span.start && target.finding.span.end <= s.end);
+    span = sentence ? { start: sentence.start, end: sentence.end } : target.finding.span;
+  } else {
+    span = target.selection;
+  }
+  const excerpt = body.slice(span.start, span.end);
+  const replacements = Object.entries(CANNED).find(([phrase]) => excerpt.includes(phrase))?.[1] ?? [`${demoPlainText(excerpt)} (demo rewrite)`];
+  return {
+    target: { ...("finding" in target ? { findingId: target.finding.id } : {}), span, excerpt },
+    model: "demo",
+    options: replacements.map((replacement, index) => ({
+      id: `o-demo-${index}`,
+      span,
+      replacement,
+      rationale: index === 0 ? "Says what changed, plainly." : "An alternative phrasing.",
+      factVerificationRequired: false,
+      unresolvedQuestions: [],
+    })),
+  };
+}
+
+export const demoEditorialBackend: EditorialChecksBackend = {
+  loadSettings: async () => ({ settings: DEFAULT_EDITORIAL_SETTINGS, exists: false }),
+  dismissedFindingIds: async () => new Set(),
+  check: async (body) => demoCheck(body),
+  suggest: async (body, _section, target) => demoSuggest(body, target),
+  recordFeedback: async () => undefined,
+};

package/lib/editorial-checks-settings.ts

@@ -0,0 +1,24 @@
+/** Runtime settings for editorial checks, stored in EditorialCheckSettings (id "settings"). */
+export type EditorialSettings = {
+  lanes: { rules: boolean; classifier: boolean };
+  classifierModel: string;
+  rewriteModel: string;
+  deadlineSeconds: number;
+  maxInputTokens: number;
+  maxExamplesPerQuestion: number;
+  guidance: string;
+  publishWarning: boolean;
+  checkWhileTyping: boolean;
+};
+
+export const DEFAULT_EDITORIAL_SETTINGS: EditorialSettings = {
+  lanes: { rules: true, classifier: true },
+  classifierModel: "jev-latest",
+  rewriteModel: "gpt-6-luna",
+  deadlineSeconds: 20,
+  maxInputTokens: 500000,
+  maxExamplesPerQuestion: 4,
+  guidance: "",
+  publishWarning: true,
+  checkWhileTyping: true,
+};