IF Commons GitHub

findings

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0002-workspace-model FR-033

What a check of the workspace reports (commons 0002-workspace-model FR-033, FR-035): a finding has a rule, a severity (ergonex:Informational, ergonex:Warning, ergonex:Error), a message, what it is about and the day it was first seen; it is written as a SARIF 2.1.0 log whose results have the level of the severity; and a finding about something outside the catalog grows from informational to a warning once it is more than the grace days old, counted from the day first seen and never restarted by a later run.

Days are YYYY-MM-DD texts, and every function takes the day it needs as an argument: nothing here reads a clock. A finding's message says what is wrong and what to do, and holds no secret: the caller gives the file and the line, never the line's text.

Source: commons/ergonex/src/findings.ts

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

daysBetweenfunction
function daysBetween(from: string, to: string): Result<number, string>

The whole days from one day to another (negative where to is before from), or an error naming the text that is not a day.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

dayNumberfunction
function dayNumber(day: string): number | undefined

A day as the number of days since 1970-01-01, or undefined where the text is not a real day.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

exitStatusOffunction
function exitStatusOf(findings: readonly Finding[]): "Findings" | "Ok"

The exit status of a run with these findings: Findings where one is a warning or an error, Ok where there is none or all are informational (0001-ergonex FR-010).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

Findingtype
type Finding = {
  /** The rule that found it, such as `ergonex/path-too-long`. */
  readonly ruleId: string;
  readonly severity: Severity;
  /** What is wrong and what to do about it. */
  readonly message: string;
  /** What it is about: a path, a repository, a tool. */
  readonly subject: string;
  /** The day it was first seen, `YYYY-MM-DD`. */
  readonly firstSeen: string;
};

What a check reports.

Imported by 27 tests of the run (27 passed, 0 failed): the library's results

firstSeenOffunction
function firstSeenOf(previous: Readonly<Record<string, string>>, key: string, today: string): string

The day to record for something seen today: the day it was recorded before where there is one, so that a later run never restarts the clock (FR-033), else today. previous is the state record's days by key.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

sarifLevelfunction
function sarifLevel(severity: Severity): "error" | "note" | "warning"

The SARIF level of a severity, the ergonex:sarifLevel of the code list.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

SarifLogtypeno test imports it
type SarifLog = { readonly $schema: string; readonly version: "2.1.0"; readonly runs: readonly [ { reado… (705 characters)
type SarifLog = {
  readonly $schema: string;
  readonly version: "2.1.0";
  readonly runs: readonly [
    {
      readonly tool: {
        readonly driver: {
          readonly name: string;
          readonly informationUri: string;
          readonly rules: readonly { readonly id: string }[];
        };
      };
      readonly results: readonly {
        readonly ruleId: string;
        readonly level: "note" | "warning" | "error";
        readonly message: { readonly text: string };
        readonly locations: readonly {
          readonly logicalLocations: readonly { readonly name: string }[];
        }[];
        readonly properties: { readonly firstSeen: string };
      }[];
    },
  ];
};

A SARIF 2.1.0 log of findings: one run, the rules that found them, one result each at the level of its severity.

Severitytype
type Severity = "Informational" | "Warning" | "Error";

The severities of a finding, the keys of the code list ergonex:Severity.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

SEVERITIESconst
const SEVERITIES: readonly Severity[]

All the severities, least serious first.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

toSariffunction
function toSarif(findings: readonly Finding[], tool?: string): SarifLog

The findings as a SARIF 2.1.0 log (FR-035); tool is the name of the command that made them.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

UNAPPROVED_GRACE_DAYSconst
const UNAPPROVED_GRACE_DAYS: 90

The grace period of a tool or module outside the catalog, in days (ergonex:unapprovedGraceDays).

Imported by 22 tests of the run (22 passed, 0 failed): the library's results

unapprovedSeverityfunction
function unapprovedSeverity(firstSeen: string, today: string, graceDays?: number): Severity

The severity of a tool or module outside the catalog first seen on firstSeen, judged on today: informational from the day it is first seen, a warning once it is more than graceDays old (FR-033). The 90th day is still informational and the 91st is a warning. A day that is not a day, or is in the future, is informational (a clock set wrong must not fail a run).

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

worstfunction
function worst(findings: readonly Finding[]): Severity | undefined

The most serious severity of a list, or undefined for none.

Imported by 6 tests of the run (6 passed, 0 failed): the library's results

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