@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.
@@ -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 flat string-to-string bag a board can patch without touching
50
- * `state` — a block or retract reason, a recorded PR url, anything
51
- * that is a fact about the card rather than its column (see
52
- * `CardSink.annotate`). Distinct from `unknownFields`: `unknownFields`
53
- * is whatever a specific adapter cannot map into this shape at all;
54
- * `properties` is this boundary's own surface, explicitly annotatable
55
- * through the shared contract rather than left to each adapter's own
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 properties?: Readonly<Record<string, string>>;
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 contract is a flat string-to-string bag (see
73
- * its doc above) — this is the one check that decides whether a given
74
- * value actually is one. Exported because `payload.ts` needs the exact
75
- * same decision to decide whether a payload's `properties` key is this
76
- * boundary's own known field at all, or merely shares its name (a
77
- * Notion page's nested `{select: {...}}` shape, for instance) and
78
- * belongs in `unknownFields` instead of being cast into a shape it does
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 contract is a flat string-to-string bag (see
12
- * its doc above) — this is the one check that decides whether a given
13
- * value actually is one. Exported because `payload.ts` needs the exact
14
- * same decision to decide whether a payload's `properties` key is this
15
- * boundary's own known field at all, or merely shares its name (a
16
- * Notion page's nested `{select: {...}}` shape, for instance) and
17
- * belongs in `unknownFields` instead of being cast into a shape it does
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 declare function createInMemoryBoard(initial?: readonly Card[]): InMemoryBoard;
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;
@@ -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
- export function createInMemoryBoard(initial = []) {
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
- function withRevision(card, id) {
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 type { CardSource, CardSink, GetResult, ListResult, WriteResult, UnparseableRecord, } from './board.js';
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';