@mark1russell7/guidebook-plans 0.0.0-stage → 0.1.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +21 -0
- package/README.md +91 -2
- package/build/index.d.ts +138 -0
- package/build/index.d.ts.map +1 -0
- package/build/index.js +287 -0
- package/build/index.js.map +1 -0
- package/package.json +61 -3
- package/src/coverage.ts +64 -0
- package/src/index.ts +9 -0
- package/src/ladder.ts +76 -0
- package/src/steps.ts +180 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 Mark Russell
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,92 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @mark1russell7/guidebook-plans
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
The plans add-on of `@mark1russell7/guidebook`. A plan is a set of steps. Each step belongs to a key and to a phase of a time ladder.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
pnpm add @mark1russell7/guidebook @mark1russell7/guidebook-plans
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
The add-on names no topic. A content package gives the steps of its topic. A runbook of a service outage and a household plan for a storm use the same records.
|
|
10
|
+
|
|
11
|
+
## The keys
|
|
12
|
+
|
|
13
|
+
A key names a case or a cut:
|
|
14
|
+
|
|
15
|
+
- A case is a kind of event, for example a storm.
|
|
16
|
+
- A cut is a service that an event stops, for example the power grid.
|
|
17
|
+
|
|
18
|
+
Many cases stop the same service. So most steps belong to a cut, and each case that stops the cut uses its steps. The plan of a case is its own steps and the steps of its cuts.
|
|
19
|
+
|
|
20
|
+
## The time ladder
|
|
21
|
+
|
|
22
|
+
`LADDER` is the default ladder. Each phase after the start is approximately 60 times longer than the phase before it.
|
|
23
|
+
|
|
24
|
+
| Phase | Time | Words of `PHASE_TITLES` |
|
|
25
|
+
| --- | --- | --- |
|
|
26
|
+
| `ready` | before the start, with no warning | Before an event |
|
|
27
|
+
| `warned` | before the start, with a warning | When a warning comes |
|
|
28
|
+
| `P0` | 0 to 5 minutes | In the first 5 minutes |
|
|
29
|
+
| `P1` | 5 minutes to 5 hours | From 5 minutes to 5 hours |
|
|
30
|
+
| `P2` | 5 hours to 5 days | From 5 hours to 5 days |
|
|
31
|
+
| `P3` | 5 days to 5 weeks | From 5 days to 5 weeks |
|
|
32
|
+
| `P4` | 5 weeks to 5 months | From 5 weeks to 5 months |
|
|
33
|
+
| `P5` | 5 months to 5 years | From 5 months to 5 years |
|
|
34
|
+
|
|
35
|
+
`phaseOf(seconds, warned)` gives the phase of a time on the default ladder. A time at a bound is in the later phase: 5 minutes gives `P1`. `phaseIn(ladder, seconds, warned)` does the same on a `Ladder` of the caller.
|
|
36
|
+
|
|
37
|
+
## The records and the queries
|
|
38
|
+
|
|
39
|
+
| Name | What it is |
|
|
40
|
+
| --- | --- |
|
|
41
|
+
| `Step` | One action: `id`, the key `on`, `phase`, `needs`, an optional condition `when`, the text `do`, `uses`, `order` and `sources` |
|
|
42
|
+
| `Gap` | A key and a phase that have no step on purpose, with the reason `why` |
|
|
43
|
+
| `stepsFor(library, on, phases)` | The steps of the keys in the phases, by key, then by phase, then by order. A step comes one time. |
|
|
44
|
+
| `planMatrix(library, gaps, on, phases)` | One row for each key, with one cell for each phase: its steps, or its marked gap |
|
|
45
|
+
| `checkSteps(steps, sources, options)` | The step gate |
|
|
46
|
+
| `checkCoverage(steps, options)` | The coverage gate: each key has steps in each phase |
|
|
47
|
+
| `coverageOf(steps, on, phases)` | The phases with steps and the phases with no step, for each key |
|
|
48
|
+
|
|
49
|
+
```ts
|
|
50
|
+
import { PHASES, checkSteps, phaseOf, stepsFor } from "@mark1russell7/guidebook-plans";
|
|
51
|
+
|
|
52
|
+
const phase = phaseOf(2 * 86_400); // "P2"
|
|
53
|
+
const steps = stepsFor(library, ["met.winter.storm", "energy.grid"], [phase]);
|
|
54
|
+
const result = checkSteps(library, sources, { phases: PHASES, on: keys, gaps });
|
|
55
|
+
```
|
|
56
|
+
|
|
57
|
+
## The step gate
|
|
58
|
+
|
|
59
|
+
`checkSteps` gives each finding as data, with the `Finding` type of the core. The text of a step is a summary of each of its sources, so the gate also applies the source gate of the core.
|
|
60
|
+
|
|
61
|
+
| Code | When |
|
|
62
|
+
| --- | --- |
|
|
63
|
+
| `duplicate-id` | Two steps have the same `id`. |
|
|
64
|
+
| `empty-text` | A step has no text `do`. |
|
|
65
|
+
| `no-source` | A step cites no source. |
|
|
66
|
+
| `missing-source` | A step cites a source that is not in the list. |
|
|
67
|
+
| `use-refused` | The license of a source refuses the use. An example is an invented source outside a fixture. |
|
|
68
|
+
| `unknown-phase` | A step or a gap has a phase that is not in `phases`. |
|
|
69
|
+
| `bad-order`, `duplicate-order` | The order is not an integer from 1, or two steps of a cell have the same order. |
|
|
70
|
+
| `unmarked-gap` | With `on`: a cell has no step and no gap marks it. |
|
|
71
|
+
| `gap-with-steps`, `duplicate-gap`, `empty-reason` | A gap marks a cell with steps, two gaps mark one cell, or a gap gives no reason. |
|
|
72
|
+
|
|
73
|
+
## The coverage gate
|
|
74
|
+
|
|
75
|
+
The step gate passes a cell with a marked gap. The coverage gate does not. It examines if each key of `on` has steps in each phase of `phases`. `HORIZONS` is the set of the phases from 5 minutes to 5 years: `P0` to `P5`.
|
|
76
|
+
|
|
77
|
+
| Code | When |
|
|
78
|
+
| --- | --- |
|
|
79
|
+
| `no-step` | A cell has no step, and no gap marks it. |
|
|
80
|
+
| `marked-gap` | A cell has no step, and a gap marks it. The message gives the reason of the gap. |
|
|
81
|
+
|
|
82
|
+
```ts
|
|
83
|
+
import { HORIZONS, checkCoverage } from "@mark1russell7/guidebook-plans";
|
|
84
|
+
|
|
85
|
+
const coverage = checkCoverage(library, { on: keys, phases: HORIZONS, gaps });
|
|
86
|
+
// A key with no step gives one finding for each horizon. It does not pass.
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
## Limits
|
|
90
|
+
|
|
91
|
+
- The gate does not evaluate `when`. The planner of an app evaluates it over the live state.
|
|
92
|
+
- A print cannot evaluate `when`. So the text `do` of a step with a `when` names its condition in words.
|
package/build/index.d.ts
ADDED
|
@@ -0,0 +1,138 @@
|
|
|
1
|
+
import { CitedUnit, Finding, GateResult, Source, SourceId, UseContext } from "@mark1russell7/guidebook";
|
|
2
|
+
/** This constant is the number of seconds in one day. */
|
|
3
|
+
export declare const SECONDS_PER_DAY: number;
|
|
4
|
+
/** A ladder of phases. Each phase has a title that a print or a page shows. */
|
|
5
|
+
interface Ladder<P extends string = string> {
|
|
6
|
+
/** The phase before the start of an event, when no warning is live. */
|
|
7
|
+
readonly ready: P;
|
|
8
|
+
/** The phase before the start of an event, when a warning is live. */
|
|
9
|
+
readonly warned: P;
|
|
10
|
+
/** The phases after the start, in their sequence. Each phase starts at its second `from`. The first phase starts at 0. */
|
|
11
|
+
readonly timed: readonly {
|
|
12
|
+
readonly phase: P;
|
|
13
|
+
readonly from: number;
|
|
14
|
+
}[];
|
|
15
|
+
readonly titles: Readonly<Record<P, string>>;
|
|
16
|
+
}
|
|
17
|
+
/** The phases of the default ladder, in their sequence. */
|
|
18
|
+
export declare const PHASES: readonly ["ready", "warned", "P0", "P1", "P2", "P3", "P4", "P5"];
|
|
19
|
+
/** One phase of the default ladder. */
|
|
20
|
+
type Phase = (typeof PHASES)[number];
|
|
21
|
+
/** The bounds of the phases `P0` to `P5`, in seconds: 0, 5 min, 5 h, 5 d, 5 wk, 5 mo and 5 yr. */
|
|
22
|
+
export declare const PHASE_BOUNDS: readonly number[];
|
|
23
|
+
/** The words of each phase of the default ladder. */
|
|
24
|
+
export declare const PHASE_TITLES: Readonly<Record<Phase, string>>;
|
|
25
|
+
/** The default ladder: each phase after the start is approximately 60 times longer than the phase before it. */
|
|
26
|
+
export declare const LADDER: Ladder<Phase>;
|
|
27
|
+
/** This function gives the phases of a ladder in their sequence: `ready`, `warned`, then the timed phases. */
|
|
28
|
+
export declare function phasesOf<P extends string>(ladder: Ladder<P>): readonly P[];
|
|
29
|
+
/**
|
|
30
|
+
* This function gives the phase of a time on a ladder, in seconds from the start of the event.
|
|
31
|
+
* A negative time is before the start: it gives `warned` when a warning is live, else `ready`.
|
|
32
|
+
* A time at a bound is in the later phase. A time after the start of the last phase stays in the last phase.
|
|
33
|
+
*/
|
|
34
|
+
export declare function phaseIn<P extends string>(ladder: Ladder<P>, seconds: number, warned?: boolean): P;
|
|
35
|
+
/** This function gives the phase of a time on the default ladder. 5 minutes gives `P1`. */
|
|
36
|
+
export declare function phaseOf(seconds: number, warned?: boolean): Phase;
|
|
37
|
+
/**
|
|
38
|
+
* One action of a plan. A step belongs to a key and to a phase.
|
|
39
|
+
* A key names a case (a kind of event) or a cut (a service that an event stops). A plan of a case is its own steps and the steps of its cuts.
|
|
40
|
+
*/
|
|
41
|
+
interface Step<P extends string = Phase> {
|
|
42
|
+
readonly id: string;
|
|
43
|
+
/** The key of the step: a case or a cut. */
|
|
44
|
+
readonly on: string;
|
|
45
|
+
readonly phase: P;
|
|
46
|
+
/** The needs that the step protects. */
|
|
47
|
+
readonly needs: readonly string[];
|
|
48
|
+
/** An optional condition: a Vex program over the live state. No `when` means always. */
|
|
49
|
+
readonly when?: string;
|
|
50
|
+
/**
|
|
51
|
+
* The action, as one instruction in Simplified Technical English, in the words of the guidebook.
|
|
52
|
+
* When the step has a `when`, this text names the condition in words, because a print cannot examine `when`.
|
|
53
|
+
*/
|
|
54
|
+
readonly do: string;
|
|
55
|
+
/** The parts, the resources and the topics that the step uses. */
|
|
56
|
+
readonly uses?: readonly string[];
|
|
57
|
+
/** The order of the step in its phase, from 1. */
|
|
58
|
+
readonly order: number;
|
|
59
|
+
/** The sources of the step. Each step has one or more. */
|
|
60
|
+
readonly sources: readonly SourceId[];
|
|
61
|
+
}
|
|
62
|
+
/** A marked gap: a key and a phase that have no step on purpose, with the reason. */
|
|
63
|
+
interface Gap<P extends string = Phase> {
|
|
64
|
+
readonly on: string;
|
|
65
|
+
readonly phase: P;
|
|
66
|
+
/** The reason, for example "A house fire gives no warning." */
|
|
67
|
+
readonly why: string;
|
|
68
|
+
}
|
|
69
|
+
/** A cell of the matrix of a library: the steps of one key in one phase, or the marked gap of the cell. */
|
|
70
|
+
interface Cell<P extends string = Phase> {
|
|
71
|
+
readonly on: string;
|
|
72
|
+
readonly phase: P;
|
|
73
|
+
readonly steps: readonly Step<P>[];
|
|
74
|
+
readonly gap?: Gap<P>;
|
|
75
|
+
}
|
|
76
|
+
/**
|
|
77
|
+
* This function gives the steps whose `on` is in `on` and whose phase is in `phases`.
|
|
78
|
+
* The sequence is by `on`, then by `phases`, then by `order`. A step that matches two entries of `on` comes one time.
|
|
79
|
+
*/
|
|
80
|
+
export declare function stepsFor<P extends string>(library: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly Step<P>[];
|
|
81
|
+
/** This function gives the matrix of a library: one row for each key of `on`, with one cell for each phase of `phases`. */
|
|
82
|
+
export declare function planMatrix<P extends string>(library: readonly Step<P>[], gaps: readonly Gap<P>[], on: readonly string[], phases: readonly P[]): readonly (readonly Cell<P>[])[];
|
|
83
|
+
/** The codes of the findings of the step gate. The codes of the source gate also apply to the sources of the steps. */
|
|
84
|
+
export declare const STEP_FINDING_CODES: readonly ["duplicate-id", "empty-text", "no-source", "missing-source", "use-refused", "unknown-phase", "bad-order", "duplicate-order", "unmarked-gap", "gap-with-steps", "duplicate-gap", "empty-reason"];
|
|
85
|
+
/** A code of a finding of the step gate. */
|
|
86
|
+
type StepFindingCode = (typeof STEP_FINDING_CODES)[number];
|
|
87
|
+
/** A finding of the step gate. */
|
|
88
|
+
type StepFinding = Finding<StepFindingCode, "step" | "gap" | "cell">;
|
|
89
|
+
/** The options of the step gate. */
|
|
90
|
+
interface StepGateOptions<P extends string> extends UseContext {
|
|
91
|
+
/** The phases that a step can have. */
|
|
92
|
+
readonly phases: readonly P[];
|
|
93
|
+
/** The keys of the matrix. With them, the gate finds each cell that has no step and no marked gap. */
|
|
94
|
+
readonly on?: readonly string[];
|
|
95
|
+
/** The marked gaps of the library. */
|
|
96
|
+
readonly gaps?: readonly Gap<P>[];
|
|
97
|
+
}
|
|
98
|
+
/** This function gives one summary unit for each source of each step, so the source gate examines the steps. */
|
|
99
|
+
export declare function unitsOf<P extends string>(steps: readonly Step<P>[]): readonly CitedUnit[];
|
|
100
|
+
/**
|
|
101
|
+
* This function applies the step gate. It examines the ids, the text, the sources, the phases and the order of each step.
|
|
102
|
+
* It examines the sources with the source gate: the text of a step is a summary of each of its sources.
|
|
103
|
+
* With `on`, it also finds each cell of the matrix that has no step and no marked gap.
|
|
104
|
+
*/
|
|
105
|
+
export declare function checkSteps<P extends string>(steps: readonly Step<P>[], sources: readonly Source[], options: StepGateOptions<P>): GateResult<StepFinding>;
|
|
106
|
+
/** The horizons of a plan: the phases from the first 5 minutes to 5 years. The coverage gate examines them by default. */
|
|
107
|
+
export declare const HORIZONS: readonly ["P0", "P1", "P2", "P3", "P4", "P5"];
|
|
108
|
+
/** The codes of the findings of the coverage gate. */
|
|
109
|
+
export declare const COVERAGE_FINDING_CODES: readonly ["no-step", "marked-gap"];
|
|
110
|
+
/** A code of a finding of the coverage gate. */
|
|
111
|
+
type CoverageFindingCode = (typeof COVERAGE_FINDING_CODES)[number];
|
|
112
|
+
/** A finding of the coverage gate. Its `id` is `<key>/<phase>`. */
|
|
113
|
+
type CoverageFinding = Finding<CoverageFindingCode, "cell">;
|
|
114
|
+
/** The options of the coverage gate. */
|
|
115
|
+
interface CoverageOptions<P extends string> {
|
|
116
|
+
/** The keys of the catalog. Each key needs steps in each phase. */
|
|
117
|
+
readonly on: readonly string[];
|
|
118
|
+
/** The phases that each key needs. */
|
|
119
|
+
readonly phases: readonly P[];
|
|
120
|
+
/** The marked gaps of the library. The gate shows the reason of a gap, but the gap does not pass. */
|
|
121
|
+
readonly gaps?: readonly Gap<P>[];
|
|
122
|
+
}
|
|
123
|
+
/** The coverage of one key: the phases with steps and the phases with no step. */
|
|
124
|
+
interface KeyCoverage<P extends string> {
|
|
125
|
+
readonly on: string;
|
|
126
|
+
readonly covered: readonly P[];
|
|
127
|
+
readonly missing: readonly P[];
|
|
128
|
+
}
|
|
129
|
+
/** This function gives the coverage of each key of `on` over `phases`, in the sequence of `on`. */
|
|
130
|
+
export declare function coverageOf<P extends string>(steps: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly KeyCoverage<P>[];
|
|
131
|
+
/**
|
|
132
|
+
* This function applies the coverage gate. Each key of `on` needs one or more steps in each phase of `phases`.
|
|
133
|
+
* A cell with no step is an error, also when a gap marks it: the finding `marked-gap` gives the reason of the gap.
|
|
134
|
+
* Thus a key with no step shows each of its gaps, and it does not pass.
|
|
135
|
+
*/
|
|
136
|
+
export declare function checkCoverage<P extends string>(steps: readonly Step<P>[], options: CoverageOptions<P>): GateResult<CoverageFinding>;
|
|
137
|
+
export type { Cell, CoverageFinding, CoverageFindingCode, CoverageOptions, Gap, KeyCoverage, Ladder, Phase, Step, StepFinding, StepFindingCode, StepGateOptions };
|
|
138
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","names":[],"sources":["../src/ladder.ts","../src/steps.ts","../src/coverage.ts"],"mappings":";;qBAWa;;UAGI,OAAO;;WAEb,OAAO;;WAEP,QAAQ;;WAER;aAA2B,OAAO;aAAY;;WAC9C,QAAQ,SAAS,OAAO;;;qBAItB;;KAGD,gBAAgB;;qBAGf;;qBAGA,cAAc,SAAS,OAAO;;qBAY9B,QAAQ,OAAO;;wBAQZ,SAAS,kBAAkB,QAAQ,OAAO,cAAc;;;;;;wBASxD,QAAQ,kBAAkB,QAAQ,OAAO,IAAI,iBAAiB,mBAAiB;;wBAU/E,QAAQ,iBAAiB,mBAAiB;;;;;UC/DzC,KAAK,mBAAmB;WAC9B;;WAEA;WACA,OAAO;;WAEP;;WAEA;;;;;WAKA;;WAEA;;WAEA;;WAEA,kBAAkB;;;UAIZ,IAAI,mBAAmB;WAC7B;WACA,OAAO;;WAEP;;;UAIM,KAAK,mBAAmB;WAC9B;WACA,OAAO;WACP,gBAAgB,KAAK;WACrB,MAAM,IAAI;;;;;;wBASL,SAAS,kBAAkB,kBAAkB,KAAK,MAAM,uBAAuB,iBAAiB,eAAe,KAAK;;wBAgBpH,WAAW,kBACzB,kBAAkB,KAAK,MACvB,eAAe,IAAI,MACnB,uBACA,iBAAiB,yBACG,KAAK;;qBAWd;;KAgBD,0BAA0B;;KAG1B,cAAc,QAAQ;;UAGjB,gBAAgB,0BAA0B;;WAEhD,iBAAiB;;WAEjB;;WAEA,gBAAgB,IAAI;;;wBAIf,QAAQ,kBAAkB,gBAAgB,KAAK,gBAAgB;;;;;;wBAS/D,WAAW,kBAAkB,gBAAgB,KAAK,MAAM,kBAAkB,UAAU,SAAS,gBAAgB,KAAK,WAAW;;qBCxHhI;;qBAGA;;KAGD,8BAA8B;;KAG9B,kBAAkB,QAAQ;;UAGrB,gBAAgB;;WAEtB;;WAEA,iBAAiB;;WAEjB,gBAAgB,IAAI;;;UAId,YAAY;WAClB;WACA,kBAAkB;WAClB,kBAAkB;;;wBAIb,WAAW,kBAAkB,gBAAgB,KAAK,MAAM,uBAAuB,iBAAiB,eAAe,YAAY;;;;;;wBAa3H,cAAc,kBAAkB,gBAAgB,KAAK,MAAM,SAAS,gBAAgB,KAAK,WAAW"}
|
package/build/index.js
ADDED
|
@@ -0,0 +1,287 @@
|
|
|
1
|
+
import { checkUnits, resultOf } from "@mark1russell7/guidebook";
|
|
2
|
+
// src/ladder.ts
|
|
3
|
+
const HOUR = 3600;
|
|
4
|
+
const DAY = 24 * HOUR;
|
|
5
|
+
const WEEK = 7 * DAY;
|
|
6
|
+
/** A month of the ladder is 30 days, and a year is 365 days. */
|
|
7
|
+
const MONTH = 30 * DAY;
|
|
8
|
+
const YEAR = 365 * DAY;
|
|
9
|
+
/** This constant is the number of seconds in one day. */
|
|
10
|
+
const SECONDS_PER_DAY = DAY;
|
|
11
|
+
/** The phases of the default ladder, in their sequence. */
|
|
12
|
+
const PHASES = [
|
|
13
|
+
"ready",
|
|
14
|
+
"warned",
|
|
15
|
+
"P0",
|
|
16
|
+
"P1",
|
|
17
|
+
"P2",
|
|
18
|
+
"P3",
|
|
19
|
+
"P4",
|
|
20
|
+
"P5"
|
|
21
|
+
];
|
|
22
|
+
/** The bounds of the phases `P0` to `P5`, in seconds: 0, 5 min, 5 h, 5 d, 5 wk, 5 mo and 5 yr. */
|
|
23
|
+
const PHASE_BOUNDS = [
|
|
24
|
+
0,
|
|
25
|
+
300,
|
|
26
|
+
5 * HOUR,
|
|
27
|
+
5 * DAY,
|
|
28
|
+
5 * WEEK,
|
|
29
|
+
5 * MONTH,
|
|
30
|
+
5 * YEAR
|
|
31
|
+
];
|
|
32
|
+
/** The words of each phase of the default ladder. */
|
|
33
|
+
const PHASE_TITLES = {
|
|
34
|
+
ready: "Before an event",
|
|
35
|
+
warned: "When a warning comes",
|
|
36
|
+
P0: "In the first 5 minutes",
|
|
37
|
+
P1: "From 5 minutes to 5 hours",
|
|
38
|
+
P2: "From 5 hours to 5 days",
|
|
39
|
+
P3: "From 5 days to 5 weeks",
|
|
40
|
+
P4: "From 5 weeks to 5 months",
|
|
41
|
+
P5: "From 5 months to 5 years"
|
|
42
|
+
};
|
|
43
|
+
/** The default ladder: each phase after the start is approximately 60 times longer than the phase before it. */
|
|
44
|
+
const LADDER = {
|
|
45
|
+
ready: "ready",
|
|
46
|
+
warned: "warned",
|
|
47
|
+
timed: [
|
|
48
|
+
"P0",
|
|
49
|
+
"P1",
|
|
50
|
+
"P2",
|
|
51
|
+
"P3",
|
|
52
|
+
"P4",
|
|
53
|
+
"P5"
|
|
54
|
+
].map((phase, i) => ({
|
|
55
|
+
phase,
|
|
56
|
+
from: PHASE_BOUNDS[i] ?? 0
|
|
57
|
+
})),
|
|
58
|
+
titles: PHASE_TITLES
|
|
59
|
+
};
|
|
60
|
+
/** This function gives the phases of a ladder in their sequence: `ready`, `warned`, then the timed phases. */
|
|
61
|
+
function phasesOf(ladder) {
|
|
62
|
+
return [
|
|
63
|
+
ladder.ready,
|
|
64
|
+
ladder.warned,
|
|
65
|
+
...ladder.timed.map((step) => step.phase)
|
|
66
|
+
];
|
|
67
|
+
}
|
|
68
|
+
/**
|
|
69
|
+
* This function gives the phase of a time on a ladder, in seconds from the start of the event.
|
|
70
|
+
* A negative time is before the start: it gives `warned` when a warning is live, else `ready`.
|
|
71
|
+
* A time at a bound is in the later phase. A time after the start of the last phase stays in the last phase.
|
|
72
|
+
*/
|
|
73
|
+
function phaseIn(ladder, seconds, warned = false) {
|
|
74
|
+
if (!Number.isFinite(seconds)) throw new RangeError(`phaseIn: the time ${String(seconds)} is not a finite number.`);
|
|
75
|
+
if (seconds < 0) return warned ? ladder.warned : ladder.ready;
|
|
76
|
+
let phase;
|
|
77
|
+
for (const step of ladder.timed) if (seconds >= step.from) phase = step.phase;
|
|
78
|
+
if (phase === void 0) throw new RangeError("phaseIn: the ladder has no timed phase that starts at 0.");
|
|
79
|
+
return phase;
|
|
80
|
+
}
|
|
81
|
+
/** This function gives the phase of a time on the default ladder. 5 minutes gives `P1`. */
|
|
82
|
+
function phaseOf(seconds, warned = false) {
|
|
83
|
+
return phaseIn(LADDER, seconds, warned);
|
|
84
|
+
}
|
|
85
|
+
// src/steps.ts
|
|
86
|
+
const byOrder = (a, b) => a.order - b.order || a.id.localeCompare(b.id);
|
|
87
|
+
/**
|
|
88
|
+
* This function gives the steps whose `on` is in `on` and whose phase is in `phases`.
|
|
89
|
+
* The sequence is by `on`, then by `phases`, then by `order`. A step that matches two entries of `on` comes one time.
|
|
90
|
+
*/
|
|
91
|
+
function stepsFor(library, on, phases) {
|
|
92
|
+
const out = [];
|
|
93
|
+
const seen = /* @__PURE__ */ new Set();
|
|
94
|
+
for (const key of on) for (const phase of phases) {
|
|
95
|
+
const hits = library.filter((step) => step.on === key && step.phase === phase && !seen.has(step.id)).sort(byOrder);
|
|
96
|
+
for (const step of hits) {
|
|
97
|
+
seen.add(step.id);
|
|
98
|
+
out.push(step);
|
|
99
|
+
}
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
/** This function gives the matrix of a library: one row for each key of `on`, with one cell for each phase of `phases`. */
|
|
104
|
+
function planMatrix(library, gaps, on, phases) {
|
|
105
|
+
return on.map((key) => phases.map((phase) => {
|
|
106
|
+
const steps = library.filter((step) => step.on === key && step.phase === phase).sort(byOrder);
|
|
107
|
+
const gap = gaps.find((item) => item.on === key && item.phase === phase);
|
|
108
|
+
return gap === void 0 ? {
|
|
109
|
+
on: key,
|
|
110
|
+
phase,
|
|
111
|
+
steps
|
|
112
|
+
} : {
|
|
113
|
+
on: key,
|
|
114
|
+
phase,
|
|
115
|
+
steps,
|
|
116
|
+
gap
|
|
117
|
+
};
|
|
118
|
+
}));
|
|
119
|
+
}
|
|
120
|
+
/** The codes of the findings of the step gate. The codes of the source gate also apply to the sources of the steps. */
|
|
121
|
+
const STEP_FINDING_CODES = [
|
|
122
|
+
"duplicate-id",
|
|
123
|
+
"empty-text",
|
|
124
|
+
"no-source",
|
|
125
|
+
"missing-source",
|
|
126
|
+
"use-refused",
|
|
127
|
+
"unknown-phase",
|
|
128
|
+
"bad-order",
|
|
129
|
+
"duplicate-order",
|
|
130
|
+
"unmarked-gap",
|
|
131
|
+
"gap-with-steps",
|
|
132
|
+
"duplicate-gap",
|
|
133
|
+
"empty-reason"
|
|
134
|
+
];
|
|
135
|
+
/** This function gives one summary unit for each source of each step, so the source gate examines the steps. */
|
|
136
|
+
function unitsOf(steps) {
|
|
137
|
+
return steps.flatMap((step) => step.sources.map((source) => ({
|
|
138
|
+
id: `${step.id}@${source}`,
|
|
139
|
+
use: "summary",
|
|
140
|
+
text: step.do,
|
|
141
|
+
source
|
|
142
|
+
})));
|
|
143
|
+
}
|
|
144
|
+
/**
|
|
145
|
+
* This function applies the step gate. It examines the ids, the text, the sources, the phases and the order of each step.
|
|
146
|
+
* It examines the sources with the source gate: the text of a step is a summary of each of its sources.
|
|
147
|
+
* With `on`, it also finds each cell of the matrix that has no step and no marked gap.
|
|
148
|
+
*/
|
|
149
|
+
function checkSteps(steps, sources, options) {
|
|
150
|
+
const out = [];
|
|
151
|
+
const error = (code, record, id, message) => {
|
|
152
|
+
out.push({
|
|
153
|
+
level: "error",
|
|
154
|
+
code,
|
|
155
|
+
record,
|
|
156
|
+
id,
|
|
157
|
+
message
|
|
158
|
+
});
|
|
159
|
+
};
|
|
160
|
+
const phases = new Set(options.phases);
|
|
161
|
+
const ids = /* @__PURE__ */ new Set();
|
|
162
|
+
const orders = /* @__PURE__ */ new Map();
|
|
163
|
+
for (const step of steps) {
|
|
164
|
+
if (ids.has(step.id)) error("duplicate-id", "step", step.id, `Two steps have the id "${step.id}".`);
|
|
165
|
+
ids.add(step.id);
|
|
166
|
+
if (step.do.trim() === "") error("empty-text", "step", step.id, `The step "${step.id}" has no text.`);
|
|
167
|
+
if (step.sources.length === 0) error("no-source", "step", step.id, `The step "${step.id}" cites no source.`);
|
|
168
|
+
if (!phases.has(step.phase)) error("unknown-phase", "step", step.id, `The step "${step.id}" has the unknown phase "${step.phase}".`);
|
|
169
|
+
if (!Number.isInteger(step.order) || step.order < 1) error("bad-order", "step", step.id, `The step "${step.id}" has the order ${String(step.order)}. It needs an integer from 1.`);
|
|
170
|
+
const cell = `${step.on}\u0000${step.phase}\u0000${String(step.order)}`;
|
|
171
|
+
const other = orders.get(cell);
|
|
172
|
+
if (other !== void 0) error("duplicate-order", "step", step.id, `The steps "${other}" and "${step.id}" have the same order in "${step.on}", phase "${step.phase}".`);
|
|
173
|
+
else orders.set(cell, step.id);
|
|
174
|
+
}
|
|
175
|
+
for (const finding of checkUnits(unitsOf(steps), sources, options)) {
|
|
176
|
+
if (finding.code !== "missing-source" && finding.code !== "use-refused") continue;
|
|
177
|
+
const id = finding.id.slice(0, finding.id.lastIndexOf("@"));
|
|
178
|
+
out.push({
|
|
179
|
+
level: finding.level,
|
|
180
|
+
code: finding.code,
|
|
181
|
+
record: "step",
|
|
182
|
+
id,
|
|
183
|
+
message: finding.message.replace(`unit "${finding.id}"`, `step "${id}"`)
|
|
184
|
+
});
|
|
185
|
+
}
|
|
186
|
+
out.push(...checkGaps(steps, options));
|
|
187
|
+
return resultOf(out);
|
|
188
|
+
}
|
|
189
|
+
function checkGaps(steps, options) {
|
|
190
|
+
const out = [];
|
|
191
|
+
const gaps = options.gaps ?? [];
|
|
192
|
+
const seen = /* @__PURE__ */ new Set();
|
|
193
|
+
for (const gap of gaps) {
|
|
194
|
+
const id = `${gap.on}/${gap.phase}`;
|
|
195
|
+
if (seen.has(id)) out.push({
|
|
196
|
+
level: "error",
|
|
197
|
+
code: "duplicate-gap",
|
|
198
|
+
record: "gap",
|
|
199
|
+
id,
|
|
200
|
+
message: `Two gaps mark "${gap.on}" in phase "${gap.phase}".`
|
|
201
|
+
});
|
|
202
|
+
seen.add(id);
|
|
203
|
+
if (gap.why.trim() === "") out.push({
|
|
204
|
+
level: "error",
|
|
205
|
+
code: "empty-reason",
|
|
206
|
+
record: "gap",
|
|
207
|
+
id,
|
|
208
|
+
message: `The gap of "${gap.on}" in phase "${gap.phase}" gives no reason.`
|
|
209
|
+
});
|
|
210
|
+
const count = steps.filter((step) => step.on === gap.on && step.phase === gap.phase).length;
|
|
211
|
+
if (count > 0) out.push({
|
|
212
|
+
level: "error",
|
|
213
|
+
code: "gap-with-steps",
|
|
214
|
+
record: "gap",
|
|
215
|
+
id,
|
|
216
|
+
message: `A gap marks "${gap.on}" in phase "${gap.phase}", but the cell has ${String(count)} steps.`
|
|
217
|
+
});
|
|
218
|
+
if (!options.phases.includes(gap.phase)) out.push({
|
|
219
|
+
level: "error",
|
|
220
|
+
code: "unknown-phase",
|
|
221
|
+
record: "gap",
|
|
222
|
+
id,
|
|
223
|
+
message: `The gap of "${gap.on}" has the unknown phase "${gap.phase}".`
|
|
224
|
+
});
|
|
225
|
+
}
|
|
226
|
+
if (options.on === void 0) return out;
|
|
227
|
+
for (const row of planMatrix(steps, gaps, options.on, options.phases)) for (const cell of row) {
|
|
228
|
+
const id = `${cell.on}/${cell.phase}`;
|
|
229
|
+
if (cell.steps.length === 0 && cell.gap === void 0) out.push({
|
|
230
|
+
level: "error",
|
|
231
|
+
code: "unmarked-gap",
|
|
232
|
+
record: "cell",
|
|
233
|
+
id,
|
|
234
|
+
message: `"${cell.on}" has no step in phase "${cell.phase}", and no gap marks the cell.`
|
|
235
|
+
});
|
|
236
|
+
}
|
|
237
|
+
return out;
|
|
238
|
+
}
|
|
239
|
+
// src/coverage.ts
|
|
240
|
+
/** The horizons of a plan: the phases from the first 5 minutes to 5 years. The coverage gate examines them by default. */
|
|
241
|
+
const HORIZONS = [
|
|
242
|
+
"P0",
|
|
243
|
+
"P1",
|
|
244
|
+
"P2",
|
|
245
|
+
"P3",
|
|
246
|
+
"P4",
|
|
247
|
+
"P5"
|
|
248
|
+
];
|
|
249
|
+
/** The codes of the findings of the coverage gate. */
|
|
250
|
+
const COVERAGE_FINDING_CODES = ["no-step", "marked-gap"];
|
|
251
|
+
/** This function gives the coverage of each key of `on` over `phases`, in the sequence of `on`. */
|
|
252
|
+
function coverageOf(steps, on, phases) {
|
|
253
|
+
return planMatrix(steps, [], on, phases).map((row, index) => ({
|
|
254
|
+
on: on[index] ?? "",
|
|
255
|
+
covered: row.filter((cell) => cell.steps.length > 0).map((cell) => cell.phase),
|
|
256
|
+
missing: row.filter((cell) => cell.steps.length === 0).map((cell) => cell.phase)
|
|
257
|
+
}));
|
|
258
|
+
}
|
|
259
|
+
/**
|
|
260
|
+
* This function applies the coverage gate. Each key of `on` needs one or more steps in each phase of `phases`.
|
|
261
|
+
* A cell with no step is an error, also when a gap marks it: the finding `marked-gap` gives the reason of the gap.
|
|
262
|
+
* Thus a key with no step shows each of its gaps, and it does not pass.
|
|
263
|
+
*/
|
|
264
|
+
function checkCoverage(steps, options) {
|
|
265
|
+
const out = [];
|
|
266
|
+
for (const row of planMatrix(steps, options.gaps ?? [], options.on, options.phases)) for (const cell of row) {
|
|
267
|
+
if (cell.steps.length > 0) continue;
|
|
268
|
+
const id = `${cell.on}/${cell.phase}`;
|
|
269
|
+
out.push(cell.gap === void 0 ? {
|
|
270
|
+
level: "error",
|
|
271
|
+
code: "no-step",
|
|
272
|
+
record: "cell",
|
|
273
|
+
id,
|
|
274
|
+
message: `"${cell.on}" has no step in phase "${cell.phase}".`
|
|
275
|
+
} : {
|
|
276
|
+
level: "error",
|
|
277
|
+
code: "marked-gap",
|
|
278
|
+
record: "cell",
|
|
279
|
+
id,
|
|
280
|
+
message: `"${cell.on}" has no step in phase "${cell.phase}". The gap gives the reason: ${cell.gap.why}`
|
|
281
|
+
});
|
|
282
|
+
}
|
|
283
|
+
return resultOf(out);
|
|
284
|
+
}
|
|
285
|
+
export { COVERAGE_FINDING_CODES, HORIZONS, LADDER, PHASES, PHASE_BOUNDS, PHASE_TITLES, SECONDS_PER_DAY, STEP_FINDING_CODES, checkCoverage, checkSteps, coverageOf, phaseIn, phaseOf, phasesOf, planMatrix, stepsFor, unitsOf };
|
|
286
|
+
|
|
287
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","names":[],"sources":["../src/ladder.ts","../src/steps.ts","../src/coverage.ts"],"sourcesContent":["// The time ladder of a plan: the phases before the start of an event, and the phases after it, each with its first second.\n\nconst MINUTE = 60;\nconst HOUR = 60 * MINUTE;\nconst DAY = 24 * HOUR;\nconst WEEK = 7 * DAY;\n/** A month of the ladder is 30 days, and a year is 365 days. */\nconst MONTH = 30 * DAY;\nconst YEAR = 365 * DAY;\n\n/** This constant is the number of seconds in one day. */\nexport const SECONDS_PER_DAY: number = DAY;\n\n/** A ladder of phases. Each phase has a title that a print or a page shows. */\nexport interface Ladder<P extends string = string> {\n /** The phase before the start of an event, when no warning is live. */\n readonly ready: P;\n /** The phase before the start of an event, when a warning is live. */\n readonly warned: P;\n /** The phases after the start, in their sequence. Each phase starts at its second `from`. The first phase starts at 0. */\n readonly timed: readonly { readonly phase: P; readonly from: number }[];\n readonly titles: Readonly<Record<P, string>>;\n}\n\n/** The phases of the default ladder, in their sequence. */\nexport const PHASES = [\"ready\", \"warned\", \"P0\", \"P1\", \"P2\", \"P3\", \"P4\", \"P5\"] as const;\n\n/** One phase of the default ladder. */\nexport type Phase = (typeof PHASES)[number];\n\n/** The bounds of the phases `P0` to `P5`, in seconds: 0, 5 min, 5 h, 5 d, 5 wk, 5 mo and 5 yr. */\nexport const PHASE_BOUNDS: readonly number[] = [0, 5 * MINUTE, 5 * HOUR, 5 * DAY, 5 * WEEK, 5 * MONTH, 5 * YEAR];\n\n/** The words of each phase of the default ladder. */\nexport const PHASE_TITLES: Readonly<Record<Phase, string>> = {\n ready: \"Before an event\",\n warned: \"When a warning comes\",\n P0: \"In the first 5 minutes\",\n P1: \"From 5 minutes to 5 hours\",\n P2: \"From 5 hours to 5 days\",\n P3: \"From 5 days to 5 weeks\",\n P4: \"From 5 weeks to 5 months\",\n P5: \"From 5 months to 5 years\",\n};\n\n/** The default ladder: each phase after the start is approximately 60 times longer than the phase before it. */\nexport const LADDER: Ladder<Phase> = {\n ready: \"ready\",\n warned: \"warned\",\n timed: ([\"P0\", \"P1\", \"P2\", \"P3\", \"P4\", \"P5\"] as const).map((phase, i) => ({ phase, from: PHASE_BOUNDS[i] ?? 0 })),\n titles: PHASE_TITLES,\n};\n\n/** This function gives the phases of a ladder in their sequence: `ready`, `warned`, then the timed phases. */\nexport function phasesOf<P extends string>(ladder: Ladder<P>): readonly P[] {\n return [ladder.ready, ladder.warned, ...ladder.timed.map((step) => step.phase)];\n}\n\n/**\n * This function gives the phase of a time on a ladder, in seconds from the start of the event.\n * A negative time is before the start: it gives `warned` when a warning is live, else `ready`.\n * A time at a bound is in the later phase. A time after the start of the last phase stays in the last phase.\n */\nexport function phaseIn<P extends string>(ladder: Ladder<P>, seconds: number, warned = false): P {\n if (!Number.isFinite(seconds)) throw new RangeError(`phaseIn: the time ${String(seconds)} is not a finite number.`);\n if (seconds < 0) return warned ? ladder.warned : ladder.ready;\n let phase: P | undefined;\n for (const step of ladder.timed) if (seconds >= step.from) phase = step.phase;\n if (phase === undefined) throw new RangeError(\"phaseIn: the ladder has no timed phase that starts at 0.\");\n return phase;\n}\n\n/** This function gives the phase of a time on the default ladder. 5 minutes gives `P1`. */\nexport function phaseOf(seconds: number, warned = false): Phase {\n return phaseIn(LADDER, seconds, warned);\n}\n","// The steps of a plan, the query of the steps, the matrix of the library, and the step gate.\n\nimport { checkUnits, resultOf } from \"@mark1russell7/guidebook\";\nimport type { CitedUnit, Finding, GateResult, Source, SourceId, UseContext } from \"@mark1russell7/guidebook\";\nimport type { Phase } from \"./ladder.ts\";\n\n/**\n * One action of a plan. A step belongs to a key and to a phase.\n * A key names a case (a kind of event) or a cut (a service that an event stops). A plan of a case is its own steps and the steps of its cuts.\n */\nexport interface Step<P extends string = Phase> {\n readonly id: string;\n /** The key of the step: a case or a cut. */\n readonly on: string;\n readonly phase: P;\n /** The needs that the step protects. */\n readonly needs: readonly string[];\n /** An optional condition: a Vex program over the live state. No `when` means always. */\n readonly when?: string;\n /**\n * The action, as one instruction in Simplified Technical English, in the words of the guidebook.\n * When the step has a `when`, this text names the condition in words, because a print cannot examine `when`.\n */\n readonly do: string;\n /** The parts, the resources and the topics that the step uses. */\n readonly uses?: readonly string[];\n /** The order of the step in its phase, from 1. */\n readonly order: number;\n /** The sources of the step. Each step has one or more. */\n readonly sources: readonly SourceId[];\n}\n\n/** A marked gap: a key and a phase that have no step on purpose, with the reason. */\nexport interface Gap<P extends string = Phase> {\n readonly on: string;\n readonly phase: P;\n /** The reason, for example \"A house fire gives no warning.\" */\n readonly why: string;\n}\n\n/** A cell of the matrix of a library: the steps of one key in one phase, or the marked gap of the cell. */\nexport interface Cell<P extends string = Phase> {\n readonly on: string;\n readonly phase: P;\n readonly steps: readonly Step<P>[];\n readonly gap?: Gap<P>;\n}\n\nconst byOrder = <P extends string>(a: Step<P>, b: Step<P>): number => a.order - b.order || a.id.localeCompare(b.id);\n\n/**\n * This function gives the steps whose `on` is in `on` and whose phase is in `phases`.\n * The sequence is by `on`, then by `phases`, then by `order`. A step that matches two entries of `on` comes one time.\n */\nexport function stepsFor<P extends string>(library: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly Step<P>[] {\n const out: Step<P>[] = [];\n const seen = new Set<string>();\n for (const key of on) {\n for (const phase of phases) {\n const hits = library.filter((step) => step.on === key && step.phase === phase && !seen.has(step.id)).sort(byOrder);\n for (const step of hits) {\n seen.add(step.id);\n out.push(step);\n }\n }\n }\n return out;\n}\n\n/** This function gives the matrix of a library: one row for each key of `on`, with one cell for each phase of `phases`. */\nexport function planMatrix<P extends string>(\n library: readonly Step<P>[],\n gaps: readonly Gap<P>[],\n on: readonly string[],\n phases: readonly P[],\n): readonly (readonly Cell<P>[])[] {\n return on.map((key) =>\n phases.map((phase) => {\n const steps = library.filter((step) => step.on === key && step.phase === phase).sort(byOrder);\n const gap = gaps.find((item) => item.on === key && item.phase === phase);\n return gap === undefined ? { on: key, phase, steps } : { on: key, phase, steps, gap };\n }),\n );\n}\n\n/** The codes of the findings of the step gate. The codes of the source gate also apply to the sources of the steps. */\nexport const STEP_FINDING_CODES = [\n \"duplicate-id\",\n \"empty-text\",\n \"no-source\",\n \"missing-source\",\n \"use-refused\",\n \"unknown-phase\",\n \"bad-order\",\n \"duplicate-order\",\n \"unmarked-gap\",\n \"gap-with-steps\",\n \"duplicate-gap\",\n \"empty-reason\",\n] as const;\n\n/** A code of a finding of the step gate. */\nexport type StepFindingCode = (typeof STEP_FINDING_CODES)[number];\n\n/** A finding of the step gate. */\nexport type StepFinding = Finding<StepFindingCode, \"step\" | \"gap\" | \"cell\">;\n\n/** The options of the step gate. */\nexport interface StepGateOptions<P extends string> extends UseContext {\n /** The phases that a step can have. */\n readonly phases: readonly P[];\n /** The keys of the matrix. With them, the gate finds each cell that has no step and no marked gap. */\n readonly on?: readonly string[];\n /** The marked gaps of the library. */\n readonly gaps?: readonly Gap<P>[];\n}\n\n/** This function gives one summary unit for each source of each step, so the source gate examines the steps. */\nexport function unitsOf<P extends string>(steps: readonly Step<P>[]): readonly CitedUnit[] {\n return steps.flatMap((step) => step.sources.map((source) => ({ id: `${step.id}@${source}`, use: \"summary\" as const, text: step.do, source })));\n}\n\n/**\n * This function applies the step gate. It examines the ids, the text, the sources, the phases and the order of each step.\n * It examines the sources with the source gate: the text of a step is a summary of each of its sources.\n * With `on`, it also finds each cell of the matrix that has no step and no marked gap.\n */\nexport function checkSteps<P extends string>(steps: readonly Step<P>[], sources: readonly Source[], options: StepGateOptions<P>): GateResult<StepFinding> {\n const out: StepFinding[] = [];\n const error = (code: StepFindingCode, record: StepFinding[\"record\"], id: string, message: string): void => {\n out.push({ level: \"error\", code, record, id, message });\n };\n const phases = new Set<string>(options.phases);\n const ids = new Set<string>();\n const orders = new Map<string, string>();\n for (const step of steps) {\n if (ids.has(step.id)) error(\"duplicate-id\", \"step\", step.id, `Two steps have the id \"${step.id}\".`);\n ids.add(step.id);\n if (step.do.trim() === \"\") error(\"empty-text\", \"step\", step.id, `The step \"${step.id}\" has no text.`);\n if (step.sources.length === 0) error(\"no-source\", \"step\", step.id, `The step \"${step.id}\" cites no source.`);\n if (!phases.has(step.phase)) error(\"unknown-phase\", \"step\", step.id, `The step \"${step.id}\" has the unknown phase \"${step.phase}\".`);\n if (!Number.isInteger(step.order) || step.order < 1) error(\"bad-order\", \"step\", step.id, `The step \"${step.id}\" has the order ${String(step.order)}. It needs an integer from 1.`);\n const cell = `${step.on}\\u0000${step.phase}\\u0000${String(step.order)}`;\n const other = orders.get(cell);\n if (other !== undefined) error(\"duplicate-order\", \"step\", step.id, `The steps \"${other}\" and \"${step.id}\" have the same order in \"${step.on}\", phase \"${step.phase}\".`);\n else orders.set(cell, step.id);\n }\n for (const finding of checkUnits(unitsOf(steps), sources, options)) {\n if (finding.code !== \"missing-source\" && finding.code !== \"use-refused\") continue;\n const id = finding.id.slice(0, finding.id.lastIndexOf(\"@\"));\n out.push({ level: finding.level, code: finding.code, record: \"step\", id, message: finding.message.replace(`unit \"${finding.id}\"`, `step \"${id}\"`) });\n }\n out.push(...checkGaps(steps, options));\n return resultOf(out);\n}\n\nfunction checkGaps<P extends string>(steps: readonly Step<P>[], options: StepGateOptions<P>): StepFinding[] {\n const out: StepFinding[] = [];\n const gaps = options.gaps ?? [];\n const seen = new Set<string>();\n for (const gap of gaps) {\n const id = `${gap.on}/${gap.phase}`;\n if (seen.has(id)) out.push({ level: \"error\", code: \"duplicate-gap\", record: \"gap\", id, message: `Two gaps mark \"${gap.on}\" in phase \"${gap.phase}\".` });\n seen.add(id);\n if (gap.why.trim() === \"\") out.push({ level: \"error\", code: \"empty-reason\", record: \"gap\", id, message: `The gap of \"${gap.on}\" in phase \"${gap.phase}\" gives no reason.` });\n const count = steps.filter((step) => step.on === gap.on && step.phase === gap.phase).length;\n if (count > 0) out.push({ level: \"error\", code: \"gap-with-steps\", record: \"gap\", id, message: `A gap marks \"${gap.on}\" in phase \"${gap.phase}\", but the cell has ${String(count)} steps.` });\n if (!options.phases.includes(gap.phase)) out.push({ level: \"error\", code: \"unknown-phase\", record: \"gap\", id, message: `The gap of \"${gap.on}\" has the unknown phase \"${gap.phase}\".` });\n }\n if (options.on === undefined) return out;\n for (const row of planMatrix(steps, gaps, options.on, options.phases)) {\n for (const cell of row) {\n const id = `${cell.on}/${cell.phase}`;\n if (cell.steps.length === 0 && cell.gap === undefined) {\n out.push({ level: \"error\", code: \"unmarked-gap\", record: \"cell\", id, message: `\"${cell.on}\" has no step in phase \"${cell.phase}\", and no gap marks the cell.` });\n }\n }\n }\n return out;\n}\n","// The coverage gate: each key of a catalog has steps in each phase of a set. A marked gap does not pass it.\n\nimport { resultOf } from \"@mark1russell7/guidebook\";\nimport type { Finding, GateResult } from \"@mark1russell7/guidebook\";\nimport { planMatrix, type Gap, type Step } from \"./steps.ts\";\n\n/** The horizons of a plan: the phases from the first 5 minutes to 5 years. The coverage gate examines them by default. */\nexport const HORIZONS = [\"P0\", \"P1\", \"P2\", \"P3\", \"P4\", \"P5\"] as const;\n\n/** The codes of the findings of the coverage gate. */\nexport const COVERAGE_FINDING_CODES = [\"no-step\", \"marked-gap\"] as const;\n\n/** A code of a finding of the coverage gate. */\nexport type CoverageFindingCode = (typeof COVERAGE_FINDING_CODES)[number];\n\n/** A finding of the coverage gate. Its `id` is `<key>/<phase>`. */\nexport type CoverageFinding = Finding<CoverageFindingCode, \"cell\">;\n\n/** The options of the coverage gate. */\nexport interface CoverageOptions<P extends string> {\n /** The keys of the catalog. Each key needs steps in each phase. */\n readonly on: readonly string[];\n /** The phases that each key needs. */\n readonly phases: readonly P[];\n /** The marked gaps of the library. The gate shows the reason of a gap, but the gap does not pass. */\n readonly gaps?: readonly Gap<P>[];\n}\n\n/** The coverage of one key: the phases with steps and the phases with no step. */\nexport interface KeyCoverage<P extends string> {\n readonly on: string;\n readonly covered: readonly P[];\n readonly missing: readonly P[];\n}\n\n/** This function gives the coverage of each key of `on` over `phases`, in the sequence of `on`. */\nexport function coverageOf<P extends string>(steps: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly KeyCoverage<P>[] {\n return planMatrix(steps, [], on, phases).map((row, index) => ({\n on: on[index] ?? \"\",\n covered: row.filter((cell) => cell.steps.length > 0).map((cell) => cell.phase),\n missing: row.filter((cell) => cell.steps.length === 0).map((cell) => cell.phase),\n }));\n}\n\n/**\n * This function applies the coverage gate. Each key of `on` needs one or more steps in each phase of `phases`.\n * A cell with no step is an error, also when a gap marks it: the finding `marked-gap` gives the reason of the gap.\n * Thus a key with no step shows each of its gaps, and it does not pass.\n */\nexport function checkCoverage<P extends string>(steps: readonly Step<P>[], options: CoverageOptions<P>): GateResult<CoverageFinding> {\n const out: CoverageFinding[] = [];\n for (const row of planMatrix(steps, options.gaps ?? [], options.on, options.phases)) {\n for (const cell of row) {\n if (cell.steps.length > 0) continue;\n const id = `${cell.on}/${cell.phase}`;\n out.push(\n cell.gap === undefined\n ? { level: \"error\", code: \"no-step\", record: \"cell\", id, message: `\"${cell.on}\" has no step in phase \"${cell.phase}\".` }\n : { level: \"error\", code: \"marked-gap\", record: \"cell\", id, message: `\"${cell.on}\" has no step in phase \"${cell.phase}\". The gap gives the reason: ${cell.gap.why}` },\n );\n }\n }\n return resultOf(out);\n}\n"],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,64 @@
|
|
|
1
1
|
{
|
|
2
|
+
"$schema": "https://json.schemastore.org/package",
|
|
2
3
|
"name": "@mark1russell7/guidebook-plans",
|
|
3
|
-
"version": "0.
|
|
4
|
-
"
|
|
5
|
-
"
|
|
4
|
+
"version": "0.1.1",
|
|
5
|
+
"description": "The plans add-on of the guidebook: a time ladder of phases, steps keyed by a case or a cut and a phase, the steps query, the matrix of a library with its marked gaps, and the step gate.",
|
|
6
|
+
"keywords": [
|
|
7
|
+
"guidebook",
|
|
8
|
+
"plan",
|
|
9
|
+
"runbook",
|
|
10
|
+
"steps",
|
|
11
|
+
"phases",
|
|
12
|
+
"typescript"
|
|
13
|
+
],
|
|
14
|
+
"homepage": "https://github.com/mark1russell7/guidebook#readme",
|
|
15
|
+
"bugs": {
|
|
16
|
+
"url": "https://github.com/mark1russell7/guidebook/issues"
|
|
17
|
+
},
|
|
18
|
+
"repository": {
|
|
19
|
+
"type": "git",
|
|
20
|
+
"url": "git+https://github.com/mark1russell7/guidebook.git",
|
|
21
|
+
"directory": "packages/plans"
|
|
22
|
+
},
|
|
23
|
+
"license": "MIT",
|
|
24
|
+
"author": "Mark Russell (https://github.com/mark1russell7)",
|
|
25
|
+
"type": "module",
|
|
26
|
+
"sideEffects": false,
|
|
27
|
+
"main": "./build/index.js",
|
|
28
|
+
"types": "./build/index.d.ts",
|
|
29
|
+
"exports": {
|
|
30
|
+
".": {
|
|
31
|
+
"types": "./build/index.d.ts",
|
|
32
|
+
"default": "./build/index.js"
|
|
33
|
+
},
|
|
34
|
+
"./package.json": "./package.json"
|
|
35
|
+
},
|
|
36
|
+
"files": [
|
|
37
|
+
"build",
|
|
38
|
+
"src",
|
|
39
|
+
"!src/**/*.test.ts"
|
|
40
|
+
],
|
|
41
|
+
"engines": {
|
|
42
|
+
"node": ">=22.12"
|
|
43
|
+
},
|
|
44
|
+
"publishConfig": {
|
|
45
|
+
"access": "public"
|
|
46
|
+
},
|
|
47
|
+
"devDependencies": {
|
|
48
|
+
"@mark1russell7/cue": "^2.0.0",
|
|
49
|
+
"@types/node": "^26.6.5",
|
|
50
|
+
"@vitest/coverage-v8": "^5.0.3",
|
|
51
|
+
"typescript": "^7.0.2",
|
|
52
|
+
"vitest": "^5.0.3",
|
|
53
|
+
"tsdown": "^0.23.7"
|
|
54
|
+
},
|
|
55
|
+
"dependencies": {
|
|
56
|
+
"@mark1russell7/guidebook": "0.1.1"
|
|
57
|
+
},
|
|
58
|
+
"scripts": {
|
|
59
|
+
"build": "tsdown",
|
|
60
|
+
"test": "vitest run",
|
|
61
|
+
"test:watch": "vitest",
|
|
62
|
+
"typecheck": "tsc -p tsconfig.json && tsc -p tsconfig.test.json"
|
|
63
|
+
}
|
|
6
64
|
}
|
package/src/coverage.ts
ADDED
|
@@ -0,0 +1,64 @@
|
|
|
1
|
+
// The coverage gate: each key of a catalog has steps in each phase of a set. A marked gap does not pass it.
|
|
2
|
+
|
|
3
|
+
import { resultOf } from "@mark1russell7/guidebook";
|
|
4
|
+
import type { Finding, GateResult } from "@mark1russell7/guidebook";
|
|
5
|
+
import { planMatrix, type Gap, type Step } from "./steps.ts";
|
|
6
|
+
|
|
7
|
+
/** The horizons of a plan: the phases from the first 5 minutes to 5 years. The coverage gate examines them by default. */
|
|
8
|
+
export const HORIZONS = ["P0", "P1", "P2", "P3", "P4", "P5"] as const;
|
|
9
|
+
|
|
10
|
+
/** The codes of the findings of the coverage gate. */
|
|
11
|
+
export const COVERAGE_FINDING_CODES = ["no-step", "marked-gap"] as const;
|
|
12
|
+
|
|
13
|
+
/** A code of a finding of the coverage gate. */
|
|
14
|
+
export type CoverageFindingCode = (typeof COVERAGE_FINDING_CODES)[number];
|
|
15
|
+
|
|
16
|
+
/** A finding of the coverage gate. Its `id` is `<key>/<phase>`. */
|
|
17
|
+
export type CoverageFinding = Finding<CoverageFindingCode, "cell">;
|
|
18
|
+
|
|
19
|
+
/** The options of the coverage gate. */
|
|
20
|
+
export interface CoverageOptions<P extends string> {
|
|
21
|
+
/** The keys of the catalog. Each key needs steps in each phase. */
|
|
22
|
+
readonly on: readonly string[];
|
|
23
|
+
/** The phases that each key needs. */
|
|
24
|
+
readonly phases: readonly P[];
|
|
25
|
+
/** The marked gaps of the library. The gate shows the reason of a gap, but the gap does not pass. */
|
|
26
|
+
readonly gaps?: readonly Gap<P>[];
|
|
27
|
+
}
|
|
28
|
+
|
|
29
|
+
/** The coverage of one key: the phases with steps and the phases with no step. */
|
|
30
|
+
export interface KeyCoverage<P extends string> {
|
|
31
|
+
readonly on: string;
|
|
32
|
+
readonly covered: readonly P[];
|
|
33
|
+
readonly missing: readonly P[];
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/** This function gives the coverage of each key of `on` over `phases`, in the sequence of `on`. */
|
|
37
|
+
export function coverageOf<P extends string>(steps: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly KeyCoverage<P>[] {
|
|
38
|
+
return planMatrix(steps, [], on, phases).map((row, index) => ({
|
|
39
|
+
on: on[index] ?? "",
|
|
40
|
+
covered: row.filter((cell) => cell.steps.length > 0).map((cell) => cell.phase),
|
|
41
|
+
missing: row.filter((cell) => cell.steps.length === 0).map((cell) => cell.phase),
|
|
42
|
+
}));
|
|
43
|
+
}
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* This function applies the coverage gate. Each key of `on` needs one or more steps in each phase of `phases`.
|
|
47
|
+
* A cell with no step is an error, also when a gap marks it: the finding `marked-gap` gives the reason of the gap.
|
|
48
|
+
* Thus a key with no step shows each of its gaps, and it does not pass.
|
|
49
|
+
*/
|
|
50
|
+
export function checkCoverage<P extends string>(steps: readonly Step<P>[], options: CoverageOptions<P>): GateResult<CoverageFinding> {
|
|
51
|
+
const out: CoverageFinding[] = [];
|
|
52
|
+
for (const row of planMatrix(steps, options.gaps ?? [], options.on, options.phases)) {
|
|
53
|
+
for (const cell of row) {
|
|
54
|
+
if (cell.steps.length > 0) continue;
|
|
55
|
+
const id = `${cell.on}/${cell.phase}`;
|
|
56
|
+
out.push(
|
|
57
|
+
cell.gap === undefined
|
|
58
|
+
? { level: "error", code: "no-step", record: "cell", id, message: `"${cell.on}" has no step in phase "${cell.phase}".` }
|
|
59
|
+
: { level: "error", code: "marked-gap", record: "cell", id, message: `"${cell.on}" has no step in phase "${cell.phase}". The gap gives the reason: ${cell.gap.why}` },
|
|
60
|
+
);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
return resultOf(out);
|
|
64
|
+
}
|
package/src/index.ts
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
// The plans add-on of the guidebook: the time ladder, the steps of a plan by key and phase, the matrix of a library, the step gate and the coverage gate.
|
|
2
|
+
// The add-on names no topic. A content package gives the steps of its topic.
|
|
3
|
+
|
|
4
|
+
export { LADDER, PHASES, PHASE_BOUNDS, PHASE_TITLES, SECONDS_PER_DAY, phaseIn, phaseOf, phasesOf } from "./ladder.ts";
|
|
5
|
+
export type { Ladder, Phase } from "./ladder.ts";
|
|
6
|
+
export { STEP_FINDING_CODES, checkSteps, planMatrix, stepsFor, unitsOf } from "./steps.ts";
|
|
7
|
+
export type { Cell, Gap, Step, StepFinding, StepFindingCode, StepGateOptions } from "./steps.ts";
|
|
8
|
+
export { COVERAGE_FINDING_CODES, HORIZONS, checkCoverage, coverageOf } from "./coverage.ts";
|
|
9
|
+
export type { CoverageFinding, CoverageFindingCode, CoverageOptions, KeyCoverage } from "./coverage.ts";
|
package/src/ladder.ts
ADDED
|
@@ -0,0 +1,76 @@
|
|
|
1
|
+
// The time ladder of a plan: the phases before the start of an event, and the phases after it, each with its first second.
|
|
2
|
+
|
|
3
|
+
const MINUTE = 60;
|
|
4
|
+
const HOUR = 60 * MINUTE;
|
|
5
|
+
const DAY = 24 * HOUR;
|
|
6
|
+
const WEEK = 7 * DAY;
|
|
7
|
+
/** A month of the ladder is 30 days, and a year is 365 days. */
|
|
8
|
+
const MONTH = 30 * DAY;
|
|
9
|
+
const YEAR = 365 * DAY;
|
|
10
|
+
|
|
11
|
+
/** This constant is the number of seconds in one day. */
|
|
12
|
+
export const SECONDS_PER_DAY: number = DAY;
|
|
13
|
+
|
|
14
|
+
/** A ladder of phases. Each phase has a title that a print or a page shows. */
|
|
15
|
+
export interface Ladder<P extends string = string> {
|
|
16
|
+
/** The phase before the start of an event, when no warning is live. */
|
|
17
|
+
readonly ready: P;
|
|
18
|
+
/** The phase before the start of an event, when a warning is live. */
|
|
19
|
+
readonly warned: P;
|
|
20
|
+
/** The phases after the start, in their sequence. Each phase starts at its second `from`. The first phase starts at 0. */
|
|
21
|
+
readonly timed: readonly { readonly phase: P; readonly from: number }[];
|
|
22
|
+
readonly titles: Readonly<Record<P, string>>;
|
|
23
|
+
}
|
|
24
|
+
|
|
25
|
+
/** The phases of the default ladder, in their sequence. */
|
|
26
|
+
export const PHASES = ["ready", "warned", "P0", "P1", "P2", "P3", "P4", "P5"] as const;
|
|
27
|
+
|
|
28
|
+
/** One phase of the default ladder. */
|
|
29
|
+
export type Phase = (typeof PHASES)[number];
|
|
30
|
+
|
|
31
|
+
/** The bounds of the phases `P0` to `P5`, in seconds: 0, 5 min, 5 h, 5 d, 5 wk, 5 mo and 5 yr. */
|
|
32
|
+
export const PHASE_BOUNDS: readonly number[] = [0, 5 * MINUTE, 5 * HOUR, 5 * DAY, 5 * WEEK, 5 * MONTH, 5 * YEAR];
|
|
33
|
+
|
|
34
|
+
/** The words of each phase of the default ladder. */
|
|
35
|
+
export const PHASE_TITLES: Readonly<Record<Phase, string>> = {
|
|
36
|
+
ready: "Before an event",
|
|
37
|
+
warned: "When a warning comes",
|
|
38
|
+
P0: "In the first 5 minutes",
|
|
39
|
+
P1: "From 5 minutes to 5 hours",
|
|
40
|
+
P2: "From 5 hours to 5 days",
|
|
41
|
+
P3: "From 5 days to 5 weeks",
|
|
42
|
+
P4: "From 5 weeks to 5 months",
|
|
43
|
+
P5: "From 5 months to 5 years",
|
|
44
|
+
};
|
|
45
|
+
|
|
46
|
+
/** The default ladder: each phase after the start is approximately 60 times longer than the phase before it. */
|
|
47
|
+
export const LADDER: Ladder<Phase> = {
|
|
48
|
+
ready: "ready",
|
|
49
|
+
warned: "warned",
|
|
50
|
+
timed: (["P0", "P1", "P2", "P3", "P4", "P5"] as const).map((phase, i) => ({ phase, from: PHASE_BOUNDS[i] ?? 0 })),
|
|
51
|
+
titles: PHASE_TITLES,
|
|
52
|
+
};
|
|
53
|
+
|
|
54
|
+
/** This function gives the phases of a ladder in their sequence: `ready`, `warned`, then the timed phases. */
|
|
55
|
+
export function phasesOf<P extends string>(ladder: Ladder<P>): readonly P[] {
|
|
56
|
+
return [ladder.ready, ladder.warned, ...ladder.timed.map((step) => step.phase)];
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/**
|
|
60
|
+
* This function gives the phase of a time on a ladder, in seconds from the start of the event.
|
|
61
|
+
* A negative time is before the start: it gives `warned` when a warning is live, else `ready`.
|
|
62
|
+
* A time at a bound is in the later phase. A time after the start of the last phase stays in the last phase.
|
|
63
|
+
*/
|
|
64
|
+
export function phaseIn<P extends string>(ladder: Ladder<P>, seconds: number, warned = false): P {
|
|
65
|
+
if (!Number.isFinite(seconds)) throw new RangeError(`phaseIn: the time ${String(seconds)} is not a finite number.`);
|
|
66
|
+
if (seconds < 0) return warned ? ladder.warned : ladder.ready;
|
|
67
|
+
let phase: P | undefined;
|
|
68
|
+
for (const step of ladder.timed) if (seconds >= step.from) phase = step.phase;
|
|
69
|
+
if (phase === undefined) throw new RangeError("phaseIn: the ladder has no timed phase that starts at 0.");
|
|
70
|
+
return phase;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** This function gives the phase of a time on the default ladder. 5 minutes gives `P1`. */
|
|
74
|
+
export function phaseOf(seconds: number, warned = false): Phase {
|
|
75
|
+
return phaseIn(LADDER, seconds, warned);
|
|
76
|
+
}
|
package/src/steps.ts
ADDED
|
@@ -0,0 +1,180 @@
|
|
|
1
|
+
// The steps of a plan, the query of the steps, the matrix of the library, and the step gate.
|
|
2
|
+
|
|
3
|
+
import { checkUnits, resultOf } from "@mark1russell7/guidebook";
|
|
4
|
+
import type { CitedUnit, Finding, GateResult, Source, SourceId, UseContext } from "@mark1russell7/guidebook";
|
|
5
|
+
import type { Phase } from "./ladder.ts";
|
|
6
|
+
|
|
7
|
+
/**
|
|
8
|
+
* One action of a plan. A step belongs to a key and to a phase.
|
|
9
|
+
* A key names a case (a kind of event) or a cut (a service that an event stops). A plan of a case is its own steps and the steps of its cuts.
|
|
10
|
+
*/
|
|
11
|
+
export interface Step<P extends string = Phase> {
|
|
12
|
+
readonly id: string;
|
|
13
|
+
/** The key of the step: a case or a cut. */
|
|
14
|
+
readonly on: string;
|
|
15
|
+
readonly phase: P;
|
|
16
|
+
/** The needs that the step protects. */
|
|
17
|
+
readonly needs: readonly string[];
|
|
18
|
+
/** An optional condition: a Vex program over the live state. No `when` means always. */
|
|
19
|
+
readonly when?: string;
|
|
20
|
+
/**
|
|
21
|
+
* The action, as one instruction in Simplified Technical English, in the words of the guidebook.
|
|
22
|
+
* When the step has a `when`, this text names the condition in words, because a print cannot examine `when`.
|
|
23
|
+
*/
|
|
24
|
+
readonly do: string;
|
|
25
|
+
/** The parts, the resources and the topics that the step uses. */
|
|
26
|
+
readonly uses?: readonly string[];
|
|
27
|
+
/** The order of the step in its phase, from 1. */
|
|
28
|
+
readonly order: number;
|
|
29
|
+
/** The sources of the step. Each step has one or more. */
|
|
30
|
+
readonly sources: readonly SourceId[];
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
/** A marked gap: a key and a phase that have no step on purpose, with the reason. */
|
|
34
|
+
export interface Gap<P extends string = Phase> {
|
|
35
|
+
readonly on: string;
|
|
36
|
+
readonly phase: P;
|
|
37
|
+
/** The reason, for example "A house fire gives no warning." */
|
|
38
|
+
readonly why: string;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** A cell of the matrix of a library: the steps of one key in one phase, or the marked gap of the cell. */
|
|
42
|
+
export interface Cell<P extends string = Phase> {
|
|
43
|
+
readonly on: string;
|
|
44
|
+
readonly phase: P;
|
|
45
|
+
readonly steps: readonly Step<P>[];
|
|
46
|
+
readonly gap?: Gap<P>;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
const byOrder = <P extends string>(a: Step<P>, b: Step<P>): number => a.order - b.order || a.id.localeCompare(b.id);
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* This function gives the steps whose `on` is in `on` and whose phase is in `phases`.
|
|
53
|
+
* The sequence is by `on`, then by `phases`, then by `order`. A step that matches two entries of `on` comes one time.
|
|
54
|
+
*/
|
|
55
|
+
export function stepsFor<P extends string>(library: readonly Step<P>[], on: readonly string[], phases: readonly P[]): readonly Step<P>[] {
|
|
56
|
+
const out: Step<P>[] = [];
|
|
57
|
+
const seen = new Set<string>();
|
|
58
|
+
for (const key of on) {
|
|
59
|
+
for (const phase of phases) {
|
|
60
|
+
const hits = library.filter((step) => step.on === key && step.phase === phase && !seen.has(step.id)).sort(byOrder);
|
|
61
|
+
for (const step of hits) {
|
|
62
|
+
seen.add(step.id);
|
|
63
|
+
out.push(step);
|
|
64
|
+
}
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
return out;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/** This function gives the matrix of a library: one row for each key of `on`, with one cell for each phase of `phases`. */
|
|
71
|
+
export function planMatrix<P extends string>(
|
|
72
|
+
library: readonly Step<P>[],
|
|
73
|
+
gaps: readonly Gap<P>[],
|
|
74
|
+
on: readonly string[],
|
|
75
|
+
phases: readonly P[],
|
|
76
|
+
): readonly (readonly Cell<P>[])[] {
|
|
77
|
+
return on.map((key) =>
|
|
78
|
+
phases.map((phase) => {
|
|
79
|
+
const steps = library.filter((step) => step.on === key && step.phase === phase).sort(byOrder);
|
|
80
|
+
const gap = gaps.find((item) => item.on === key && item.phase === phase);
|
|
81
|
+
return gap === undefined ? { on: key, phase, steps } : { on: key, phase, steps, gap };
|
|
82
|
+
}),
|
|
83
|
+
);
|
|
84
|
+
}
|
|
85
|
+
|
|
86
|
+
/** The codes of the findings of the step gate. The codes of the source gate also apply to the sources of the steps. */
|
|
87
|
+
export const STEP_FINDING_CODES = [
|
|
88
|
+
"duplicate-id",
|
|
89
|
+
"empty-text",
|
|
90
|
+
"no-source",
|
|
91
|
+
"missing-source",
|
|
92
|
+
"use-refused",
|
|
93
|
+
"unknown-phase",
|
|
94
|
+
"bad-order",
|
|
95
|
+
"duplicate-order",
|
|
96
|
+
"unmarked-gap",
|
|
97
|
+
"gap-with-steps",
|
|
98
|
+
"duplicate-gap",
|
|
99
|
+
"empty-reason",
|
|
100
|
+
] as const;
|
|
101
|
+
|
|
102
|
+
/** A code of a finding of the step gate. */
|
|
103
|
+
export type StepFindingCode = (typeof STEP_FINDING_CODES)[number];
|
|
104
|
+
|
|
105
|
+
/** A finding of the step gate. */
|
|
106
|
+
export type StepFinding = Finding<StepFindingCode, "step" | "gap" | "cell">;
|
|
107
|
+
|
|
108
|
+
/** The options of the step gate. */
|
|
109
|
+
export interface StepGateOptions<P extends string> extends UseContext {
|
|
110
|
+
/** The phases that a step can have. */
|
|
111
|
+
readonly phases: readonly P[];
|
|
112
|
+
/** The keys of the matrix. With them, the gate finds each cell that has no step and no marked gap. */
|
|
113
|
+
readonly on?: readonly string[];
|
|
114
|
+
/** The marked gaps of the library. */
|
|
115
|
+
readonly gaps?: readonly Gap<P>[];
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** This function gives one summary unit for each source of each step, so the source gate examines the steps. */
|
|
119
|
+
export function unitsOf<P extends string>(steps: readonly Step<P>[]): readonly CitedUnit[] {
|
|
120
|
+
return steps.flatMap((step) => step.sources.map((source) => ({ id: `${step.id}@${source}`, use: "summary" as const, text: step.do, source })));
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
/**
|
|
124
|
+
* This function applies the step gate. It examines the ids, the text, the sources, the phases and the order of each step.
|
|
125
|
+
* It examines the sources with the source gate: the text of a step is a summary of each of its sources.
|
|
126
|
+
* With `on`, it also finds each cell of the matrix that has no step and no marked gap.
|
|
127
|
+
*/
|
|
128
|
+
export function checkSteps<P extends string>(steps: readonly Step<P>[], sources: readonly Source[], options: StepGateOptions<P>): GateResult<StepFinding> {
|
|
129
|
+
const out: StepFinding[] = [];
|
|
130
|
+
const error = (code: StepFindingCode, record: StepFinding["record"], id: string, message: string): void => {
|
|
131
|
+
out.push({ level: "error", code, record, id, message });
|
|
132
|
+
};
|
|
133
|
+
const phases = new Set<string>(options.phases);
|
|
134
|
+
const ids = new Set<string>();
|
|
135
|
+
const orders = new Map<string, string>();
|
|
136
|
+
for (const step of steps) {
|
|
137
|
+
if (ids.has(step.id)) error("duplicate-id", "step", step.id, `Two steps have the id "${step.id}".`);
|
|
138
|
+
ids.add(step.id);
|
|
139
|
+
if (step.do.trim() === "") error("empty-text", "step", step.id, `The step "${step.id}" has no text.`);
|
|
140
|
+
if (step.sources.length === 0) error("no-source", "step", step.id, `The step "${step.id}" cites no source.`);
|
|
141
|
+
if (!phases.has(step.phase)) error("unknown-phase", "step", step.id, `The step "${step.id}" has the unknown phase "${step.phase}".`);
|
|
142
|
+
if (!Number.isInteger(step.order) || step.order < 1) error("bad-order", "step", step.id, `The step "${step.id}" has the order ${String(step.order)}. It needs an integer from 1.`);
|
|
143
|
+
const cell = `${step.on}\u0000${step.phase}\u0000${String(step.order)}`;
|
|
144
|
+
const other = orders.get(cell);
|
|
145
|
+
if (other !== undefined) error("duplicate-order", "step", step.id, `The steps "${other}" and "${step.id}" have the same order in "${step.on}", phase "${step.phase}".`);
|
|
146
|
+
else orders.set(cell, step.id);
|
|
147
|
+
}
|
|
148
|
+
for (const finding of checkUnits(unitsOf(steps), sources, options)) {
|
|
149
|
+
if (finding.code !== "missing-source" && finding.code !== "use-refused") continue;
|
|
150
|
+
const id = finding.id.slice(0, finding.id.lastIndexOf("@"));
|
|
151
|
+
out.push({ level: finding.level, code: finding.code, record: "step", id, message: finding.message.replace(`unit "${finding.id}"`, `step "${id}"`) });
|
|
152
|
+
}
|
|
153
|
+
out.push(...checkGaps(steps, options));
|
|
154
|
+
return resultOf(out);
|
|
155
|
+
}
|
|
156
|
+
|
|
157
|
+
function checkGaps<P extends string>(steps: readonly Step<P>[], options: StepGateOptions<P>): StepFinding[] {
|
|
158
|
+
const out: StepFinding[] = [];
|
|
159
|
+
const gaps = options.gaps ?? [];
|
|
160
|
+
const seen = new Set<string>();
|
|
161
|
+
for (const gap of gaps) {
|
|
162
|
+
const id = `${gap.on}/${gap.phase}`;
|
|
163
|
+
if (seen.has(id)) out.push({ level: "error", code: "duplicate-gap", record: "gap", id, message: `Two gaps mark "${gap.on}" in phase "${gap.phase}".` });
|
|
164
|
+
seen.add(id);
|
|
165
|
+
if (gap.why.trim() === "") out.push({ level: "error", code: "empty-reason", record: "gap", id, message: `The gap of "${gap.on}" in phase "${gap.phase}" gives no reason.` });
|
|
166
|
+
const count = steps.filter((step) => step.on === gap.on && step.phase === gap.phase).length;
|
|
167
|
+
if (count > 0) out.push({ level: "error", code: "gap-with-steps", record: "gap", id, message: `A gap marks "${gap.on}" in phase "${gap.phase}", but the cell has ${String(count)} steps.` });
|
|
168
|
+
if (!options.phases.includes(gap.phase)) out.push({ level: "error", code: "unknown-phase", record: "gap", id, message: `The gap of "${gap.on}" has the unknown phase "${gap.phase}".` });
|
|
169
|
+
}
|
|
170
|
+
if (options.on === undefined) return out;
|
|
171
|
+
for (const row of planMatrix(steps, gaps, options.on, options.phases)) {
|
|
172
|
+
for (const cell of row) {
|
|
173
|
+
const id = `${cell.on}/${cell.phase}`;
|
|
174
|
+
if (cell.steps.length === 0 && cell.gap === undefined) {
|
|
175
|
+
out.push({ level: "error", code: "unmarked-gap", record: "cell", id, message: `"${cell.on}" has no step in phase "${cell.phase}", and no gap marks the cell.` });
|
|
176
|
+
}
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
return out;
|
|
180
|
+
}
|