@verevoir/aigency-work 0.2.1 → 0.4.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/CHANGELOG.md +137 -0
- package/README.md +59 -0
- package/dist/asf-board.js +118 -40
- package/dist/backlog-board.d.ts +21 -0
- package/dist/backlog-board.js +383 -0
- package/dist/board.d.ts +21 -2
- package/dist/board.js +30 -1
- package/dist/card.d.ts +61 -17
- package/dist/card.js +38 -8
- package/dist/in-memory-board.d.ts +13 -1
- package/dist/in-memory-board.js +23 -3
- package/dist/index.d.ts +9 -3
- package/dist/index.js +4 -1
- package/dist/notion-board.d.ts +82 -0
- package/dist/notion-board.js +667 -26
- package/dist/payload-board.js +6 -1
- package/dist/status.d.ts +24 -0
- package/dist/status.js +36 -0
- package/dist/store-board.js +6 -1
- package/dist/trello-board.d.ts +41 -0
- package/dist/trello-board.js +337 -0
- package/package.json +1 -1
|
@@ -0,0 +1,383 @@
|
|
|
1
|
+
// A `CardSource` and `CardSink` over a BACKLOG.md-style markdown file (the
|
|
2
|
+
// "v2" backlog format). All IO is injected as `read`/`write`; this file
|
|
3
|
+
// touches no filesystem and no network.
|
|
4
|
+
//
|
|
5
|
+
// The parse mirrors the reference implementation, `parseBacklog` in
|
|
6
|
+
// v5's src/seams/backlog-git.ts:
|
|
7
|
+
//
|
|
8
|
+
// - [ ] BL-123 Title text
|
|
9
|
+
// requires: BL-1, BL-2 (optional, directly below the entry)
|
|
10
|
+
// retracted: <reason> (only on an [R] entry, and required there)
|
|
11
|
+
// parent: <id> (optional, before or after body:)
|
|
12
|
+
// body: <text or URL> (optional; else the title is the body)
|
|
13
|
+
// Targets: ... / Excludes: ... / Blocked on BL-9 ... / free text
|
|
14
|
+
//
|
|
15
|
+
// Markers: ' ' ready, '~' in progress, 'x' done, '!' blocked, 'R' retracted.
|
|
16
|
+
// Any other marker, a missing id, a blank title, a blank requires/parent/
|
|
17
|
+
// retracted line, an invalid id in requires:, an [R] with no retracted:
|
|
18
|
+
// line, a retracted: line on a non-[R] entry, and every copy of a duplicated
|
|
19
|
+
// id are unparseable (reported in `unparseable`, not dropped).
|
|
20
|
+
//
|
|
21
|
+
// Choices made here, beyond the reference:
|
|
22
|
+
// - `Card.body` is the card's whole indented text, de-indented by two
|
|
23
|
+
// spaces and joined with newlines, `requires:`/`body:` lines included.
|
|
24
|
+
// With no indented lines it is the title, as in the reference.
|
|
25
|
+
// - `Card.requires` is the `requires:` ids PLUS any id following the words
|
|
26
|
+
// "Blocked on" in the card's indented text. The reference reads only
|
|
27
|
+
// `requires:`; "Blocked on" is how the v2 file itself records it.
|
|
28
|
+
// - The reference reads '~' as `assigned` (planning/assigned/in-review are
|
|
29
|
+
// one marker); the normalized status for it is `in-progress`.
|
|
30
|
+
// - `writeState` changes the marker character and nothing else. The
|
|
31
|
+
// reference's put() also deletes the `retracted:` line when an [R] card
|
|
32
|
+
// moves out of [R]; that is more than a marker, so here a move into or
|
|
33
|
+
// out of 'R' is refused rather than half-done.
|
|
34
|
+
// - Status is derived on read through the map and never stored.
|
|
35
|
+
// - `list()` reports `danglingIds`: ids named by any card's requires (so by
|
|
36
|
+
// "Blocked on") that match no card in the file, deduplicated and sorted. A
|
|
37
|
+
// reference to a card kept in an archive file therefore shows as dangling
|
|
38
|
+
// unless the caller passes `archived` (anything with an `id`, as the
|
|
39
|
+
// reference's readBacklogArchive entries have). An id that is present but
|
|
40
|
+
// malformed is not dangling; it is in `unparseable`.
|
|
41
|
+
// - Nothing is dropped silently. Besides the reference's rules, a line that
|
|
42
|
+
// LOOKS like an entry (optional indent, a `-` or `*` bullet, `[...]`, then an
|
|
43
|
+
// id-shaped token) but misses the strict `- [c] ` shape is unparseable, and
|
|
44
|
+
// so is an indented line that follows no card directly (for example text
|
|
45
|
+
// after a blank line, a stray Targets:/Excludes: line, or text above the
|
|
46
|
+
// first card). Unindented prose, headings and blank lines are intentionally
|
|
47
|
+
// ignored, as in the reference.
|
|
48
|
+
// - A `requires:`/`parent:`/`retracted:`/`body:` line out of its fixed position
|
|
49
|
+
// is kept in the body text but not interpreted (inert, as in the reference).
|
|
50
|
+
// "Blocked on" followed by something that is not an id is likewise text only.
|
|
51
|
+
// - A trailing CR (CRLF files) is ignored when parsing; writes preserve it.
|
|
52
|
+
// - `createCard` and `annotate` are `unsupported` for now.
|
|
53
|
+
import { normalizeStatus } from './status.js';
|
|
54
|
+
/**
|
|
55
|
+
* Native marker character to normalized status. '~' is `in-progress`
|
|
56
|
+
* because the reference reads it as `assigned`; it is also written for
|
|
57
|
+
* planning and in-review work, which one marker cannot tell apart.
|
|
58
|
+
*/
|
|
59
|
+
export const BACKLOG_STATUS_MAP = {
|
|
60
|
+
toStatus: {
|
|
61
|
+
' ': 'ready',
|
|
62
|
+
'~': 'in-progress',
|
|
63
|
+
x: 'done',
|
|
64
|
+
'!': 'blocked',
|
|
65
|
+
R: 'retracted',
|
|
66
|
+
},
|
|
67
|
+
fromStatus: {
|
|
68
|
+
ready: ' ',
|
|
69
|
+
'in-progress': '~',
|
|
70
|
+
done: 'x',
|
|
71
|
+
blocked: '!',
|
|
72
|
+
retracted: 'R',
|
|
73
|
+
},
|
|
74
|
+
};
|
|
75
|
+
const ID_BODY = '[A-Za-z][A-Za-z0-9]*-[A-Za-z0-9]+(?:\\.[A-Za-z0-9]+)*';
|
|
76
|
+
const ID_PATTERN = new RegExp(`^${ID_BODY}$`);
|
|
77
|
+
const BLOCKED_ON = new RegExp(`\\bBlocked on (${ID_BODY})`, 'g');
|
|
78
|
+
const ENTRY_LINE = /^- \[(.)\]\s*(.*)$/;
|
|
79
|
+
const REQUIRES_LINE = /^ {2}requires: (.*)$/;
|
|
80
|
+
const RETRACTED_LINE = /^ {2}retracted:\s*(.*)$/;
|
|
81
|
+
const PARENT_LINE = /^ {2}parent:(.*)$/;
|
|
82
|
+
const BODY_LINE = /^ {2}body: (.+)$/;
|
|
83
|
+
const LOOSE_ENTRY = new RegExp(`^[ \\t]*[-*][ \\t]+\\[[^\\]]*\\][ \\t]*(${ID_BODY})(?=\\s|$)`);
|
|
84
|
+
const KNOWN_MARKERS = new Set([' ', '~', 'x', '!', 'R']);
|
|
85
|
+
function parseEntryLine(raw) {
|
|
86
|
+
const match = ENTRY_LINE.exec(raw);
|
|
87
|
+
if (match === null) {
|
|
88
|
+
const loose = LOOSE_ENTRY.exec(raw);
|
|
89
|
+
if (loose === null)
|
|
90
|
+
return { kind: 'none' };
|
|
91
|
+
return {
|
|
92
|
+
kind: 'problem',
|
|
93
|
+
reason: 'looks like a card but does not match "- [<marker>] <ID> <title>"',
|
|
94
|
+
...(loose[1] !== undefined ? { id: loose[1] } : {}),
|
|
95
|
+
};
|
|
96
|
+
}
|
|
97
|
+
const marker = match[1] ?? '';
|
|
98
|
+
const tokens = (match[2] ?? '').split(/\s+/).filter((token) => token.length > 0);
|
|
99
|
+
const first = tokens[0];
|
|
100
|
+
if (!KNOWN_MARKERS.has(marker)) {
|
|
101
|
+
return {
|
|
102
|
+
kind: 'problem',
|
|
103
|
+
reason: `unknown marker "${marker}"`,
|
|
104
|
+
...(first !== undefined && ID_PATTERN.test(first) ? { id: first } : {}),
|
|
105
|
+
};
|
|
106
|
+
}
|
|
107
|
+
if (first === undefined || !ID_PATTERN.test(first)) {
|
|
108
|
+
return { kind: 'problem', reason: 'missing id' };
|
|
109
|
+
}
|
|
110
|
+
const title = tokens.slice(1).join(' ');
|
|
111
|
+
if (title === '')
|
|
112
|
+
return { kind: 'problem', reason: 'blank title', id: first };
|
|
113
|
+
return { kind: 'entry', marker, id: first, title };
|
|
114
|
+
}
|
|
115
|
+
function isIndented(line) {
|
|
116
|
+
return (line !== undefined &&
|
|
117
|
+
line.startsWith(' ') &&
|
|
118
|
+
line.trim() !== '' &&
|
|
119
|
+
!ENTRY_LINE.test(line) &&
|
|
120
|
+
!LOOSE_ENTRY.test(line));
|
|
121
|
+
}
|
|
122
|
+
function parseBacklog(text) {
|
|
123
|
+
const lines = text.split('\n').map((line) => (line.endsWith('\r') ? line.slice(0, -1) : line));
|
|
124
|
+
const outcomes = lines.map(parseEntryLine);
|
|
125
|
+
const linesById = new Map();
|
|
126
|
+
outcomes.forEach((outcome, i) => {
|
|
127
|
+
if (outcome.kind === 'none' || outcome.id === undefined)
|
|
128
|
+
return;
|
|
129
|
+
linesById.set(outcome.id, [...(linesById.get(outcome.id) ?? []), i + 1]);
|
|
130
|
+
});
|
|
131
|
+
const entries = [];
|
|
132
|
+
const problems = [];
|
|
133
|
+
outcomes.forEach((outcome, i) => {
|
|
134
|
+
if (outcome.kind === 'none')
|
|
135
|
+
return;
|
|
136
|
+
const copies = outcome.id === undefined ? undefined : linesById.get(outcome.id);
|
|
137
|
+
if (outcome.id !== undefined && copies !== undefined && copies.length > 1) {
|
|
138
|
+
problems.push({
|
|
139
|
+
line: i + 1,
|
|
140
|
+
id: outcome.id,
|
|
141
|
+
reason: `duplicate id ${outcome.id} (lines ${copies.join(', ')})`,
|
|
142
|
+
});
|
|
143
|
+
return;
|
|
144
|
+
}
|
|
145
|
+
if (outcome.kind === 'problem') {
|
|
146
|
+
problems.push({
|
|
147
|
+
line: i + 1,
|
|
148
|
+
reason: outcome.reason,
|
|
149
|
+
...(outcome.id !== undefined ? { id: outcome.id } : {}),
|
|
150
|
+
});
|
|
151
|
+
return;
|
|
152
|
+
}
|
|
153
|
+
const bad = (line, reason) => {
|
|
154
|
+
problems.push({ line, id: outcome.id, reason });
|
|
155
|
+
};
|
|
156
|
+
// Fixed-position lines, in the reference's order: requires, retracted,
|
|
157
|
+
// parent, body, then a late parent.
|
|
158
|
+
let cursor = i + 1;
|
|
159
|
+
let requires = [];
|
|
160
|
+
const requiresMatch = REQUIRES_LINE.exec(lines[cursor] ?? '');
|
|
161
|
+
if (requiresMatch !== null) {
|
|
162
|
+
const tokens = (requiresMatch[1] ?? '')
|
|
163
|
+
.split(',')
|
|
164
|
+
.map((token) => token.trim())
|
|
165
|
+
.filter((token) => token.length > 0);
|
|
166
|
+
if (tokens.length === 0)
|
|
167
|
+
return bad(cursor + 1, 'blank requires line');
|
|
168
|
+
const invalid = tokens.find((token) => !ID_PATTERN.test(token));
|
|
169
|
+
if (invalid !== undefined)
|
|
170
|
+
return bad(cursor + 1, `invalid id "${invalid}" in requires line`);
|
|
171
|
+
requires = tokens;
|
|
172
|
+
cursor += 1;
|
|
173
|
+
}
|
|
174
|
+
const retractedAt = cursor;
|
|
175
|
+
const retractedMatch = RETRACTED_LINE.exec(lines[cursor] ?? '');
|
|
176
|
+
const retractedReason = (retractedMatch?.[1] ?? '').trim();
|
|
177
|
+
if (retractedMatch !== null)
|
|
178
|
+
cursor += 1;
|
|
179
|
+
let parent;
|
|
180
|
+
let blankParentAt;
|
|
181
|
+
const readParent = () => {
|
|
182
|
+
const match = PARENT_LINE.exec(lines[cursor] ?? '');
|
|
183
|
+
if (match === null)
|
|
184
|
+
return false;
|
|
185
|
+
const value = (match[1] ?? '').trim();
|
|
186
|
+
if (value === '')
|
|
187
|
+
blankParentAt = cursor + 1;
|
|
188
|
+
else
|
|
189
|
+
parent = value;
|
|
190
|
+
cursor += 1;
|
|
191
|
+
return true;
|
|
192
|
+
};
|
|
193
|
+
const earlyParent = readParent();
|
|
194
|
+
if (BODY_LINE.test(lines[cursor] ?? ''))
|
|
195
|
+
cursor += 1;
|
|
196
|
+
if (!earlyParent)
|
|
197
|
+
readParent();
|
|
198
|
+
if (retractedMatch !== null && retractedReason === '') {
|
|
199
|
+
return bad(retractedAt + 1, 'blank retracted line');
|
|
200
|
+
}
|
|
201
|
+
if (blankParentAt !== undefined)
|
|
202
|
+
return bad(blankParentAt, 'blank parent line');
|
|
203
|
+
if (outcome.marker === 'R' && retractedMatch === null) {
|
|
204
|
+
return bad(i + 1, 'retracted entry has no retracted: reason line');
|
|
205
|
+
}
|
|
206
|
+
if (outcome.marker !== 'R' && retractedMatch !== null) {
|
|
207
|
+
return bad(retractedAt + 1, 'retracted: line present on a non-retracted entry');
|
|
208
|
+
}
|
|
209
|
+
let end = i + 1;
|
|
210
|
+
while (isIndented(lines[end]))
|
|
211
|
+
end += 1;
|
|
212
|
+
const indented = lines.slice(i + 1, end).map((line) => line.slice(2));
|
|
213
|
+
const text = indented.join('\n');
|
|
214
|
+
const blockedOn = Array.from(text.matchAll(BLOCKED_ON), (m) => m[1] ?? '');
|
|
215
|
+
entries.push({
|
|
216
|
+
line: i + 1,
|
|
217
|
+
marker: outcome.marker,
|
|
218
|
+
id: outcome.id,
|
|
219
|
+
title: outcome.title,
|
|
220
|
+
body: indented.length > 0 ? text : outcome.title,
|
|
221
|
+
requires: Array.from(new Set([...requires, ...blockedOn])),
|
|
222
|
+
...(parent !== undefined ? { parent } : {}),
|
|
223
|
+
...(retractedMatch !== null ? { retractedReason } : {}),
|
|
224
|
+
});
|
|
225
|
+
});
|
|
226
|
+
// Indented text that no card line directly precedes is attached to nothing.
|
|
227
|
+
const consumed = new Set();
|
|
228
|
+
outcomes.forEach((outcome, i) => {
|
|
229
|
+
if (outcome.kind === 'none')
|
|
230
|
+
return;
|
|
231
|
+
for (let j = i + 1; isIndented(lines[j]); j += 1)
|
|
232
|
+
consumed.add(j);
|
|
233
|
+
});
|
|
234
|
+
lines.forEach((line, i) => {
|
|
235
|
+
if (outcomes[i]?.kind !== 'none' || consumed.has(i) || !/^[ \t]+\S/.test(line))
|
|
236
|
+
return;
|
|
237
|
+
problems.push({
|
|
238
|
+
line: i + 1,
|
|
239
|
+
reason: 'indented text attached to no card (it must directly follow a card line)',
|
|
240
|
+
});
|
|
241
|
+
});
|
|
242
|
+
problems.sort((a, b) => a.line - b.line);
|
|
243
|
+
return { entries, problems };
|
|
244
|
+
}
|
|
245
|
+
function describe(cause) {
|
|
246
|
+
return cause instanceof Error ? cause.message : String(cause);
|
|
247
|
+
}
|
|
248
|
+
export function createBacklogBoard(options) {
|
|
249
|
+
const statusMap = options.statusMap ?? BACKLOG_STATUS_MAP;
|
|
250
|
+
function toCard(entry) {
|
|
251
|
+
const derived = normalizeStatus(entry.marker, statusMap);
|
|
252
|
+
return {
|
|
253
|
+
id: entry.id,
|
|
254
|
+
state: entry.marker,
|
|
255
|
+
reference: `BACKLOG.md:${entry.line}`,
|
|
256
|
+
source: 'backlog',
|
|
257
|
+
unknownFields: {},
|
|
258
|
+
title: entry.title,
|
|
259
|
+
body: entry.body,
|
|
260
|
+
requires: entry.requires,
|
|
261
|
+
...(entry.parent !== undefined ? { parent: entry.parent } : {}),
|
|
262
|
+
...(entry.retractedReason !== undefined
|
|
263
|
+
? { properties: { retracted: entry.retractedReason } }
|
|
264
|
+
: {}),
|
|
265
|
+
...(derived.kind === 'mapped' ? { status: derived.status } : {}),
|
|
266
|
+
};
|
|
267
|
+
}
|
|
268
|
+
function toUnparseable(bad) {
|
|
269
|
+
const problems = [{ field: 'line', message: `line ${bad.line}: ${bad.reason}` }];
|
|
270
|
+
return { id: bad.id ?? `line:${bad.line}`, problems };
|
|
271
|
+
}
|
|
272
|
+
return {
|
|
273
|
+
async get(id) {
|
|
274
|
+
let parsed;
|
|
275
|
+
try {
|
|
276
|
+
parsed = parseBacklog(await options.read());
|
|
277
|
+
}
|
|
278
|
+
catch (cause) {
|
|
279
|
+
return { outcome: 'unreachable', reason: describe(cause) };
|
|
280
|
+
}
|
|
281
|
+
const entry = parsed.entries.find((candidate) => candidate.id === id);
|
|
282
|
+
if (entry !== undefined)
|
|
283
|
+
return { outcome: 'found', card: toCard(entry) };
|
|
284
|
+
const bad = parsed.problems.filter((problem) => problem.id === id);
|
|
285
|
+
if (bad.length > 0) {
|
|
286
|
+
return {
|
|
287
|
+
outcome: 'unparseable',
|
|
288
|
+
id,
|
|
289
|
+
problems: bad.flatMap((problem) => toUnparseable(problem).problems),
|
|
290
|
+
};
|
|
291
|
+
}
|
|
292
|
+
return { outcome: 'absent' };
|
|
293
|
+
},
|
|
294
|
+
async list() {
|
|
295
|
+
let parsed;
|
|
296
|
+
try {
|
|
297
|
+
parsed = parseBacklog(await options.read());
|
|
298
|
+
}
|
|
299
|
+
catch (cause) {
|
|
300
|
+
return { outcome: 'unreachable', reason: describe(cause) };
|
|
301
|
+
}
|
|
302
|
+
if (parsed.entries.length === 0 && parsed.problems.length === 0)
|
|
303
|
+
return { outcome: 'empty' };
|
|
304
|
+
const known = new Set([
|
|
305
|
+
...parsed.entries.map((entry) => entry.id),
|
|
306
|
+
...parsed.problems.flatMap((problem) => (problem.id === undefined ? [] : [problem.id])),
|
|
307
|
+
...(options.archived ?? []).map((entry) => entry.id),
|
|
308
|
+
]);
|
|
309
|
+
const referenced = Array.from(new Set(parsed.entries.flatMap((entry) => entry.requires)));
|
|
310
|
+
const dangling = referenced.filter((ref) => !known.has(ref)).sort();
|
|
311
|
+
return {
|
|
312
|
+
outcome: 'cards',
|
|
313
|
+
cards: parsed.entries.map(toCard),
|
|
314
|
+
unparseable: parsed.problems.map(toUnparseable),
|
|
315
|
+
danglingIds: dangling,
|
|
316
|
+
};
|
|
317
|
+
},
|
|
318
|
+
async writeState(id, state, writeOptions) {
|
|
319
|
+
if (writeOptions?.expectedRevision !== undefined) {
|
|
320
|
+
return {
|
|
321
|
+
outcome: 'unsupported',
|
|
322
|
+
id,
|
|
323
|
+
reason: 'a BACKLOG.md board has no revisions, so expectedRevision cannot be honoured',
|
|
324
|
+
};
|
|
325
|
+
}
|
|
326
|
+
if (!Object.prototype.hasOwnProperty.call(statusMap.toStatus, state)) {
|
|
327
|
+
return { outcome: 'refused', reason: `marker "${state}" is not in the status map` };
|
|
328
|
+
}
|
|
329
|
+
if (state.length !== 1 || !KNOWN_MARKERS.has(state)) {
|
|
330
|
+
return { outcome: 'refused', reason: `marker "${state}" is not a backlog marker` };
|
|
331
|
+
}
|
|
332
|
+
let text;
|
|
333
|
+
try {
|
|
334
|
+
text = await options.read();
|
|
335
|
+
}
|
|
336
|
+
catch (cause) {
|
|
337
|
+
return { outcome: 'unreachable', reason: describe(cause) };
|
|
338
|
+
}
|
|
339
|
+
const { entries, problems } = parseBacklog(text);
|
|
340
|
+
const entry = entries.find((candidate) => candidate.id === id);
|
|
341
|
+
if (entry === undefined) {
|
|
342
|
+
const bad = problems.find((problem) => problem.id === id);
|
|
343
|
+
return {
|
|
344
|
+
outcome: 'refused',
|
|
345
|
+
reason: bad === undefined
|
|
346
|
+
? `no card with id ${id}`
|
|
347
|
+
: `card ${id} is present but malformed on line ${bad.line} (${bad.reason})`,
|
|
348
|
+
};
|
|
349
|
+
}
|
|
350
|
+
if ((state === 'R') !== (entry.marker === 'R')) {
|
|
351
|
+
return {
|
|
352
|
+
outcome: 'refused',
|
|
353
|
+
reason: `moving card ${id} into or out of 'R' needs its retracted: line changed too; only the marker is writable here`,
|
|
354
|
+
};
|
|
355
|
+
}
|
|
356
|
+
const lines = text.split('\n');
|
|
357
|
+
const line = lines[entry.line - 1] ?? '';
|
|
358
|
+
// "- [" is three characters; the marker is the fourth.
|
|
359
|
+
lines[entry.line - 1] = `${line.slice(0, 3)}${state}${line.slice(4)}`;
|
|
360
|
+
try {
|
|
361
|
+
await options.write(lines.join('\n'));
|
|
362
|
+
}
|
|
363
|
+
catch (cause) {
|
|
364
|
+
return { outcome: 'unreachable', reason: describe(cause) };
|
|
365
|
+
}
|
|
366
|
+
return { outcome: 'applied' };
|
|
367
|
+
},
|
|
368
|
+
async createCard(card) {
|
|
369
|
+
return {
|
|
370
|
+
outcome: 'unsupported',
|
|
371
|
+
id: card.id,
|
|
372
|
+
reason: 'creating cards in BACKLOG.md is not supported yet',
|
|
373
|
+
};
|
|
374
|
+
},
|
|
375
|
+
async annotate(id) {
|
|
376
|
+
return {
|
|
377
|
+
outcome: 'unsupported',
|
|
378
|
+
id,
|
|
379
|
+
reason: 'annotating cards in BACKLOG.md is not supported yet',
|
|
380
|
+
};
|
|
381
|
+
},
|
|
382
|
+
};
|
|
383
|
+
}
|
package/dist/board.d.ts
CHANGED
|
@@ -96,6 +96,7 @@ export type GetResult = {
|
|
|
96
96
|
readonly card: Card;
|
|
97
97
|
} | {
|
|
98
98
|
readonly outcome: 'absent';
|
|
99
|
+
readonly reason?: string;
|
|
99
100
|
} | {
|
|
100
101
|
readonly outcome: 'unreachable';
|
|
101
102
|
readonly reason: string;
|
|
@@ -157,6 +158,7 @@ export type ListResult = {
|
|
|
157
158
|
} | {
|
|
158
159
|
readonly outcome: 'unreachable';
|
|
159
160
|
readonly reason: string;
|
|
161
|
+
readonly notFound?: true;
|
|
160
162
|
};
|
|
161
163
|
/**
|
|
162
164
|
* Options threading an optimistic-concurrency guard through a write.
|
|
@@ -182,14 +184,31 @@ export interface WriteOptions {
|
|
|
182
184
|
readonly expectedRevision?: string;
|
|
183
185
|
}
|
|
184
186
|
/**
|
|
185
|
-
* The patch `CardSink.annotate` applies: a flat
|
|
187
|
+
* The patch `CardSink.annotate` applies: a flat bag of strings and numbers
|
|
186
188
|
* merged into a card's own `properties`, never touching `state`. Used
|
|
187
189
|
* for facts about a card's history that are not a column — a block or
|
|
188
190
|
* retract reason, a recorded PR url.
|
|
189
191
|
*/
|
|
190
192
|
export interface AnnotatePatch {
|
|
191
|
-
readonly properties: Readonly<Record<string, string>>;
|
|
193
|
+
readonly properties: Readonly<Record<string, string | number>>;
|
|
192
194
|
}
|
|
195
|
+
/**
|
|
196
|
+
* How a board that stores only flat string properties (in-memory, payload,
|
|
197
|
+
* store, ASF) takes a numeric patch value: `String(n)`, deterministically,
|
|
198
|
+
* so `1234.5` is stored as `"1234.5"`. A non-finite number is refused
|
|
199
|
+
* before this is called (see `nonFiniteNumberReason`), never stored as
|
|
200
|
+
* `"NaN"`. A board with typed number
|
|
201
|
+
* properties (Notion) writes the number itself instead; a board that
|
|
202
|
+
* cannot annotate at all (Trello) refuses before it ever looks.
|
|
203
|
+
*/
|
|
204
|
+
export declare function stringifyPatchProperties(properties: Readonly<Record<string, string | number>>): Record<string, string>;
|
|
205
|
+
/**
|
|
206
|
+
* The reason a flat-string board refuses a patch, or `undefined` if it has
|
|
207
|
+
* none: a `NaN` or `Infinity` value would otherwise be stored as the string
|
|
208
|
+
* `"NaN"` or `"Infinity"`. Each such board answers `refused` with this text,
|
|
209
|
+
* matching what the Notion board does for the same patch.
|
|
210
|
+
*/
|
|
211
|
+
export declare function nonFiniteNumberReason(properties: Readonly<Record<string, string | number>>): string | undefined;
|
|
193
212
|
/**
|
|
194
213
|
* The write half: changes a card's state, creates cards, and patches a
|
|
195
214
|
* card's properties. Nothing else about a card is writable through it.
|
package/dist/board.js
CHANGED
|
@@ -3,4 +3,33 @@
|
|
|
3
3
|
// into a specific tracker's SDK — that is `sources`' job and a concrete
|
|
4
4
|
// adapter's job, not this file's. This is the shape both halves share,
|
|
5
5
|
// whatever backs them.
|
|
6
|
-
|
|
6
|
+
/**
|
|
7
|
+
* How a board that stores only flat string properties (in-memory, payload,
|
|
8
|
+
* store, ASF) takes a numeric patch value: `String(n)`, deterministically,
|
|
9
|
+
* so `1234.5` is stored as `"1234.5"`. A non-finite number is refused
|
|
10
|
+
* before this is called (see `nonFiniteNumberReason`), never stored as
|
|
11
|
+
* `"NaN"`. A board with typed number
|
|
12
|
+
* properties (Notion) writes the number itself instead; a board that
|
|
13
|
+
* cannot annotate at all (Trello) refuses before it ever looks.
|
|
14
|
+
*/
|
|
15
|
+
export function stringifyPatchProperties(properties) {
|
|
16
|
+
const out = {};
|
|
17
|
+
for (const [key, value] of Object.entries(properties)) {
|
|
18
|
+
out[key] = typeof value === 'number' ? String(value) : value;
|
|
19
|
+
}
|
|
20
|
+
return out;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* The reason a flat-string board refuses a patch, or `undefined` if it has
|
|
24
|
+
* none: a `NaN` or `Infinity` value would otherwise be stored as the string
|
|
25
|
+
* `"NaN"` or `"Infinity"`. Each such board answers `refused` with this text,
|
|
26
|
+
* matching what the Notion board does for the same patch.
|
|
27
|
+
*/
|
|
28
|
+
export function nonFiniteNumberReason(properties) {
|
|
29
|
+
for (const [key, value] of Object.entries(properties)) {
|
|
30
|
+
if (typeof value === 'number' && !Number.isFinite(value)) {
|
|
31
|
+
return `property "${key}" is ${String(value)}, not a finite number, so it is not written`;
|
|
32
|
+
}
|
|
33
|
+
}
|
|
34
|
+
return undefined;
|
|
35
|
+
}
|
package/dist/card.d.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { Status } from './status.js';
|
|
1
2
|
/**
|
|
2
3
|
* `state` is deliberately not a union, and it must not become one.
|
|
3
4
|
*
|
|
@@ -11,6 +12,16 @@
|
|
|
11
12
|
* Leave it a string.
|
|
12
13
|
*/
|
|
13
14
|
export type State = string;
|
|
15
|
+
/**
|
|
16
|
+
* A JSON-safe value: a string, number, boolean, `null`, or an array or
|
|
17
|
+
* plain object built only from more of the same -- exactly what
|
|
18
|
+
* `JSON.parse`/`JSON.stringify` round-trip without loss. `Card.properties`
|
|
19
|
+
* is typed to this, and nothing wider: no function, no `Date`, nothing a
|
|
20
|
+
* tracker's own JSON API could never actually hand back.
|
|
21
|
+
*/
|
|
22
|
+
export type PropertyValue = string | number | boolean | null | readonly PropertyValue[] | {
|
|
23
|
+
readonly [key: string]: PropertyValue;
|
|
24
|
+
};
|
|
14
25
|
export interface Card {
|
|
15
26
|
readonly id: string;
|
|
16
27
|
readonly state: State;
|
|
@@ -46,16 +57,45 @@ export interface Card {
|
|
|
46
57
|
*/
|
|
47
58
|
readonly revision?: string;
|
|
48
59
|
/**
|
|
49
|
-
* A
|
|
50
|
-
*
|
|
51
|
-
*
|
|
52
|
-
* `CardSink.annotate`). Distinct
|
|
53
|
-
* is whatever a specific adapter
|
|
54
|
-
* `properties` is this boundary's
|
|
55
|
-
* through the shared contract
|
|
56
|
-
* extension fields.
|
|
60
|
+
* A bag a board can patch without touching `state` — a block or
|
|
61
|
+
* retract reason, a recorded PR url, a custom field the underlying
|
|
62
|
+
* tracker carries on the task itself — anything that is a fact about
|
|
63
|
+
* the card rather than its column (see `CardSink.annotate`). Distinct
|
|
64
|
+
* from `unknownFields`: `unknownFields` is whatever a specific adapter
|
|
65
|
+
* cannot map into this shape at all; `properties` is this boundary's
|
|
66
|
+
* own surface, explicitly annotatable through the shared contract
|
|
67
|
+
* rather than left to each adapter's own extension fields.
|
|
68
|
+
*
|
|
69
|
+
* Values are `PropertyValue` — JSON-safe, never narrower than that. A
|
|
70
|
+
* flat string-to-string bag (`isStringRecord`'s contract, below) is
|
|
71
|
+
* one valid shape this can hold, and remains the ONLY shape `parseCard`
|
|
72
|
+
* accepts on the way in from an untrusted payload (see `payload.ts`,
|
|
73
|
+
* which keeps every tracker-shaped or otherwise non-flat-string value
|
|
74
|
+
* in `unknownFields` instead) — but a board that builds a `Card`
|
|
75
|
+
* directly from its own already-typed read, rather than parsing one
|
|
76
|
+
* from an untrusted payload (e.g. `asfBoard`), may populate an array,
|
|
77
|
+
* a number, or a nested object here: a custom property a tracker's
|
|
78
|
+
* own API already hands back as JSON, carried through verbatim rather
|
|
79
|
+
* than demoted to `unknownFields` for not being a plain string.
|
|
80
|
+
*/
|
|
81
|
+
readonly properties?: Readonly<Record<string, PropertyValue>>;
|
|
82
|
+
/** Human-readable title. */
|
|
83
|
+
readonly title?: string;
|
|
84
|
+
/** Markdown body. */
|
|
85
|
+
readonly body?: string;
|
|
86
|
+
/** Prerequisite card ids, in this board's id space. */
|
|
87
|
+
readonly requires?: readonly string[];
|
|
88
|
+
/** Parent card id. */
|
|
89
|
+
readonly parent?: string;
|
|
90
|
+
/**
|
|
91
|
+
* Normalized status, derived by a board from its native `state` through
|
|
92
|
+
* a `StatusMap` the board owns. A board never stores it and ignores any
|
|
93
|
+
* supplied value. Absent when the board has no map or the state is
|
|
94
|
+
* unmapped. `state` stays the native name for round trips. (`parseCard`
|
|
95
|
+
* validates a `status` value when present; that is input validation,
|
|
96
|
+
* not storage.)
|
|
57
97
|
*/
|
|
58
|
-
readonly
|
|
98
|
+
readonly status?: Status;
|
|
59
99
|
}
|
|
60
100
|
export interface Problem {
|
|
61
101
|
readonly field: string;
|
|
@@ -69,14 +109,18 @@ export type ParseResult = {
|
|
|
69
109
|
readonly problems: readonly Problem[];
|
|
70
110
|
};
|
|
71
111
|
/**
|
|
72
|
-
* `Card.properties`'s own
|
|
73
|
-
*
|
|
74
|
-
*
|
|
75
|
-
*
|
|
76
|
-
*
|
|
77
|
-
* Notion page's nested `{select: {...}}` shape,
|
|
78
|
-
*
|
|
79
|
-
* not have.
|
|
112
|
+
* The flat string-to-string bag `Card.properties`'s own doc above still
|
|
113
|
+
* documents as ONE valid shape it can hold — and the only shape
|
|
114
|
+
* `parseCard`'s own validation below accepts, deliberately narrower
|
|
115
|
+
* than `Card.properties`'s own widened `PropertyValue` type: a payload
|
|
116
|
+
* parsed from an untrusted tracker (see `payload.ts`) is held to this
|
|
117
|
+
* stricter contract so a Notion page's nested `{select: {...}}` shape,
|
|
118
|
+
* for instance, is recognised as NOT this field and bucketed into
|
|
119
|
+
* `unknownFields` rather than cast into a shape it does not have. A
|
|
120
|
+
* board that builds a `Card` directly from its own already-typed read
|
|
121
|
+
* (e.g. `asfBoard`) is not bound by this function at all — see
|
|
122
|
+
* `Card.properties`'s own doc for why that is deliberate, not an
|
|
123
|
+
* oversight.
|
|
80
124
|
*/
|
|
81
125
|
export declare function isStringRecord(value: unknown): value is Record<string, string>;
|
|
82
126
|
/**
|
package/dist/card.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
// Card: the shape common across trackers, and it decides as little as
|
|
2
2
|
// possible on purpose. Anything a specific tracker needs beyond this is
|
|
3
3
|
// carried in `unknownFields`, not added here.
|
|
4
|
+
import { isStatus } from './status.js';
|
|
4
5
|
function isPlainObject(value) {
|
|
5
6
|
return typeof value === 'object' && value !== null && !Array.isArray(value);
|
|
6
7
|
}
|
|
@@ -8,14 +9,18 @@ function isNonEmptyString(value) {
|
|
|
8
9
|
return typeof value === 'string' && value.length > 0;
|
|
9
10
|
}
|
|
10
11
|
/**
|
|
11
|
-
* `Card.properties`'s own
|
|
12
|
-
*
|
|
13
|
-
*
|
|
14
|
-
*
|
|
15
|
-
*
|
|
16
|
-
* Notion page's nested `{select: {...}}` shape,
|
|
17
|
-
*
|
|
18
|
-
* not have.
|
|
12
|
+
* The flat string-to-string bag `Card.properties`'s own doc above still
|
|
13
|
+
* documents as ONE valid shape it can hold — and the only shape
|
|
14
|
+
* `parseCard`'s own validation below accepts, deliberately narrower
|
|
15
|
+
* than `Card.properties`'s own widened `PropertyValue` type: a payload
|
|
16
|
+
* parsed from an untrusted tracker (see `payload.ts`) is held to this
|
|
17
|
+
* stricter contract so a Notion page's nested `{select: {...}}` shape,
|
|
18
|
+
* for instance, is recognised as NOT this field and bucketed into
|
|
19
|
+
* `unknownFields` rather than cast into a shape it does not have. A
|
|
20
|
+
* board that builds a `Card` directly from its own already-typed read
|
|
21
|
+
* (e.g. `asfBoard`) is not bound by this function at all — see
|
|
22
|
+
* `Card.properties`'s own doc for why that is deliberate, not an
|
|
23
|
+
* oversight.
|
|
19
24
|
*/
|
|
20
25
|
export function isStringRecord(value) {
|
|
21
26
|
return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === 'string');
|
|
@@ -71,6 +76,26 @@ export function parseCard(shape) {
|
|
|
71
76
|
message: 'properties must be an object with only string values when present',
|
|
72
77
|
});
|
|
73
78
|
}
|
|
79
|
+
if (candidate.title !== undefined && typeof candidate.title !== 'string') {
|
|
80
|
+
problems.push({ field: 'title', message: 'title must be a string when present' });
|
|
81
|
+
}
|
|
82
|
+
if (candidate.body !== undefined && typeof candidate.body !== 'string') {
|
|
83
|
+
problems.push({ field: 'body', message: 'body must be a string when present' });
|
|
84
|
+
}
|
|
85
|
+
if (candidate.requires !== undefined &&
|
|
86
|
+
!(Array.isArray(candidate.requires) &&
|
|
87
|
+
candidate.requires.every((entry) => typeof entry === 'string'))) {
|
|
88
|
+
problems.push({
|
|
89
|
+
field: 'requires',
|
|
90
|
+
message: 'requires must be an array of strings when present',
|
|
91
|
+
});
|
|
92
|
+
}
|
|
93
|
+
if (candidate.parent !== undefined && typeof candidate.parent !== 'string') {
|
|
94
|
+
problems.push({ field: 'parent', message: 'parent must be a string when present' });
|
|
95
|
+
}
|
|
96
|
+
if (candidate.status !== undefined && !isStatus(candidate.status)) {
|
|
97
|
+
problems.push({ field: 'status', message: 'status must be a known Status when present' });
|
|
98
|
+
}
|
|
74
99
|
if (problems.length > 0) {
|
|
75
100
|
return { ok: false, problems };
|
|
76
101
|
}
|
|
@@ -84,6 +109,11 @@ export function parseCard(shape) {
|
|
|
84
109
|
unknownFields: candidate.unknownFields,
|
|
85
110
|
...(typeof candidate.revision === 'string' ? { revision: candidate.revision } : {}),
|
|
86
111
|
...(isStringRecord(candidate.properties) ? { properties: candidate.properties } : {}),
|
|
112
|
+
...(typeof candidate.title === 'string' ? { title: candidate.title } : {}),
|
|
113
|
+
...(typeof candidate.body === 'string' ? { body: candidate.body } : {}),
|
|
114
|
+
...(Array.isArray(candidate.requires) ? { requires: candidate.requires } : {}),
|
|
115
|
+
...(typeof candidate.parent === 'string' ? { parent: candidate.parent } : {}),
|
|
116
|
+
...(isStatus(candidate.status) ? { status: candidate.status } : {}),
|
|
87
117
|
},
|
|
88
118
|
};
|
|
89
119
|
}
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { Card } from './card.js';
|
|
2
|
+
import type { StatusMap } from './status.js';
|
|
2
3
|
import type { CardSource, CardSink } from './board.js';
|
|
3
4
|
export interface InMemoryBoard extends CardSource, CardSink {
|
|
4
5
|
/**
|
|
@@ -13,4 +14,15 @@ export interface InMemoryBoard extends CardSource, CardSink {
|
|
|
13
14
|
/** Puts a card directly into the fake board, for setting up a scenario. */
|
|
14
15
|
put(card: Card): void;
|
|
15
16
|
}
|
|
16
|
-
export
|
|
17
|
+
export interface InMemoryBoardOptions {
|
|
18
|
+
/**
|
|
19
|
+
* When given, every card returned by `get` and `list` carries a `status`
|
|
20
|
+
* derived from its native `state` through this map. A state the map does
|
|
21
|
+
* not know leaves `status` absent (the native `state` is still returned).
|
|
22
|
+
* With no map, `status` is absent. Either way a `status` supplied on a
|
|
23
|
+
* card (seeded, `put` or `createCard`) is ignored: the board never
|
|
24
|
+
* returns a stored status.
|
|
25
|
+
*/
|
|
26
|
+
readonly statusMap?: StatusMap;
|
|
27
|
+
}
|
|
28
|
+
export declare function createInMemoryBoard(initial?: readonly Card[], options?: InMemoryBoardOptions): InMemoryBoard;
|