IF Commons GitHub

governance/event

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0002-planning-core FR-005

The events of an item (0037-planning FR-003): each one case of the closed union of fourteen types, with an id, the item it is of, a time and an actor, and the data its source wrote. An event is immutable once built (it is frozen), and the library has no operation that changes or removes one: the history of an item is the set of its events, and its state is a fold of them. makeEvent is the one way to build an event and returns a Result: an event of an agent with no principal, a confirmation by anything but a person and a link of an item to itself are refused.

import { makeEvent } from "./event.ts";
// makeEvent({ id, item, at, actor }, { type: "commented", body: "Seen." }) is a Result of an event

Source: commons/planning/src/governance/event.ts

0 of 22 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

governance.Targettypeno test imports it
type Target = { readonly file?: string; readonly page?: number; readonly quote?: string };

What a record is about: a file, a page and a quoted text (a Web Annotation target).

governance.FindingSourcetypeno test imports it
type FindingSource = { readonly [key: string]: string | number | boolean | null };

What a tool's finding says of where it was found (a SARIF result: the tool, the rule, the file and the line), with any other member the source wrote.

governance.Carriedtypeno test imports it
type Carried = { /** The severity as the source wrote it, where it has more levels than the three of `Severity`. */ … (545 characters)
type Carried = {
  /** The severity as the source wrote it, where it has more levels than the three of `Severity`. */
  readonly sourceSeverity?: string;
  /** The Web Annotation motivation, as a name. */
  readonly motivation?: string;
  readonly blocker?: boolean;
  readonly target?: Target;
  readonly source?: FindingSource;
  readonly priority?: string;
  readonly size?: string;
  readonly goals?: readonly string[];
  readonly engines?: readonly string[];
  readonly cites?: readonly string[];
  readonly evidence?: readonly string[];
};

The fields a source may carry of an item beyond the core, each as the source wrote it (0037-planning FR-046).

governance.OpenedDatatypeno test imports it
type OpenedData = {
  readonly type: "opened";
  readonly kind: ItemKind;
  readonly title: string;
  readonly body: string;
  readonly labels: readonly string[];
  readonly assignees: readonly string[];
  readonly origin: Origin;
  readonly severity?: Severity;
} & Carried;

The opening of an item: its kind, text, labels, assignees and origin, and what the source carried.

governance.EventDatatypeno test imports it
type EventData = | OpenedData | { readonly type: "commented"; readonly body: string } | { readonly type: "edited";… (948 characters)
type EventData =
  | OpenedData
  | { readonly type: "commented"; readonly body: string }
  | { readonly type: "edited"; readonly title?: string; readonly body?: string }
  | { readonly type: "labeled"; readonly add: readonly string[]; readonly remove: readonly string[] }
  | { readonly type: "assigned"; readonly add: readonly string[]; readonly remove: readonly string[] }
  | { readonly type: "severity-set"; readonly severity: Severity }
  | { readonly type: "blocker-set"; readonly blocker: boolean }
  | { readonly type: "started" }
  | { readonly type: "deferred"; readonly until: Day; readonly reason?: string }
  | { readonly type: "closed"; readonly reason: CloseReason }
  | { readonly type: "reopened" }
  | { readonly type: "decided"; readonly verdict: Verdict; readonly note: string }
  | { readonly type: "linked"; readonly change: "add" | "remove"; readonly link: LinkKind; readonly to: ItemId }
  | { readonly type: "confirmed" };

What happened to an item, by its type.

governance.EventHeadtypeno test imports it
type EventHead = { readonly id: EventId; readonly item: ItemId; readonly at: Instant; readonly actor: Actor; readonly external?: readonly ExternalId[] };

What every event has: its id, the item it is of, its time, its actor, and the ids it has in the places it was read from.

governance.ItemEventtypeno test imports it
type ItemEvent = EventHead & { readonly data: EventData };

One event of an item: immutable.

governance.EventProblemtypeno test imports it
type EventProblem =
  | { readonly kind: "actor"; readonly problem: ActorProblem }
  | { readonly kind: "confirmed-by-a-non-person"; readonly actor: string }
  | { readonly kind: "link-to-itself"; readonly item: ItemId };

Why an event is refused.

governance.describeEventProblemfunctionno test imports it
function describeEventProblem(p: EventProblem): string

One sentence for a refusal.

governance.freezeDeepfunctionno test imports it
function freezeDeep<T>(value: T): T

Freezes a value and everything it holds.

governance.makeEventfunctionno test imports it
function makeEvent(head: EventHead, data: EventData): Result<ItemEvent, EventProblem>

The event, built, or why it is refused. The actor is checked as a value that came from outside, whatever its type says.

Targettypeno test imports it
type Target = { readonly file?: string; readonly page?: number; readonly quote?: string };

What a record is about: a file, a page and a quoted text (a Web Annotation target).

FindingSourcetypeno test imports it
type FindingSource = { readonly [key: string]: string | number | boolean | null };

What a tool's finding says of where it was found (a SARIF result: the tool, the rule, the file and the line), with any other member the source wrote.

Carriedtypeno test imports it
type Carried = { /** The severity as the source wrote it, where it has more levels than the three of `Severity`. */ … (545 characters)
type Carried = {
  /** The severity as the source wrote it, where it has more levels than the three of `Severity`. */
  readonly sourceSeverity?: string;
  /** The Web Annotation motivation, as a name. */
  readonly motivation?: string;
  readonly blocker?: boolean;
  readonly target?: Target;
  readonly source?: FindingSource;
  readonly priority?: string;
  readonly size?: string;
  readonly goals?: readonly string[];
  readonly engines?: readonly string[];
  readonly cites?: readonly string[];
  readonly evidence?: readonly string[];
};

The fields a source may carry of an item beyond the core, each as the source wrote it (0037-planning FR-046).

OpenedDatatypeno test imports it
type OpenedData = {
  readonly type: "opened";
  readonly kind: ItemKind;
  readonly title: string;
  readonly body: string;
  readonly labels: readonly string[];
  readonly assignees: readonly string[];
  readonly origin: Origin;
  readonly severity?: Severity;
} & Carried;

The opening of an item: its kind, text, labels, assignees and origin, and what the source carried.

EventDatatypeno test imports it
type EventData = | OpenedData | { readonly type: "commented"; readonly body: string } | { readonly type: "edited";… (948 characters)
type EventData =
  | OpenedData
  | { readonly type: "commented"; readonly body: string }
  | { readonly type: "edited"; readonly title?: string; readonly body?: string }
  | { readonly type: "labeled"; readonly add: readonly string[]; readonly remove: readonly string[] }
  | { readonly type: "assigned"; readonly add: readonly string[]; readonly remove: readonly string[] }
  | { readonly type: "severity-set"; readonly severity: Severity }
  | { readonly type: "blocker-set"; readonly blocker: boolean }
  | { readonly type: "started" }
  | { readonly type: "deferred"; readonly until: Day; readonly reason?: string }
  | { readonly type: "closed"; readonly reason: CloseReason }
  | { readonly type: "reopened" }
  | { readonly type: "decided"; readonly verdict: Verdict; readonly note: string }
  | { readonly type: "linked"; readonly change: "add" | "remove"; readonly link: LinkKind; readonly to: ItemId }
  | { readonly type: "confirmed" };

What happened to an item, by its type.

EventHeadtypeno test imports it
type EventHead = { readonly id: EventId; readonly item: ItemId; readonly at: Instant; readonly actor: Actor; readonly external?: readonly ExternalId[] };

What every event has: its id, the item it is of, its time, its actor, and the ids it has in the places it was read from.

ItemEventtypeno test imports it
type ItemEvent = EventHead & { readonly data: EventData };

One event of an item: immutable.

EventProblemtypeno test imports it
type EventProblem =
  | { readonly kind: "actor"; readonly problem: ActorProblem }
  | { readonly kind: "confirmed-by-a-non-person"; readonly actor: string }
  | { readonly kind: "link-to-itself"; readonly item: ItemId };

Why an event is refused.

describeEventProblemfunctionno test imports it
function describeEventProblem(p: EventProblem): string

One sentence for a refusal.

freezeDeepfunctionno test imports it
function freezeDeep<T>(value: T): T

Freezes a value and everything it holds.

makeEventfunctionno test imports it
function makeEvent(head: EventHead, data: EventData): Result<ItemEvent, EventProblem>

The event, built, or why it is refused. The actor is checked as a value that came from outside, whatever its type says.

Titles, headings, exports, tables, columns and requirements. Esc closes.