Skip to content

Garry's Opinionated OpenClaw/Hermes Agent Brain

TypeScript
16.0 KB
Raw Blame
/**
 * Content Tier 1 rules over both sections of a page (#6188): `header_alias`
 * and `column_default` (header level), the cell rules in rules.ts, and
 * prior-aware `renumber` across body and timeline. Of two rows sharing a
 * number, the one matching the stored row keeps it; otherwise a row in a
 * fence that parses clean keeps it (Invariant 0), and the first occurrence
 * only breaks the remaining tie. A `superseded by #N` reference that names a
 * shared number is ambiguous, except inside a fence `merge_fences` built
 * (#6377): there it names its own before-fence's row N and follows that
 * row's new number (or the number of the kept row a dropped duplicate N
 * equalled).
 *
 * Cells are edited in place by source span; a row is re-rendered only when
 * its header is rewritten, and then every cell keeps its source text and only
 * moves into canonical order. Nothing is re-rendered through
 * `renderFactsTable` / `renderTakesFence`.
 */
import { parseFactsFence } from '../facts-fence.ts';
import { stripStrikethrough } from '../fence-shared.ts';
import { parseTakesFence } from '../takes-fence.ts';
import type { MergeOrigins } from './merge.ts';
import { planRowRules, type CellText, type RowPlan } from './rules.ts';
import { extractRawRows, rowNumOf, type RawFence, type RawRow, type RawSection } from './raw-rows.ts';
import { ALLOWED, BASE_WIDTH, canonicalColumn, CANONICAL_HEADER, collapse, COLUMN_DEFAULTS, COLUMNS, supersededRef, WIDE_WIDTH } from './schema.ts';
import { headerlessMisfit } from './stray-cells.ts';
import { applyEdits, fenceBlocked, type Edit } from './structure.ts';
import type { FenceCtx, FenceFix, FenceIssue, FenceKind, FenceReason, FenceSection } from './types.ts';

export interface ContentResult {
  texts: Record<FenceSection, string>;
  fixes: FenceFix[];
  residual: FenceIssue[];
}

/** Header rewrite plan for a fence whose header is out of canonical order. */
interface Rewrite {
  target: readonly string[];
  defaults: string[];
}

interface RowWork {
  fence: RawFence;
  row: RawRow;
  num: number | null;
  plan: RowPlan | null;
  /** May take a new number (aligned, in a workable fence, not hidden). */
  eligible: boolean;
  needsNumber: boolean;
  /** The row's fence parses with no warning (Invariant 0 prefers to leave it alone). */
  clean: boolean;
  /** Index of the before fence the row came from, when `merge_fences` built its fence; null otherwise. */
  origin: number | null;
  newNum?: number;
  /** The `superseded by #N` reference the row carries now names this number. */
  refTo?: number;
}

interface FenceWork {
  fence: RawFence;
  rewrite: Rewrite | null;
  rows: RowWork[];
}

interface Pass {
  ctx: FenceCtx;
  fixes: FenceFix[];
  residual: FenceIssue[];
  edits: Record<FenceSection, Edit[]>;
  works: FenceWork[];
  /** All rows of each kind in page order (body first), workable or not. */
  rows: Record<FenceKind, RowWork[]>;
  merges: readonly MergeOrigins[];
  /** Next number to hand out; one counter for both kinds, so no new number repeats on the page. */
  next: number | null;
  nextNumber: () => number;
}

const REPORTED: ReadonlySet<FenceReason> = new Set(['row_before_header', 'no_header', 'short_row', 'extra_cells']);

/** Plan and apply the content rules; `nextNumber` is called only when a row needs a new number. */
export function contentPass(texts: Record<FenceSection, string>, ctx: FenceCtx, nextNumber: () => number, merges: readonly MergeOrigins[] = []): ContentResult {
  const pass: Pass = { ctx, fixes: [], residual: [], edits: { body: [], timeline: [] }, works: [], rows: { facts: [], takes: [] }, next: null, nextNumber, merges };
  for (const section of ['body', 'timeline'] as const) planSection(pass, extractRawRows(texts[section], section));
  for (const kind of ['facts', 'takes'] as const) renumber(pass, kind);
  for (const work of pass.works) emitFence(pass, work);
  return {
    texts: { body: applyEdits(texts.body, pass.edits.body), timeline: applyEdits(texts.timeline, pass.edits.timeline) },
    fixes: pass.fixes,
    residual: pass.residual,
  };
}

function issueAt(fence: RawFence, reason: FenceReason, line: number | null, row: number | null = null, column: string | null = null, allowed?: readonly string[]): FenceIssue {
  const out: FenceIssue = { fence: fence.kind, section: fence.section, row, column, line, reason };
  return allowed ? { ...out, allowed } : out;
}

function planSection(pass: Pass, raw: RawSection): void {
  pass.residual.push(...raw.issues);
  for (const fence of raw.fences) {
    if (!fence.primary) continue;
    pass.residual.push(...fence.issues.filter(i => i.reason === 'repeated_marker'));
    const balanced = fence.end !== null && !fence.begin.nearMiss && !fence.end.nearMiss;
    const workable = balanced && !fenceBlocked(raw, fence) && fenceWorkable(pass, fence);
    if (balanced) pass.residual.push(...fence.issues.filter(i => REPORTED.has(i.reason)), ...headerlessIssues(fence));
    const rewrite = workable && fence.needsRewrite ? planRewrite(fence) : null;
    const clean = (fence.kind === 'facts' ? parseFactsFence(raw.text) : parseTakesFence(raw.text)).warnings.length === 0;
    const merged = mergeOf(pass, fence);
    const rows = fence.rows.map(row => rowWork(pass, fence, row, workable, clean, merged?.origins[row.occurrence] ?? null));
    pass.rows[fence.kind].push(...rows);
    if (workable) pass.works.push({ fence, rewrite, rows });
  }
}

/** Rows of a fence with no header that cannot be read by position (stray-cells.ts), held as manual. */
function headerlessIssues(fence: RawFence): FenceIssue[] {
  return fence.rows.flatMap(row => {
    const misfit = headerlessMisfit(fence, row);
    if (!misfit) return [];
    return [misfit === 'claim_split' ? issueAt(fence, misfit, row.line, rowNumOf(fence, row), 'kind', ALLOWED[fence.kind].kind) : issueAt(fence, misfit, row.line, rowNumOf(fence, row))];
  });
}

/** A balanced fence the content rules may edit; reports why not otherwise. */
function fenceWorkable(pass: Pass, fence: RawFence): boolean {
  if (!fence.header) return false;
  const headerLine = fence.header.line;
  if (fence.kind === 'facts' && takesShaped(fence)) {
    pass.residual.push(issueAt(fence, 'takes_in_facts', headerLine));
    return false;
  }
  if (!fence.needsRewrite) return true;
  if (fence.columns.some(c => c === null)) {
    pass.residual.push(issueAt(fence, 'header_unmapped', headerLine, null, null, COLUMNS[fence.kind]));
    return false;
  }
  const missing = fence.kind === 'takes' ? (['who', 'weight'] as const).filter(c => !fence.columns.includes(c)) : [];
  for (const column of missing) pass.residual.push(issueAt(fence, column === 'who' ? 'holder_missing' : 'weight_missing', headerLine, null, column));
  return !missing.length && fence.rows.every(r => r.beforeHeader || r.shape === 'ok');
}

/** A takes table (a holder column, no facts-only columns) inside a facts fence. */
function takesShaped(fence: RawFence): boolean {
  const cells = fence.header!.cells.map(c => c.text);
  const facts = cells.map(c => canonicalColumn('facts', c));
  return cells.some(c => canonicalColumn('takes', c) === 'who') && !facts.includes('visibility') && !facts.includes('notability');
}

function planRewrite(fence: RawFence): Rewrite {
  const { kind } = fence;
  const wide = fence.columns.some(c => c !== null && COLUMNS[kind].indexOf(c) >= BASE_WIDTH[kind]);
  // #6385: a header naming a column past the typed layout (facts `attributed_to`) keeps it.
  const width = fence.columns.some(c => c !== null && COLUMNS[kind].indexOf(c) >= WIDE_WIDTH[kind]) ? COLUMNS[kind].length : wide ? WIDE_WIDTH[kind] : BASE_WIDTH[kind];
  const target = COLUMNS[kind].slice(0, width);
  const defaults = Object.keys(COLUMN_DEFAULTS[kind]).filter(c => !fence.columns.includes(c));
  return { target, defaults };
}

function mergeOf(pass: Pass, fence: RawFence): MergeOrigins | undefined {
  return pass.merges.find(m => m.section === fence.section && m.kind === fence.kind);
}

function rowWork(pass: Pass, fence: RawFence, row: RawRow, workable: boolean, clean: boolean, origin: number | null): RowWork {
  const num = rowNumOf(fence, row);
  const aligned = workable && !row.beforeHeader && row.shape === 'ok';
  const plan = aligned ? planRowRules(fence.kind, cellTexts(row), pass.ctx) : null;
  const hidden = num !== null && (pass.ctx.hiddenRows?.has(num) ?? false);
  const minted = aligned && !fence.columns.includes('#') && fence.needsRewrite;
  return { fence, row, num, plan, eligible: aligned && !hidden, needsNumber: minted || (plan?.badNumber ?? false), clean, origin };
}

function cellTexts(row: RawRow): Map<string, CellText> {
  return new Map([...row.byColumn].map(([column, cell]) => [column, { raw: cell.raw, text: cell.text }]));
}

/** Claim text the stored map is keyed by: strikethrough stripped, whitespace collapsed. */
function claimKey(row: RawRow): string {
  return collapse(stripStrikethrough(row.byColumn.get('claim')?.text ?? '').text);
}

const REF_COLUMN: Record<FenceKind, string> = { facts: 'context', takes: 'source' };

function refOf(kind: FenceKind, w: RowWork): number | null {
  return supersededRef(w.row.byColumn.get(REF_COLUMN[kind])?.text ?? '');
}

function renumber(pass: Pass, kind: FenceKind): void {
  const rows = pass.rows[kind];
  // A reference from outside a merged fence makes any shared number it names ambiguous; a merged row's reference is resolved to its own before fence below.
  const refs = new Set(rows.filter(w => w.origin === null).map(w => refOf(kind, w)).filter(n => n !== null));
  const groups = new Map<number, RowWork[]>();
  for (const w of rows) if (w.num !== null) groups.set(w.num, [...(groups.get(w.num) ?? []), w]);
  const targets = new Map<RowWork, RowWork>();
  for (const w of rows) {
    const num = w.origin === null ? null : refOf(kind, w);
    if (num === null) continue;
    const target = localTarget(pass, kind, w, num, groups);
    if (target === 'ambiguous') pass.residual.push(issueAt(w.fence, 'superseded_ambiguous', w.row.line, num, '#'));
    else if (target) targets.set(w, target);
  }
  for (const [num, group] of groups) {
    if (group.length < 2) continue;
    if (refs.has(num)) {
      for (const w of group) pass.residual.push(issueAt(w.fence, 'superseded_ambiguous', w.row.line, num, '#'));
      continue;
    }
    const stored = pass.ctx.storedRows?.[kind].get(num);
    const keeper = group.find(w => stored !== undefined && claimKey(w.row) === collapse(stored))
      ?? group.find(w => w.clean) ?? group[0]!;
    for (const w of group) {
      if (w === keeper) continue;
      if (w.eligible) w.needsNumber = true;
      else if (pass.ctx.hiddenRows?.has(num)) pass.residual.push(issueAt(w.fence, 'row_collision', w.row.line, num, '#'));
    }
  }
  for (const w of rows) {
    if (!w.needsNumber || !w.eligible) continue;
    pass.next ??= pass.nextNumber();
    w.newNum = pass.next++;
  }
  for (const [w, target] of targets) {
    const final = finalNum(target);
    if (final === null || final === refOf(kind, w)) continue;
    if (!w.plan) {
      pass.residual.push(issueAt(w.fence, 'superseded_ambiguous', w.row.line, refOf(kind, w), '#'));
      continue;
    }
    w.refTo = final;
  }
}

/**
 * The row a merged row's `superseded by #N` names: the one row numbered N of
 * its own before fence, or the kept row a dropped duplicate numbered N of
 * that fence equalled. With neither, N must not be a shared number.
 */
function localTarget(pass: Pass, kind: FenceKind, w: RowWork, num: number, groups: ReadonlyMap<number, RowWork[]>): RowWork | 'ambiguous' | null {
  const merged = mergeOf(pass, w.fence)!;
  const section = pass.rows[kind].filter(r => r.fence.section === w.fence.section);
  const own = section.filter(r => r.origin === w.origin && r.num === num);
  const dropped = merged.dropped.filter(d => d.fence === w.origin && d.num === num).map(d => section[d.keptOccurrence]!);
  const candidates = [...own, ...dropped];
  if (candidates.length > 1) return 'ambiguous';
  if (candidates.length === 1) return candidates[0]!;
  return (groups.get(num)?.length ?? 0) > 1 ? 'ambiguous' : null;
}

/** The reference cell rewritten to the row's new number, on top of any rule change to the same cell. */
function refEdit(w: RowWork, kind: FenceKind): void {
  const column = REF_COLUMN[kind];
  const change = w.plan!.changes.find(c => c.column === column);
  const raw = (change?.raw ?? w.row.byColumn.get(column)?.raw ?? '').replace(/(superseded by #)\d+/i, `$1${w.refTo}`);
  if (change) change.raw = raw;
  else w.plan!.changes.push({ column, raw, class: 'renumber' });
}

/** The number the row was written with (`0` and negatives included), or null when the cell is not numeric or absent. */
function writtenNum(row: RawRow): number | null {
  const n = parseInt(row.byColumn.get('#')?.text ?? '', 10);
  return Number.isFinite(n) ? n : null;
}

function finalNum(w: RowWork): number | null {
  return w.newNum ?? w.num;
}

function emitFence(pass: Pass, work: FenceWork): void {
  const { fence } = work;
  if (work.rewrite) emitRewrite(pass, fence, work.rewrite);
  for (const w of work.rows) {
    if (!w.plan) continue;
    const row = finalNum(w);
    if (w.newNum !== undefined) {
      pass.fixes.push({ fence: fence.kind, section: fence.section, row, column: '#', line: w.row.line, class: 'renumber', from: writtenNum(w.row) });
    }
    if (w.refTo !== undefined) {
      refEdit(w, fence.kind);
      pass.fixes.push({ fence: fence.kind, section: fence.section, row, column: REF_COLUMN[fence.kind], line: w.row.line, class: 'renumber' });
    }
    for (const change of w.plan.changes) {
      if (change.column === 'context' && change.class === 'kind_map') continue;
      if (change.column === REF_COLUMN[fence.kind] && change.class === 'renumber') continue;
      pass.fixes.push({ fence: fence.kind, section: fence.section, row, column: change.column, line: w.row.line, class: change.class });
    }
    for (const i of w.plan.issues) pass.residual.push(issueAt(fence, i.reason, w.row.line, row, i.column, i.allowed));
    if (work.rewrite) pass.edits[fence.section].push(renderRow(w, work.rewrite));
    else pass.edits[fence.section].push(...cellEdits(w));
  }
}

function emitRewrite(pass: Pass, fence: RawFence, rewrite: Rewrite): void {
  const header = fence.header!;
  const text = CANONICAL_HEADER[fence.kind];
  const width = rewrite.target.length;
  const [headerText, sepText] = width > WIDE_WIDTH[fence.kind] ? [text.attributed!, text.attributedSep!]
    : width > BASE_WIDTH[fence.kind] ? [text.wide, text.wideSep] : [text.narrow, text.narrowSep];
  pass.edits[fence.section].push({ start: header.start, end: header.end, text: headerText });
  const sep = fence.separators.find(s => s.line === header.line + 1);
  if (sep) pass.edits[fence.section].push({ start: sep.start, end: sep.end, text: sepText });
  const at = { fence: fence.kind, section: fence.section, row: null, line: header.line };
  pass.fixes.push({ ...at, column: null, class: 'header_alias' });
  for (const column of rewrite.defaults) pass.fixes.push({ ...at, column, class: 'column_default' });
}

/** The row re-rendered in canonical column order from its own source cells. */
function renderRow(w: RowWork, rewrite: Rewrite): Edit {
  const changes = new Map(w.plan!.changes.map(c => [c.column, c.raw]));
  const defaults = COLUMN_DEFAULTS[w.fence.kind];
  const cells = rewrite.target.map(column => {
    if (column === '#' && w.newNum !== undefined) return String(w.newNum);
    return changes.get(column) ?? w.row.byColumn.get(column)?.raw ?? defaults[column] ?? '';
  });
  return { start: w.row.start, end: w.row.end, text: `| ${cells.join(' | ')} |` };
}

/** In-place cell edits; a facts context the row lacks is appended as its last cell. */
function cellEdits(w: RowWork): Edit[] {
  const edits: Edit[] = [];
  const { row } = w;
  const num = row.byColumn.get('#');
  if (w.newNum !== undefined && num) edits.push({ start: num.start, end: num.end, text: String(w.newNum) });
  for (const change of w.plan!.changes) {
    const cell = row.byColumn.get(change.column);
    if (cell) edits.push({ start: cell.start, end: cell.end, text: change.raw });
    else edits.push({ start: row.end, end: row.end, text: row.closed ? ` ${change.raw} |` : ` | ${change.raw}` });
  }
  return edits;
}