@verevoir/aigency-work 0.2.0 → 0.3.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 +126 -0
- package/dist/asf-board.js +112 -39
- package/dist/backlog-board.d.ts +21 -0
- package/dist/backlog-board.js +383 -0
- 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 +17 -2
- package/dist/index.d.ts +11 -3
- package/dist/index.js +5 -1
- package/dist/notion-board.d.ts +33 -0
- package/dist/notion-board.js +515 -4
- package/dist/status.d.ts +24 -0
- package/dist/status.js +36 -0
- 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/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;
|
package/dist/in-memory-board.js
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
// stand in for a real tracker in a demo or a test. A card moving needs
|
|
3
3
|
// something to move it on, and a tracker nobody has access to cannot be
|
|
4
4
|
// that thing.
|
|
5
|
-
|
|
5
|
+
import { normalizeStatus } from './status.js';
|
|
6
|
+
export function createInMemoryBoard(initial = [], options = {}) {
|
|
7
|
+
const statusMap = options.statusMap;
|
|
6
8
|
const cards = new Map();
|
|
7
9
|
const revisions = new Map();
|
|
8
10
|
for (const card of initial) {
|
|
@@ -25,7 +27,20 @@ export function createInMemoryBoard(initial = []) {
|
|
|
25
27
|
delete copy.revision;
|
|
26
28
|
return copy;
|
|
27
29
|
}
|
|
28
|
-
|
|
30
|
+
// Status is derived on the way out, never stored independently, so it
|
|
31
|
+
// cannot contradict `state`. Any supplied status is dropped; with no map
|
|
32
|
+
// there is nothing to derive it from, so it stays absent.
|
|
33
|
+
function withDerivedStatus(card) {
|
|
34
|
+
const rest = { ...card };
|
|
35
|
+
delete rest.status;
|
|
36
|
+
if (statusMap === undefined) {
|
|
37
|
+
return rest;
|
|
38
|
+
}
|
|
39
|
+
const derived = normalizeStatus(card.state, statusMap);
|
|
40
|
+
return derived.kind === 'mapped' ? { ...rest, status: derived.status } : rest;
|
|
41
|
+
}
|
|
42
|
+
function withRevision(stored, id) {
|
|
43
|
+
const card = withDerivedStatus(stored);
|
|
29
44
|
const revision = revisions.get(id);
|
|
30
45
|
return revision === undefined ? card : { ...card, revision: String(revision) };
|
|
31
46
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,12 +1,20 @@
|
|
|
1
1
|
export { parseCard } from './card.js';
|
|
2
2
|
export type { Card, Problem, ParseResult, State } from './card.js';
|
|
3
|
-
export
|
|
3
|
+
export { normalizeStatus, nativeStateFor } from './status.js';
|
|
4
|
+
export type { Status, StatusMap, NormalizeResult, NativeStateResult } from './status.js';
|
|
5
|
+
export type { CardSource, CardSink, GetResult, ListResult, WriteResult, UnparseableRecord, AnnotatePatch, WriteOptions, CardClaimer, ClaimResult, NominateClaimResult, CompletionOptions, CompletionResult, RunOutcome, } from './board.js';
|
|
4
6
|
export { createInMemoryBoard } from './in-memory-board.js';
|
|
5
|
-
export type { InMemoryBoard } from './in-memory-board.js';
|
|
7
|
+
export type { InMemoryBoard, InMemoryBoardOptions } from './in-memory-board.js';
|
|
6
8
|
export { createPayloadBoard } from './payload-board.js';
|
|
7
9
|
export type { PayloadBoard } from './payload-board.js';
|
|
8
|
-
export { createNotionBoard, NOTION_VERSION } from './notion-board.js';
|
|
10
|
+
export { createNotionBoard, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP } from './notion-board.js';
|
|
9
11
|
export type { NotionBoard, NotionBoardConfig, NotionFetch, NotionFetchInit, NotionFetchResponse, } from './notion-board.js';
|
|
12
|
+
export { createTrelloBoard } from './trello-board.js';
|
|
13
|
+
export type { TrelloBoard, TrelloBoardConfig, TrelloFetch, TrelloFetchInit, TrelloFetchResponse, } from './trello-board.js';
|
|
14
|
+
export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
|
|
15
|
+
export type { BacklogBoardOptions } from './backlog-board.js';
|
|
16
|
+
export { asfBoard } from './asf-board.js';
|
|
17
|
+
export type { AsfBoardOptions, AsfFetch, AsfFetchInit, AsfFetchResponse } from './asf-board.js';
|
|
10
18
|
export { parseCardPayload, renderCardPayload } from './payload.js';
|
|
11
19
|
export { moveCard } from './move-card.js';
|
|
12
20
|
export type { MoveCardRequest, MoveResult } from './move-card.js';
|
package/dist/index.js
CHANGED
|
@@ -3,9 +3,13 @@
|
|
|
3
3
|
// typecheck, lint and test — is gone: this project's first real export has
|
|
4
4
|
// landed, which was the condition it was written to be removed on.
|
|
5
5
|
export { parseCard } from './card.js';
|
|
6
|
+
export { normalizeStatus, nativeStateFor } from './status.js';
|
|
6
7
|
export { createInMemoryBoard } from './in-memory-board.js';
|
|
7
8
|
export { createPayloadBoard } from './payload-board.js';
|
|
8
|
-
export { createNotionBoard, NOTION_VERSION } from './notion-board.js';
|
|
9
|
+
export { createNotionBoard, NOTION_VERSION, NOTION_DEFAULT_STATUS_MAP } from './notion-board.js';
|
|
10
|
+
export { createTrelloBoard } from './trello-board.js';
|
|
11
|
+
export { createBacklogBoard, BACKLOG_STATUS_MAP } from './backlog-board.js';
|
|
12
|
+
export { asfBoard } from './asf-board.js';
|
|
9
13
|
export { parseCardPayload, renderCardPayload } from './payload.js';
|
|
10
14
|
export { moveCard } from './move-card.js';
|
|
11
15
|
export { assessUnparseable } from './schema-change.js';
|