components/flag-list/flag-list-model.ts

Functions

Imports

It imports no other module of this repo. Imported by components/flag-list/flag-list.ts.

Source

1// The flag list's data and its pure helpers (flag-list.ts).
2
3export type FlagKind = "blocking" | "advisory";
4export type FlagState = "open" | "resolved";
5// How a resolved flag was closed: fixed, dismissed as not a problem, or by applying its suggestion.
6export type Resolution = "resolved" | "dismissed" | "applied";
7export type AnchorStatus = "found" | "lost" | "none";
8
9export interface FlagAnchor {
10  // The id of the passage in the page (the link is href="#id").
11  id: string;
12  // The quoted words, exactly as they were when the flag was raised. The last known text
13  // when the anchor is lost.
14  quote: string;
15  // A few words either side, to tell one occurrence of the quote from another.
16  before?: string;
17  after?: string;
18  // Used when no current text is given: the server already knows the passage has gone.
19  lost?: boolean;
20  // The link's words. Default "Go to passage".
21  label?: string;
22}
23
24export interface FlagSuggestion {
25  replacement: string;
26  // Who or what suggested it ("Style check", "AI reviewer"). A suggestion never applies itself.
27  by?: string;
28}
29
30export interface Flag {
31  id: string;
32  kind: FlagKind;
33  // What rule fired, in words: "Every factual claim needs a source."
34  cause: string;
35  // What is wrong, in a sentence. The flag's title.
36  message: string;
37  // Who or what raised it.
38  raisedBy?: string;
39  anchor?: FlagAnchor;
40  suggestion?: FlagSuggestion;
41  state: FlagState;
42  resolution?: Resolution;
43  resolvedBy?: string;
44  // An ISO timestamp.
45  resolvedAt?: string;
46}
47
48// ---------------------------------------------------------------------------------------
49// Pure helpers.
50
51const byState = (a: Flag, b: Flag) => Number(a.state === "resolved") - Number(b.state === "resolved");
52
53// Blocking first, then advisory; within each, open flags before resolved ones, in the order given.
54export function groupFlags(flags: readonly Flag[]): { blocking: Flag[]; advisory: Flag[] } {
55  const stable = (kind: FlagKind) =>
56    flags
57      .map((f, i) => [f, i] as const)
58      .filter(([f]) => f.kind === kind)
59      .sort(([a, i], [b, j]) => byState(a, b) || i - j)
60      .map(([f]) => f);
61  return { blocking: stable("blocking"), advisory: stable("advisory") };
62}
63
64export interface FlagCounts {
65  // Open flags by kind.
66  blocking: number;
67  advisory: number;
68  open: number;
69  resolved: number;
70  total: number;
71}
72
73export function countFlags(flags: readonly Flag[]): FlagCounts {
74  const open = flags.filter((f) => f.state === "open");
75  const blocking = open.filter((f) => f.kind === "blocking").length;
76  return { blocking, advisory: open.length - blocking, open: open.length, resolved: flags.length - open.length, total: flags.length };
77}
78
79// "2 blocking, 3 advisory, 4 resolved". With nothing open it says so.
80export function summaryLine(c: FlagCounts): string {
81  if (c.total === 0) return "No flags";
82  if (c.open === 0) return `No open flags, ${c.resolved} resolved`;
83  return `${c.blocking} blocking, ${c.advisory} advisory, ${c.resolved} resolved`;
84}
85
86// Every place the quote occurs in the text, as start offsets.
87function occurrences(text: string, quote: string): number[] {
88  const at: number[] = [];
89  if (!quote) return at;
90  for (let i = text.indexOf(quote); i !== -1; i = text.indexOf(quote, i + 1)) at.push(i);
91  return at;
92}
93
94// The occurrence the flag means: the one whose neighbours match the recorded context, else the first.
95function pick(text: string, a: FlagAnchor, hits: number[]): number {
96  if (hits.length > 1 && (a.before || a.after)) {
97    const fit = hits.find((i) => (!a.before || text.slice(Math.max(0, i - a.before.length), i) === a.before) && (!a.after || text.slice(i + a.quote.length, i + a.quote.length + a.after.length) === a.after));
98    if (fit !== undefined) return fit;
99  }
100  return hits[0] ?? -1;
101}
102
103// Whether the quoted passage is still in the text. "none": the flag is not anchored to text.
104// Without a text, the flag's own `lost` mark is believed.
105export function anchorStatus(flag: Pick<Flag, "anchor">, text?: string): AnchorStatus {
106  const a = flag.anchor;
107  if (!a || !a.quote) return "none";
108  if (text === undefined) return a.lost ? "lost" : "found";
109  return text.includes(a.quote) ? "found" : "lost";
110}
111
112// The text with the suggestion put in place of the quoted passage; null when the flag has no
113// suggestion or its anchor has gone. Pure: it never touches the page.
114export function applySuggestion(text: string, flag: Pick<Flag, "anchor" | "suggestion">): string | null {
115  const a = flag.anchor;
116  if (!a || !flag.suggestion) return null;
117  const i = pick(text, a, occurrences(text, a.quote));
118  if (i < 0) return null;
119  return text.slice(0, i) + flag.suggestion.replacement + text.slice(i + a.quote.length);
120}
121
122// The inverse, for Undo: puts the quote back where the replacement now is. null when the
123// replacement is not there any more (the draft was edited since).
124export function revertSuggestion(text: string, flag: Pick<Flag, "anchor" | "suggestion">): string | null {
125  const a = flag.anchor;
126  const s = flag.suggestion;
127  if (!a || !s || !s.replacement) return null;
128  const i = text.indexOf(s.replacement);
129  if (i < 0) return null;
130  return text.slice(0, i) + a.quote + text.slice(i + s.replacement.length);
131}
132
133// The flags whose suggestion can be applied now: open, with a suggestion, and the passage still there.
134export function appliable(flags: readonly Flag[], text?: string): Flag[] {
135  return flags.filter((f) => f.state === "open" && f.suggestion && anchorStatus(f, text) === "found");
136}