IF Commons GitHub

governance/observation

Written to: 1 requirement: 0 proved, 0 partly, 0 failing, 1 with no test recorded. 0003-planning-reconcile FR-001

What a source read (0037-planning FR-008, FR-009, FR-046): an observation is one thing read in one place, with where it was read (a locator), the SHA-256 of the bytes it was read from, a fingerprint of its identity that does not depend on where in the place it is, the content as an observed item and the record as read; a trace is the link from an item to an observation of it, which holds the content last taken (the base of a three-way merge) and whether the thing is present or absent now. Data only.

import type { Observation } from "./observation.ts";
const where = (o: Observation) => o.locator.kind;

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

0 of 20 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.Rawtypeno test imports it
type Raw = null | boolean | number | string | readonly Raw[] | { readonly [key: string]: Raw };

A value as a source read it, with no function and no undefined: the record kept in an observation.

governance.Locatortypeno test imports it
type Locator =
  | { readonly kind: "file-span"; readonly path: string; readonly startLine: number; readonly endLine: number }
  | { readonly kind: "url"; readonly url: string }
  | { readonly kind: "commit"; readonly sha: string; readonly repo?: string };

Where a thing was read: a span of lines of a file, a URL or a commit (the three kinds of locator).

governance.ObservedStatetypeno test imports it
type ObservedState =
  | { readonly kind: "open" }
  | { readonly kind: "in-progress" }
  | { readonly kind: "deferred"; readonly until: Day }
  | { readonly kind: "closed"; readonly reason: CloseReason };

The state a place says a thing is in.

governance.ObservedItemtypeno test imports it
type ObservedItem = { readonly kind: ItemKind; readonly title: string; readonly body: string; readonly labels: r… (1000 characters)
type ObservedItem = {
  readonly kind: ItemKind;
  readonly title: string;
  readonly body: string;
  readonly labels: readonly string[];
  readonly assignees: readonly string[];
  readonly severity?: Severity;
  readonly state: ObservedState;
  readonly origin: Origin;
  /** The ids the thing has in its place. */
  readonly external: readonly ExternalId[];
  /** The id of an item the place carries in its own form (an anchor): a thing that carries it is that item. */
  readonly anchor?: ItemId;
  /** The fingerprint of the observation of the parent in the same source, for a nested thing. */
  readonly parent?: string;
  /** When the place says the thing began, where it says: it gives the time of the id made from an external id, so that two stores that read the place make the same ids. */
  readonly at?: Instant;
  /** The events the place keeps itself, where it is a history (each with its id, time and actor): taken as they are. */
  readonly history?: readonly ItemEvent[];
} & Carried;

What a source read of one thing, as an item would hold it.

governance.Observationtypeno test imports it
type Observation = { readonly source: string; readonly locator: Locator; /** The SHA-256 of the bytes it was read … (444 characters)
type Observation = {
  readonly source: string;
  readonly locator: Locator;
  /** The SHA-256 of the bytes it was read from, in lower case hexadecimal. */
  readonly contentHash: string;
  /** The identity of the thing that does not depend on where in the place it is. */
  readonly fingerprint: string;
  readonly content: ObservedItem;
  /** The record as the source read it, kept so that nothing of it is dropped. */
  readonly raw: Raw;
};

One thing read in one place.

governance.Presencetypeno test imports it
type Presence = "present" | "absent";

Whether a thing is found in its place now.

governance.Tracetypeno test imports it
type Trace = {
  readonly item: ItemId;
  readonly source: string;
  readonly fingerprint: string;
  readonly locator: Locator;
  readonly contentHash: string;
  readonly observed: ObservedItem;
  readonly presence: Presence;
};

The link from an item to an observation of it, with the content last taken.

governance.BASELINE_CLASSESconstno test imports it
const BASELINE_CLASSES: readonly ["new", "unchanged", "updated", "absent"]

The four classes of an observation against the one last taken (SARIF 2.1.0 section 3.27.24: baselineState).

governance.BaselineClasstypeno test imports it
type BaselineClass = (typeof BASELINE_CLASSES)[number];

One class of an observation against its base.

governance.sameLocatorfunctionno test imports it
function sameLocator(a: Locator, b: Locator): boolean

Two locators are the same place.

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

A value as a source read it, with no function and no undefined: the record kept in an observation.

Locatortypeno test imports it
type Locator =
  | { readonly kind: "file-span"; readonly path: string; readonly startLine: number; readonly endLine: number }
  | { readonly kind: "url"; readonly url: string }
  | { readonly kind: "commit"; readonly sha: string; readonly repo?: string };

Where a thing was read: a span of lines of a file, a URL or a commit (the three kinds of locator).

ObservedStatetypeno test imports it
type ObservedState =
  | { readonly kind: "open" }
  | { readonly kind: "in-progress" }
  | { readonly kind: "deferred"; readonly until: Day }
  | { readonly kind: "closed"; readonly reason: CloseReason };

The state a place says a thing is in.

ObservedItemtypeno test imports it
type ObservedItem = { readonly kind: ItemKind; readonly title: string; readonly body: string; readonly labels: r… (1000 characters)
type ObservedItem = {
  readonly kind: ItemKind;
  readonly title: string;
  readonly body: string;
  readonly labels: readonly string[];
  readonly assignees: readonly string[];
  readonly severity?: Severity;
  readonly state: ObservedState;
  readonly origin: Origin;
  /** The ids the thing has in its place. */
  readonly external: readonly ExternalId[];
  /** The id of an item the place carries in its own form (an anchor): a thing that carries it is that item. */
  readonly anchor?: ItemId;
  /** The fingerprint of the observation of the parent in the same source, for a nested thing. */
  readonly parent?: string;
  /** When the place says the thing began, where it says: it gives the time of the id made from an external id, so that two stores that read the place make the same ids. */
  readonly at?: Instant;
  /** The events the place keeps itself, where it is a history (each with its id, time and actor): taken as they are. */
  readonly history?: readonly ItemEvent[];
} & Carried;

What a source read of one thing, as an item would hold it.

Observationtypeno test imports it
type Observation = { readonly source: string; readonly locator: Locator; /** The SHA-256 of the bytes it was read … (444 characters)
type Observation = {
  readonly source: string;
  readonly locator: Locator;
  /** The SHA-256 of the bytes it was read from, in lower case hexadecimal. */
  readonly contentHash: string;
  /** The identity of the thing that does not depend on where in the place it is. */
  readonly fingerprint: string;
  readonly content: ObservedItem;
  /** The record as the source read it, kept so that nothing of it is dropped. */
  readonly raw: Raw;
};

One thing read in one place.

Presencetypeno test imports it
type Presence = "present" | "absent";

Whether a thing is found in its place now.

Tracetypeno test imports it
type Trace = {
  readonly item: ItemId;
  readonly source: string;
  readonly fingerprint: string;
  readonly locator: Locator;
  readonly contentHash: string;
  readonly observed: ObservedItem;
  readonly presence: Presence;
};

The link from an item to an observation of it, with the content last taken.

BASELINE_CLASSESconstno test imports it
const BASELINE_CLASSES: readonly ["new", "unchanged", "updated", "absent"]

The four classes of an observation against the one last taken (SARIF 2.1.0 section 3.27.24: baselineState).

BaselineClasstypeno test imports it
type BaselineClass = (typeof BASELINE_CLASSES)[number];

One class of an observation against its base.

sameLocatorfunctionno test imports it
function sameLocator(a: Locator, b: Locator): boolean

Two locators are the same place.

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