@glw907/cairn-cms 0.59.0 → 0.60.1

package/src/lib/components/editor-tidy.ts

@@ -0,0 +1,241 @@
+// The tidy apply primitives (spec 2.5, Task 14). The author's original stays in the buffer until they
+// accept: tidy never overwrites the document and asks for an undo. A StateField holds the change set
+// and each change's disposition, and a decoration plugin shows the proposed edits IN PLACE over the
+// untouched source. An insertion renders as a mark/widget showing the new text in --color-positive-ink
+// (the inserted text is decoration CONTENT, never buffer text); a deletion renders as a strike-through
+// over the original run in --cairn-error-ink (reserved for tidy deletions). The author sees exactly
+// what tidy wants to remove, which is the safety contract.
+//
+// Client-only like editor-placeholder and editor-media: MarkdownEditor reaches this through a dynamic
+// import, so the static @codemirror imports never enter a server bundle (the editor-boundary test's
+// DYNAMIC_ONLY list names this file). The architecture mirrors editor-placeholder: a StateField over
+// StateEffects, with positions mapped across doc changes so an accepted change shifts the others.
+//
+// Accept lands in ONE batched transaction. accept-fixes collects every named change into a single
+// view.dispatch({ changes }), so the whole edit is one undoable step (the session-level "Undo tidy").
+// accept-one dispatches that change alone; reject-one and reject-all change no text, leaving the
+// original byte-identical.
+
+import { Decoration, EditorView, WidgetType, type DecorationSet } from '@codemirror/view';
+import { StateEffect, StateField, RangeSet, type Extension, type Range } from '@codemirror/state';
+import type { Change } from './tidy-diff.js';
+
+/** A change plus its live disposition and current mapped span. `pending` is undecided-in-the-buffer:
+ *  it still carries decorations. `accepted` has been written (its edit dispatched), so it carries no
+ *  decoration. `rejected` was dropped, so it also carries no decoration and never writes. The `from`
+ *  and `to` are the change's current offsets, mapped across every accepted edit since tidy opened. */
+interface TidyEntry {
+	index: number;
+	from: number;
+	to: number;
+	replacement: string;
+	status: 'pending' | 'accepted' | 'rejected';
+}
+
+/** The tidy state: the entry per change keyed by its stable index. Empty when tidy is not open. */
+interface TidyState {
+	entries: Map<number, TidyEntry>;
+}
+
+// The effects that drive the field. enter seeds the change set (tidy opened); accept marks one or many
+// changes accepted (their edits ride the SAME transaction); reject marks changes rejected; clear empties
+// the set (tidy closed or reject-all). Accept and reject carry the index list so one effect covers the
+// bulk action.
+const enterTidy = StateEffect.define<Change[]>();
+const markAccepted = StateEffect.define<number[]>();
+const markRejected = StateEffect.define<number[]>();
+const clearTidy = StateEffect.define<void>();
+
+// The deletion widget: a zero-width marker is not enough, since the deletion's original text stays in
+// the buffer; the strike-through mark below carries the visible deletion. This widget renders the small
+// non-color marker that pairs with the color, so the deletion reads without relying on hue (WCAG 1.4.1).
+// It sits at the start of the deleted run.
+class DeletionMarkerWidget extends WidgetType {
+	eq(other: WidgetType): boolean {
+		return other instanceof DeletionMarkerWidget;
+	}
+	toDOM(): HTMLElement {
+		const span = document.createElement('span');
+		span.className = 'cm-cairn-tidy-del-marker';
+		span.setAttribute('aria-hidden', 'true');
+		span.textContent = '';
+		return span;
+	}
+	ignoreEvent(): boolean {
+		return true;
+	}
+}
+
+// The insertion widget: the proposed new text shown as decoration CONTENT after the change's point in
+// the buffer, so the source is untouched. It carries the addition color and a leading marker glyph so
+// the insertion reads without hue alone. A pure insertion (from === to) and a replacement both render
+// their insertion this way; the replacement also strikes the original run through the deletion mark.
+class InsertionWidget extends WidgetType {
+	constructor(readonly text: string) {
+		super();
+	}
+	eq(other: WidgetType): boolean {
+		return other instanceof InsertionWidget && other.text === this.text;
+	}
+	toDOM(): HTMLElement {
+		const span = document.createElement('span');
+		span.className = 'cm-cairn-tidy-ins';
+		span.setAttribute('aria-hidden', 'true');
+		span.textContent = this.text;
+		return span;
+	}
+	ignoreEvent(): boolean {
+		return true;
+	}
+}
+
+// Build the decoration set for the pending entries. A deletion (a non-empty span) draws a strike-through
+// mark over its run plus a leading marker widget. An insertion (replacement text) draws an insertion
+// widget at the change's end point. A replacement does both: the original strikes through and the new
+// text shows beside it. RangeSet requires ascending, side-ordered ranges, so the ranges are sorted.
+function buildDecorations(state: TidyState): DecorationSet {
+	const ranges: Range<Decoration>[] = [];
+	for (const e of state.entries.values()) {
+		if (e.status !== 'pending') continue;
+		if (e.to > e.from) {
+			// A deletion run: strike it through, and mark its start.
+			ranges.push(Decoration.widget({ widget: new DeletionMarkerWidget(), side: -1 }).range(e.from));
+			ranges.push(Decoration.mark({ class: 'cm-cairn-tidy-del' }).range(e.from, e.to));
+		}
+		if (e.replacement.length > 0) {
+			// The proposed insertion, shown as decoration content after the (possibly struck) original.
+			ranges.push(Decoration.widget({ widget: new InsertionWidget(e.replacement), side: 1 }).range(e.to));
+		}
+	}
+	// Sort by from, then by startSide so a -1 marker precedes the run it leads and a +1 insertion follows.
+	ranges.sort((a, b) => a.from - b.from || a.value.startSide - b.value.startSide);
+	return RangeSet.of(ranges, true);
+}
+
+const tidyField = StateField.define<TidyState>({
+	create() {
+		return { entries: new Map() };
+	},
+	update(value, tr) {
+		let entries = value.entries;
+		let changed = false;
+
+		// Map every entry's span across a doc change (an accepted edit) so the remaining pending changes
+		// shift with the text rather than stranding on stale offsets.
+		if (tr.docChanged && entries.size > 0) {
+			const next = new Map<number, TidyEntry>();
+			for (const [i, e] of entries) {
+				next.set(i, {
+					...e,
+					from: tr.changes.mapPos(e.from, 1),
+					to: tr.changes.mapPos(e.to, -1),
+				});
+			}
+			entries = next;
+			changed = true;
+		}
+
+		for (const effect of tr.effects) {
+			if (effect.is(enterTidy)) {
+				const next = new Map<number, TidyEntry>();
+				for (const c of effect.value) {
+					next.set(c.index, { index: c.index, from: c.from, to: c.to, replacement: c.replacement, status: 'pending' });
+				}
+				entries = next;
+				changed = true;
+			} else if (effect.is(clearTidy)) {
+				entries = new Map();
+				changed = true;
+			} else if (effect.is(markAccepted)) {
+				const next = new Map(entries);
+				for (const i of effect.value) {
+					const e = next.get(i);
+					if (e) next.set(i, { ...e, status: 'accepted' });
+				}
+				entries = next;
+				changed = true;
+			} else if (effect.is(markRejected)) {
+				const next = new Map(entries);
+				for (const i of effect.value) {
+					const e = next.get(i);
+					if (e) next.set(i, { ...e, status: 'rejected' });
+				}
+				entries = next;
+				changed = true;
+			}
+		}
+
+		if (!changed) return value;
+		return { entries };
+	},
+	provide: (f) => EditorView.decorations.from(f, (v) => buildDecorations(v)),
+});
+
+/** The api the host drives over one editor view (spec 2.5). Mirrors imagePlaceholderApi: the host
+ *  registers it through registerTidy, and the review surface calls it as the author works the list.
+ *  Every accept lands as a CodeMirror transaction; reject and reject-all write no text. */
+export interface TidyApi {
+	/** Open tidy with the validated change set: seed the field, show the decorations. The buffer is
+	 *  untouched; the originals stay until an accept writes. */
+	enter(changes: Change[]): void;
+	/** Accept one change: dispatch its replacement over its current span in one transaction and mark it
+	 *  accepted. The other pending changes map across the edit. */
+	acceptOne(index: number): void;
+	/** Reject one change: mark it rejected so its decorations clear, leaving the original untouched. */
+	rejectOne(index: number): void;
+	/** Accept many changes (the bulk action) in ONE transaction: the whole edit is one undoable step.
+	 *  The caller passes ONLY the indexes it has decided to keep; this never sweeps an index the caller
+	 *  did not name, which is how Accept-fixes confines itself to objective hunks. */
+	acceptMany(indexes: number[]): void;
+	/** Reject every remaining pending change, leaving the document byte-identical. */
+	rejectAll(): void;
+	/** Close tidy: clear the field and the decorations. The buffer holds whatever the accepts wrote. */
+	exit(): void;
+}
+
+/** The tidy extension: the StateField holding the change set and its decorations. The host adds it to
+ *  the initial editor state (in its own compartment beside media and folding), then builds the driving
+ *  api with tidyApi once the view exists. */
+export function cairnTidy(): Extension {
+	return tidyField;
+}
+
+/** Build the api that drives tidy against one editor view. The host registers it through registerTidy;
+ *  the review surface calls enter, the per-hunk and bulk accept/reject, and exit. */
+export function tidyApi(view: EditorView): TidyApi {
+	// Dispatch the named changes' replacements over their CURRENT mapped spans in one transaction, mark
+	// them accepted, and let the field map any remaining pending entries. The changes are read from the
+	// field so they carry the live offsets, and they are sorted ascending (CodeMirror requires it).
+	const applyIndexes = (indexes: number[]) => {
+		const entries = view.state.field(tidyField).entries;
+		const specs = indexes
+			.map((i) => entries.get(i))
+			.filter((e): e is TidyEntry => !!e && e.status === 'pending')
+			.sort((a, b) => a.from - b.from)
+			.map((e) => ({ from: e.from, to: e.to, insert: e.replacement }));
+		if (specs.length === 0) return;
+		view.dispatch({ changes: specs, effects: markAccepted.of(indexes) });
+	};
+
+	return {
+		enter(changes) {
+			view.dispatch({ effects: enterTidy.of(changes) });
+		},
+		acceptOne(index) {
+			applyIndexes([index]);
+		},
+		rejectOne(index) {
+			view.dispatch({ effects: markRejected.of([index]) });
+		},
+		acceptMany(indexes) {
+			applyIndexes(indexes);
+		},
+		rejectAll() {
+			const indexes = [...view.state.field(tidyField).entries.keys()];
+			view.dispatch({ effects: markRejected.of(indexes) });
+		},
+		exit() {
+			view.dispatch({ effects: clearTidy.of() });
+		},
+	};
+}

package/src/lib/components/index.ts

@@ -7,6 +7,7 @@ export { default as ConfirmPage } from './ConfirmPage.svelte';
 export { default as CsrfField } from './CsrfField.svelte';
 export { default as ConceptList } from './ConceptList.svelte';
 export { default as CairnMediaLibrary } from './CairnMediaLibrary.svelte';
+export { default as CairnTidySettings } from './CairnTidySettings.svelte';
 export { default as EditPage } from './EditPage.svelte';
 export { default as ManageEditors } from './ManageEditors.svelte';
 export { default as MarkdownEditor } from './MarkdownEditor.svelte';

package/src/lib/components/markdown-directives.ts

@@ -262,6 +262,41 @@ export function markerPrefix(line: string): string | null {
   return m ? m[0] : null;
 }
 
+// A YAML-frontmatter fence: exactly three dashes on their own line, no leading whitespace. The
+// base markdown grammar does not parse frontmatter, so this line-based check is the single source
+// of the region. The strict shape (line start, three dashes, line end) is what separates a leading
+// frontmatter fence from a body `---` thematic break, which carries surrounding prose or blank
+// lines and so never sits on line 0.
+const FRONTMATTER_FENCE = /^---$/;
+
+/**
+ * The frontmatter block at the very top of the document, as absolute character offsets, or null
+ * when there is none. The block must open with an exact `---` on the first line and close with a
+ * later exact `---` line; a body `---` thematic break (which has prose or blank lines above it) is
+ * never frontmatter, a fence with leading whitespace or blank lines above it does not count, and
+ * an unterminated opening fence returns null.
+ *
+ * The span covers the whole block, both fences included: `from` is the start of the opening `---`
+ * (offset 0) and `to` is the end of the closing `---` line (no trailing newline). So
+ * `text.slice(from, to)` is the entire frontmatter, which is what the spellcheck skip and the tidy
+ * byte-for-byte validator both compare against. This is the single source of the frontmatter region.
+ */
+export function frontmatterSpan(text: string): { from: number; to: number } | null {
+  const lines = text.split('\n');
+  if (lines.length < 2 || !FRONTMATTER_FENCE.test(lines[0]!)) return null;
+  // Walk the offset forward line by line; the opening fence sits at offset 0, and each line costs
+  // its length plus the one newline that joined it. The closing fence's end is its start plus its
+  // own length, which is 3 for an exact `---`.
+  let offset = lines[0]!.length + 1;
+  for (let i = 1; i < lines.length; i++) {
+    if (FRONTMATTER_FENCE.test(lines[i]!)) {
+      return { from: 0, to: offset + lines[i]!.length };
+    }
+    offset += lines[i]!.length + 1;
+  }
+  return null;
+}
+
 /** Inline directive ranges (`:name[...]{...}`) within a line of text. */
 export function findInlineDirectives(text: string): { from: number; to: number }[] {
   const out: { from: number; to: number }[] = [];

package/src/lib/components/objective-errors.ts

@@ -0,0 +1,155 @@
+// cairn-cms: the objective-error layer (spec 1.7). Three deterministic mechanical checks over the
+// prose spans the spellcheck classifier already kept: doubled words, double spaces inside a line,
+// and stray repeated punctuation. No Worker, no dictionary, no `retext` pipeline (that stays out of
+// the client and remains the right tool for a future CI-side prose check). There is NO style or
+// opinion linter here by decision 2; the `retext` passive/simplify/equality/readability plugins are
+// never enabled. This module is pure and CodeMirror-free: text plus prose ranges in, findings (each
+// a flagged range and a single-edit fix) out, so it unit-tests in node. The thin lint-source wiring
+// lives in spellcheck.ts, where the findings join the spellcheck diagnostics on the same locked
+// amber underline.
+import type { Range } from './spellcheck.js';
+
+/** The three objective-error kinds, each its own check. */
+export type ObjectiveErrorKind = 'doubled-word' | 'double-space' | 'repeated-punct';
+
+/** A single deterministic edit that resolves one finding: replace [from, to) with `insert`. The lint
+ *  source turns this into the diagnostic's quick-fix action. */
+export interface ObjectiveFix {
+  from: number;
+  to: number;
+  insert: string;
+}
+
+/** One objective-error finding: the flagged range a reader sees underlined, the error kind, a plain
+ *  message, and the one-edit fix. */
+export interface ObjectiveError {
+  kind: ObjectiveErrorKind;
+  /** The flagged range (absolute document offsets), the span the underline covers. */
+  from: number;
+  to: number;
+  /** A plain message naming the error, so the underline is never the only signal. */
+  message: string;
+  /** The deterministic fix. */
+  fix: ObjectiveFix;
+}
+
+// A word for the doubled-word check, matched the same way the spellcheck extractor matches words:
+// Unicode letters and digits, with an intra-word apostrophe (straight or curly) or hyphen kept so
+// "it's" and "well-known" stay whole. Kept consistent with extractWords so the two surfaces agree on
+// what a word is.
+const WORD = /[\p{L}\p{N}]+(?:[-'’][\p{L}\p{N}]+)*/u;
+
+// A doubled word: a word, then whitespace (a space run or a line break), then a second word. The two
+// words are compared case-insensitively in code rather than with a backreference so the comparison
+// stays explicit. The WORD class is greedy to the boundary, so each side is a whole word and a repeat
+// is never matched mid-word ("the theater" is not a doubled "the"). The match runs only inside one
+// prose span, so two equal words separated by a skipped region never read as a doubled pair.
+const DOUBLED_WORD = new RegExp(`(${WORD.source})(\\s+)(${WORD.source})`, 'gu');
+
+// Two or more spaces NOT at the start of a line (leading indentation is markdown-significant and is
+// left alone). The check is same-line only: \n is not part of the run, so a line break is never
+// collapsed. The run must follow a non-whitespace character on the line, so a space run after leading
+// indentation (a newline or a tab) is never flagged. A run is flagged from its second space, the
+// surplus the fix removes.
+const DOUBLE_SPACE = /[^\s] ( +)/g;
+
+// Stray repeated punctuation: two or more of `!`, `?`, or `,` in a run. The period is deliberately
+// excluded so an ellipsis ("...") is left alone, the most judgment-laden case. The threshold is two:
+// a single mark is correct, two or more of these three is plainly a typo. A mixed run ("?!") is not
+// flagged because it is a legitimate construction; only a run of one identical mark counts.
+const REPEATED_PUNCT = /([!?,])\1+/g;
+
+/** Whether two matched word strings are the same word, case-insensitively. Both are already plain
+ *  word runs from the same WORD pattern, so a locale-insensitive lowercase compare is enough. */
+function sameWord(a: string, b: string): boolean {
+  return a.toLowerCase() === b.toLowerCase();
+}
+
+/** Run the three objective checks over one prose span [from, to), returning every finding with an
+ *  absolute range and fix. The doubled-word check is bounded to this span so a repeat that straddles
+ *  a skipped region is never matched. */
+function checkSpan(text: string, from: number, to: number): ObjectiveError[] {
+  const out: ObjectiveError[] = [];
+  const slice = text.slice(from, to);
+
+  // 1. Doubled words. lastIndex stepping handles overlapping triples ("the the the") by restarting
+  //    the scan at the second word, so each adjacent pair is examined.
+  DOUBLED_WORD.lastIndex = 0;
+  let dw: RegExpExecArray | null;
+  while ((dw = DOUBLED_WORD.exec(slice)) !== null) {
+    const [whole, first, gap, second] = dw;
+    if (gap === undefined || first === undefined || second === undefined) continue;
+    if (sameWord(first, second)) {
+      const matchStart = from + dw.index;
+      const matchEnd = matchStart + whole.length;
+      // The fix deletes the gap and the second word, leaving the first word alone.
+      const fixFrom = matchStart + first.length;
+      out.push({
+        kind: 'doubled-word',
+        from: matchStart,
+        to: matchEnd,
+        message: `Doubled word \`${first}\`.`,
+        fix: { from: fixFrom, to: matchEnd, insert: '' },
+      });
+    }
+    // Restart at the second word so an overlapping triple is caught as two pairs.
+    DOUBLED_WORD.lastIndex = dw.index + first.length + gap.length;
+  }
+
+  // 2. Double (or more) spaces inside a line, never leading indentation. The capture group is the
+  //    surplus spaces (every space past the first); the fix removes them, collapsing the run to one.
+  DOUBLE_SPACE.lastIndex = 0;
+  let ds: RegExpExecArray | null;
+  while ((ds = DOUBLE_SPACE.exec(slice)) !== null) {
+    const surplus = ds[1];
+    if (surplus === undefined) continue;
+    // The run begins one space after the leading non-space-non-newline character the pattern anchored
+    // on, so the flagged range is the whole space run (the one kept space plus the surplus).
+    const runStart = from + ds.index + 1;
+    const runEnd = runStart + 1 + surplus.length;
+    out.push({
+      kind: 'double-space',
+      from: runStart,
+      to: runEnd,
+      message: 'Repeated space.',
+      fix: { from: runStart + 1, to: runEnd, insert: '' },
+    });
+  }
+
+  // 3. Stray repeated punctuation (`!`, `?`, `,`), collapsed to one. The period is excluded so an
+  //    ellipsis is never touched.
+  REPEATED_PUNCT.lastIndex = 0;
+  let rp: RegExpExecArray | null;
+  while ((rp = REPEATED_PUNCT.exec(slice)) !== null) {
+    const mark = rp[1];
+    if (mark === undefined) continue;
+    const runStart = from + rp.index;
+    const runEnd = runStart + rp[0].length;
+    out.push({
+      kind: 'repeated-punct',
+      from: runStart,
+      to: runEnd,
+      message: `Repeated \`${mark}\`.`,
+      // Keep the first mark, delete the rest.
+      fix: { from: runStart + 1, to: runEnd, insert: '' },
+    });
+  }
+
+  return out;
+}
+
+/**
+ * Every objective-error finding across the given prose spans. The spans are the same keep ranges the
+ * spellcheck classifier produced (via {@link classifyProse}), so an error inside code, a URL,
+ * frontmatter, or directive machinery is never flagged. Each finding carries an absolute range and a
+ * single-edit fix. Deterministic and CodeMirror-free, so the unit test asserts the findings without a
+ * browser or a Worker. The findings are returned in document order across the spans.
+ */
+export function objectiveErrors(text: string, spans: Range[]): ObjectiveError[] {
+  const out: ObjectiveError[] = [];
+  for (const span of spans) {
+    out.push(...checkSpan(text, span.from, span.to));
+  }
+  out.sort((a, b) => a.from - b.from || a.to - b.to);
+  return out;
+}