@chernabog/sdk 0.11.0 → 0.12.0

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/src/compose.ts CHANGED
@@ -37,6 +37,16 @@ import {
37
37
  startOf,
38
38
  subjects,
39
39
  } from "./blocks.ts";
40
+ import { type FlowEvents, type WakingEvent } from "./events.ts";
41
+ import {
42
+ type ItemKind,
43
+ NO_RECORD,
44
+ PHASE_NAME,
45
+ phasesOf,
46
+ type Reading,
47
+ type Reconciling,
48
+ SUBJECT_ITEMS,
49
+ } from "./phases.ts";
40
50
 
41
51
  export type Problem = { readonly path: string; readonly message: string };
42
52
 
@@ -622,7 +632,17 @@ const blocksByName: { readonly [name: string]: Block } = catalogue;
622
632
 
623
633
  const subjectsByName: { readonly [name: string]: Subject } = subjects;
624
634
 
625
- const sourcesByName: { readonly [name: string]: { readonly subject: string } } = sources;
635
+ const sourcesByName: {
636
+ readonly [name: string]: {
637
+ readonly subject: string;
638
+ readonly reads: ReadonlyArray<Reading>;
639
+ readonly reconciles: ReadonlyArray<Reconciling>;
640
+ readonly events: ReadonlyArray<WakingEvent>;
641
+ };
642
+ } = sources;
643
+
644
+ // The item a run on each subject works on, which a phase it names is of.
645
+ const subjectItems: { readonly [subject: string]: ItemKind } = SUBJECT_ITEMS;
626
646
 
627
647
  const sourceInputs: {
628
648
  readonly [name: string]: {
@@ -754,6 +774,44 @@ const checkInputs = (
754
774
  }
755
775
  };
756
776
 
777
+ // The phase a block such as progress.advance records, as its document names
778
+ // it. A team's own phase may be any name of its own, but one a slip away from
779
+ // one of the SDK's would pass for it nowhere, and leave the flow that reads
780
+ // that one finding nothing.
781
+ const checkRecordedPhase = (checking: Checking, step: UseStep, block: Block, at: string) => {
782
+ for (const input of Option.toArray(block.recordsInput)) {
783
+ for (const phase of Option.toArray(Record.get(step.with ?? {}, input))) {
784
+ const path = `${at}.with.${input}`;
785
+
786
+ if (!Predicate.isString(phase) || !PHASE_NAME.test(phase)) {
787
+ say(
788
+ checking,
789
+ path,
790
+ "must be a phase's name: lower-case words joined by hyphens, such as triaged",
791
+ );
792
+
793
+ continue;
794
+ }
795
+
796
+ for (const item of Option.toArray(Record.get(subjectItems, checking.subject))) {
797
+ const theSdks = phasesOf(item);
798
+
799
+ if (theSdks.includes(phase)) {
800
+ continue;
801
+ }
802
+
803
+ for (const hint of Option.toArray(suggesting(phase, theSdks))) {
804
+ say(
805
+ checking,
806
+ path,
807
+ `${phase} is a ${item} phase so close to one of the SDK's that it reads as a slip: ${hint} A team's own phase needs a name of its own`,
808
+ );
809
+ }
810
+ }
811
+ }
812
+ }
813
+ };
814
+
757
815
  // A name the document gives something, which the flow file declares as it is:
758
816
  // it must be a name, and one the file doesn't already have.
759
817
  const checkName = (
@@ -1361,6 +1419,7 @@ const checkUse = (
1361
1419
  }
1362
1420
 
1363
1421
  checkInputs(checking, step, block, names, at);
1422
+ checkRecordedPhase(checking, step, block, at);
1364
1423
  checkRouting(checking, step, block, at);
1365
1424
  checkStepKey(checking, step, block, place, at);
1366
1425
 
@@ -2048,6 +2107,13 @@ const describeStage = (stage: StageDefinition) => {
2048
2107
  return { name: stage.name, inputs, gives, failures: STAGE_FAILURES };
2049
2108
  };
2050
2109
 
2110
+ // A declared event as a listing gives it.
2111
+ const eventJson = (waking: WakingEvent): Schema.Json => ({
2112
+ ...waking,
2113
+ types: [...waking.types],
2114
+ item: { ...waking.item },
2115
+ });
2116
+
2051
2117
  // Everything a document can use, for an agent or a person composing one, with
2052
2118
  // the repo's Effect stages when given them.
2053
2119
  export const describe = (stages: ReadonlyArray<StageDefinition> = []): Schema.Json => ({
@@ -2064,9 +2130,21 @@ export const describe = (stages: ReadonlyArray<StageDefinition> = []): Schema.Js
2064
2130
  about: source.about,
2065
2131
  with: source.with,
2066
2132
  // The subject of the work it finds.
2133
+ // And the phases whose items it finds, and those it moves an item to
2134
+ // from what GitHub says.
2067
2135
  ...Option.match(Record.get(sourcesByName, name), {
2068
2136
  onNone: () => ({}),
2069
- onSome: (found) => ({ subject: found.subject }),
2137
+ onSome: (found) => ({
2138
+ subject: found.subject,
2139
+ reads: found.reads.map((reading) => ({ item: reading.item, phases: [...reading.phases] })),
2140
+ reconciles: found.reconciles.map((reconciled) => ({
2141
+ item: reconciled.item,
2142
+ from: [...reconciled.from],
2143
+ to: reconciled.to,
2144
+ })),
2145
+ // The GitHub events that can change what it finds.
2146
+ events: found.events.map(eventJson),
2147
+ }),
2070
2148
  }),
2071
2149
  })),
2072
2150
  loopStates: Object.keys(loopStates),
@@ -2102,6 +2180,19 @@ export const describe = (stages: ReadonlyArray<StageDefinition> = []): Schema.Js
2102
2180
  waits: block.waits,
2103
2181
  // Whether it runs only on a run's way out, so in a repeat it takes no round.
2104
2182
  last: block.last,
2183
+ // The phases it may record, and the input naming one it records as its
2184
+ // document says; and the phases its wakes find parked runs by.
2185
+ records: block.records.map((recorded) => ({ ...recorded })),
2186
+ ...Option.match(block.recordsInput, {
2187
+ onNone: () => ({}),
2188
+ onSome: (input) => ({ recordsInput: input }),
2189
+ }),
2190
+ wakeReads: (block.contributes.wakeReads ?? []).map((reading) => ({
2191
+ item: reading.item,
2192
+ phases: [...reading.phases],
2193
+ })),
2194
+ // The GitHub events that settle the wait its wakes look for.
2195
+ wakeEvents: (block.contributes.wakeEvents ?? []).map(eventJson),
2105
2196
  })),
2106
2197
  stages: stages.map(describeStage),
2107
2198
  });
@@ -2664,3 +2755,304 @@ export const generate = (
2664
2755
 
2665
2756
  return Result.succeed(emit(document, sdk, stages));
2666
2757
  };
2758
+
2759
+ // A phase a flow reads or records, and the source or block that does.
2760
+ export type PhaseUse = {
2761
+ readonly flow: string;
2762
+ readonly item: ItemKind;
2763
+ readonly phase: string;
2764
+ readonly by: string;
2765
+ };
2766
+
2767
+ // What a document's sources and blocks read and record.
2768
+ export type FlowProgress = {
2769
+ readonly reads: ReadonlyArray<PhaseUse>;
2770
+ readonly records: ReadonlyArray<PhaseUse>;
2771
+ };
2772
+
2773
+ // The block steps of a document, deep in its branches, rounds and lanes too.
2774
+ const useStepsIn = (steps: ReadonlyArray<Step>): ReadonlyArray<UseStep> =>
2775
+ steps.flatMap((step) => [...Arr.filter([step], isUse), ...useStepsIn(inside(step))]);
2776
+
2777
+ const phaseKey = (use: { readonly item: ItemKind; readonly phase: string }) =>
2778
+ `${use.item} ${use.phase}`;
2779
+
2780
+ const useKey = (use: PhaseUse) => `${use.flow} ${use.by} ${phaseKey(use)}`;
2781
+
2782
+ const byUse = Order.mapInput(Order.String, useKey);
2783
+
2784
+ const distinctUses = (uses: ReadonlyArray<PhaseUse>) =>
2785
+ Arr.sort(
2786
+ Arr.dedupeWith(uses, (one, other) => useKey(one) === useKey(other)),
2787
+ byUse,
2788
+ );
2789
+
2790
+ const readingsOf = (
2791
+ flow: string,
2792
+ by: string,
2793
+ readings: ReadonlyArray<Reading>,
2794
+ ): ReadonlyArray<PhaseUse> =>
2795
+ readings.flatMap((reading) =>
2796
+ reading.phases
2797
+ .filter((phase) => phase !== NO_RECORD)
2798
+ .map((phase) => ({ flow, item: reading.item, phase, by })),
2799
+ );
2800
+
2801
+ // The phase a step of a block such as progress.advance records, as its
2802
+ // document names it under with, on the item its subject is.
2803
+ const namedPhaseOf = (document: FlowDocument, step: UseStep, block: Block) =>
2804
+ Option.toArray(block.recordsInput).flatMap((input) =>
2805
+ Option.toArray(
2806
+ Option.all({
2807
+ item: Record.get(subjectItems, document.subject),
2808
+ phase: Option.filter(Record.get(step.with ?? {}, input), Predicate.isString),
2809
+ }),
2810
+ ),
2811
+ );
2812
+
2813
+ // What a document's sources and blocks read and record, as the catalogue
2814
+ // declares them: a source's reads and what it reconciles, a block's records,
2815
+ // the phase a progress.advance step names, and what a block's wakes read.
2816
+ export const progressOf = (document: FlowDocument): FlowProgress => {
2817
+ const flow = document.flow;
2818
+
2819
+ const found = document.trigger.flatMap((entry) =>
2820
+ Option.toArray(Record.get(sourcesByName, entry.use)).map((source) => ({
2821
+ name: entry.use,
2822
+ source,
2823
+ })),
2824
+ );
2825
+
2826
+ const used = useStepsIn(document.steps).flatMap((step) =>
2827
+ Option.toArray(Record.get(blocksByName, step.use)).map((block) => ({ step, block })),
2828
+ );
2829
+
2830
+ return {
2831
+ reads: distinctUses([
2832
+ ...found.flatMap(({ name, source }) => readingsOf(flow, name, source.reads)),
2833
+ ...used.flatMap(({ block }) =>
2834
+ readingsOf(flow, block.name, block.contributes.wakeReads ?? []),
2835
+ ),
2836
+ ]),
2837
+ records: distinctUses([
2838
+ ...used.flatMap(({ block, step }) => [
2839
+ ...block.records.map((recorded) => ({
2840
+ flow,
2841
+ item: recorded.item,
2842
+ phase: recorded.phase,
2843
+ by: block.name,
2844
+ })),
2845
+ ...namedPhaseOf(document, step, block).map((named) => ({ flow, by: block.name, ...named })),
2846
+ ]),
2847
+ ...found.flatMap(({ name, source }) =>
2848
+ source.reconciles.map((reconciled) => ({
2849
+ flow,
2850
+ item: reconciled.item,
2851
+ phase: reconciled.to,
2852
+ by: name,
2853
+ })),
2854
+ ),
2855
+ ]),
2856
+ };
2857
+ };
2858
+
2859
+ // A phase read that no flow records, or recorded that no flow reads though a
2860
+ // source the SDK has would. Certain unless some flow declares nothing.
2861
+ export type PhaseGap = {
2862
+ readonly gap: "unrecorded" | "unread";
2863
+ readonly item: ItemKind;
2864
+ readonly phase: string;
2865
+ readonly certain: boolean;
2866
+ readonly message: string;
2867
+ };
2868
+
2869
+ // A list as a sentence gives all of it: "a, b and c".
2870
+ const allOf = (names: ReadonlyArray<string>) =>
2871
+ [names.slice(0, -1).join(", "), ...names.slice(-1)]
2872
+ .filter((part) => part.length > 0)
2873
+ .join(" and ");
2874
+
2875
+ const sorted = (names: ReadonlyArray<string>) => Arr.sort(Arr.dedupe(names), Order.String);
2876
+
2877
+ // A verb for one or for several: "reads" or "read".
2878
+ const agreeing = (count: number, one: string, several: string) =>
2879
+ Option.getOrElse(
2880
+ Option.liftPredicate(one, () => count === 1),
2881
+ () => several,
2882
+ );
2883
+
2884
+ // Who in which flows: "issue.handOff and issue.handOffAdopted in implement".
2885
+ const whoIn = (uses: ReadonlyArray<PhaseUse>) =>
2886
+ allOf(
2887
+ sorted(uses.map((use) => use.flow)).map(
2888
+ (flow) =>
2889
+ `${allOf(sorted(uses.flatMap((use) => Arr.filter([use.by], () => use.flow === flow))))} in ${flow}`,
2890
+ ),
2891
+ );
2892
+
2893
+ const countOf = (uses: ReadonlyArray<PhaseUse>) =>
2894
+ new Set(uses.map((use) => `${use.flow} ${use.by}`)).size;
2895
+
2896
+ // The catalogue's sources and blocks that record and read each phase, whatever
2897
+ // the repo's flows use: where to look for one a flow is missing.
2898
+ const catalogueRecords = (item: ItemKind, phase: string) =>
2899
+ sorted([
2900
+ ...Object.values(blocksByName)
2901
+ .filter((block) =>
2902
+ block.records.some((recorded) => recorded.item === item && recorded.phase === phase),
2903
+ )
2904
+ .map((block) => block.name),
2905
+ ...Object.entries(sourcesByName)
2906
+ .filter(([, source]) =>
2907
+ source.reconciles.some((reconciled) => reconciled.item === item && reconciled.to === phase),
2908
+ )
2909
+ .map(([name]) => name),
2910
+ ]);
2911
+
2912
+ const holds = (readings: ReadonlyArray<Reading>, item: ItemKind, phase: string) =>
2913
+ readings.some((reading) => reading.item === item && reading.phases.some((one) => one === phase));
2914
+
2915
+ const catalogueReads = (item: ItemKind, phase: string) =>
2916
+ sorted([
2917
+ ...Object.entries(sourcesByName)
2918
+ .filter(([, source]) => holds(source.reads, item, phase))
2919
+ .map(([name]) => name),
2920
+ ...Object.values(blocksByName)
2921
+ .filter((block) => holds(block.contributes.wakeReads ?? [], item, phase))
2922
+ .map((block) => block.name),
2923
+ ]);
2924
+
2925
+ // Whether what reads a phase also finds items with no record, as
2926
+ // review.requested takes a pull request a person opened: it needs nothing
2927
+ // recorded to find its work.
2928
+ const takesNone = (use: PhaseUse) =>
2929
+ [
2930
+ ...Option.toArray(Record.get(sourcesByName, use.by)).flatMap((source) => source.reads),
2931
+ ...Option.toArray(Record.get(blocksByName, use.by)).flatMap(
2932
+ (block) => block.contributes.wakeReads ?? [],
2933
+ ),
2934
+ ].some(
2935
+ (reading) =>
2936
+ reading.item === use.item &&
2937
+ reading.phases.some((phase) => phase === use.phase) &&
2938
+ reading.phases.some((phase) => phase === NO_RECORD),
2939
+ );
2940
+
2941
+ const groupedBy = (uses: ReadonlyArray<PhaseUse>) =>
2942
+ Arr.dedupe(uses.map(phaseKey)).map((key) => uses.filter((use) => phaseKey(use) === key));
2943
+
2944
+ // Gaps between what a repo's flows read and record of phases: a phase a
2945
+ // flow's source or wake reads that no flow's block records nor source
2946
+ // reconciles, so the flow never finds the work, unless it also finds items
2947
+ // with no record; and one a flow records that no
2948
+ // flow reads, where the SDK has a source that would. A phase no source reads
2949
+ // is for status, and recorded freely. `undeclared` names the repo's flows
2950
+ // without a document, written in TypeScript, which declare nothing: with any,
2951
+ // a gap is one they may fill, not certain.
2952
+ export const phaseGaps = (
2953
+ documents: ReadonlyArray<FlowDocument>,
2954
+ undeclared: ReadonlyArray<string> = [],
2955
+ ): ReadonlyArray<PhaseGap> => {
2956
+ const progress = documents.map(progressOf);
2957
+ const reads = progress.flatMap((each) => each.reads);
2958
+ const records = progress.flatMap((each) => each.records);
2959
+ const recorded = new Set(records.map(phaseKey));
2960
+ const isRead = new Set(reads.map(phaseKey));
2961
+ const certain = undeclared.length === 0;
2962
+
2963
+ const unsure = Option.getOrElse(
2964
+ Option.liftPredicate(
2965
+ `; ${allOf(sorted(undeclared))} ${agreeing(undeclared.length, "has no document and declares nothing, so it may", "have no document and declare nothing, so one of them may")}`,
2966
+ () => !certain,
2967
+ ),
2968
+ () => "",
2969
+ );
2970
+
2971
+ // The phases recorded of the item near one read, and the flows that record them.
2972
+ const near = (item: ItemKind, phase: string) => {
2973
+ const ofItem = records.filter((use) => use.item === item);
2974
+ const names = nearest(phase, sorted(ofItem.map((use) => use.phase)));
2975
+
2976
+ const flows = sorted(
2977
+ ofItem.flatMap((use) => Arr.filter([use.flow], () => names.includes(use.phase))),
2978
+ );
2979
+
2980
+ return Option.map(
2981
+ Option.liftPredicate(names, (found) => found.length > 0),
2982
+ (found) =>
2983
+ `; did you mean ${oneOf(found)}, which ${allOf(flows)} ${agreeing(flows.length, "records", "record")}?`,
2984
+ );
2985
+ };
2986
+
2987
+ const unrecorded = groupedBy(
2988
+ reads.filter((use) => !recorded.has(phaseKey(use)) && !takesNone(use)),
2989
+ ).flatMap((uses) =>
2990
+ Option.toArray(Arr.head(uses)).map(({ item, phase }): PhaseGap => {
2991
+ const recorders = catalogueRecords(item, phase);
2992
+
2993
+ const where = Option.getOrElse(
2994
+ Option.liftPredicate(
2995
+ `: ${allOf(recorders)} ${agreeing(recorders.length, "records", "record")} it`,
2996
+ () => recorders.length > 0,
2997
+ ),
2998
+ () => "",
2999
+ );
3000
+
3001
+ return {
3002
+ gap: "unrecorded",
3003
+ item,
3004
+ phase,
3005
+ certain,
3006
+ message: `${whoIn(uses)} ${agreeing(countOf(uses), "reads", "read")} the ${item} phase ${phase}, but no flow records it${where}${Option.getOrElse(near(item, phase), () => "")}${unsure}`,
3007
+ };
3008
+ }),
3009
+ );
3010
+
3011
+ const unread = groupedBy(records.filter((use) => !isRead.has(phaseKey(use)))).flatMap((uses) =>
3012
+ Option.toArray(Arr.head(uses)).flatMap(({ item, phase }) => {
3013
+ const readers = catalogueReads(item, phase);
3014
+
3015
+ return Arr.filter(
3016
+ [
3017
+ {
3018
+ gap: "unread" as const,
3019
+ item,
3020
+ phase,
3021
+ certain,
3022
+ message: `${whoIn(uses)} ${agreeing(countOf(uses), "records", "record")} the ${item} phase ${phase}, but no flow reads it: ${allOf(readers)} ${agreeing(readers.length, "reads", "read")} it${unsure}`,
3023
+ },
3024
+ ],
3025
+ () => readers.length > 0,
3026
+ );
3027
+ }),
3028
+ );
3029
+
3030
+ return [...unrecorded, ...unread];
3031
+ };
3032
+
3033
+ const eventKey = (waking: WakingEvent) => printJson(eventJson(waking));
3034
+
3035
+ // The GitHub events that can change what a document's trigger finds, as the
3036
+ // catalogue declares them: its sources' and its blocks' wakes'; and whether
3037
+ // it reads phases, so a phase event wakes it too (events.ts). A compiled
3038
+ // flow carries them.
3039
+ export const eventsOf = (document: FlowDocument): FlowEvents => {
3040
+ const found = document.trigger.flatMap((entry) =>
3041
+ Option.toArray(Record.get(sourcesByName, entry.use)),
3042
+ );
3043
+
3044
+ const used = useStepsIn(document.steps).flatMap((step) =>
3045
+ Option.toArray(Record.get(blocksByName, step.use)),
3046
+ );
3047
+
3048
+ return {
3049
+ events: Arr.dedupeWith(
3050
+ [
3051
+ ...found.flatMap((source) => source.events),
3052
+ ...used.flatMap((block) => block.contributes.wakeEvents ?? []),
3053
+ ],
3054
+ (one, other) => eventKey(one) === eventKey(other),
3055
+ ),
3056
+ readsPhases: progressOf(document).reads.length > 0,
3057
+ };
3058
+ };
@@ -38,7 +38,9 @@ import {
38
38
  type WorktreePath,
39
39
  } from "./block.ts";
40
40
  import * as Epic from "./epic.ts";
41
+ import * as Events from "./events.ts";
41
42
  import * as Implement from "./implement.ts";
43
+ import { NO_RECORD, PHASES } from "./phases.ts";
42
44
  import * as Plan from "./plan.ts";
43
45
  import * as PullRequest from "./pull-request.ts";
44
46
  import * as Routing from "./routing.ts";
@@ -917,6 +919,7 @@ export const epicBlocks = {
917
919
  Option.liftPredicate(read.summary, () => read.finished),
918
920
  },
919
921
  mustRoute: ["finished"],
922
+ records: [{ item: "epic", phase: PHASES.epic.finished }],
920
923
  contributes: {},
921
924
  }),
922
925
 
@@ -1048,6 +1051,7 @@ export const epicBlocks = {
1048
1051
  outcomes: {},
1049
1052
  mustRoute: [],
1050
1053
  waits: true,
1054
+ records: [{ item: "epic", phase: PHASES.epic.waiting }],
1051
1055
  contributes: {},
1052
1056
  }),
1053
1057
 
@@ -1184,13 +1188,21 @@ export const laneScopes = {
1184
1188
  };
1185
1189
 
1186
1190
  export const epicSources = {
1187
- "epic.queued": defineSource("epic.queued", "epic", () => ({
1188
- trigger: Epic.queued.pipe(reportAs("trigger")),
1189
- contributes: {
1190
- settings: { ...Routing.Settings.fields, ...Settings.Board.fields },
1191
- labels: Plan.flowLabels.filter((label) => label.name === Plan.LABELS.epic),
1191
+ "epic.queued": defineSource(
1192
+ "epic.queued",
1193
+ "epic",
1194
+ () => ({
1195
+ trigger: Epic.queued.pipe(reportAs("trigger")),
1196
+ contributes: {
1197
+ settings: { ...Routing.Settings.fields, ...Settings.Board.fields },
1198
+ labels: Plan.flowLabels.filter((label) => label.name === Plan.LABELS.epic),
1199
+ },
1200
+ }),
1201
+ {
1202
+ reads: [{ item: "epic", phases: [PHASES.epic.waiting, NO_RECORD] }],
1203
+ events: [Events.issueLabelled, ...Events.layerChanged],
1192
1204
  },
1193
- })),
1205
+ ),
1194
1206
  };
1195
1207
 
1196
1208
  // However the run ends, its claim on the epic goes, and the engine lets its