gcf-aif-ext 0.16.1 → 0.18.3

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/lib/bundle.js CHANGED
@@ -1,18 +1,22 @@
1
- // The structured entry (GCF-PRD §11.10): `design export` glues game.md, glossary.md and the
2
- // units into one bundle a designer edits; `design import` brings it back without a model.
1
+ // The structured entry (GCF-PRD §11.10): `design export` glues game.md, glossary.md, PILLARS.md
2
+ // and the units into one bundle a designer edits; `design import` brings it back without a
3
+ // model. A board's form saves one part the same way (`design save`, lib/design-parts.js).
3
4
  // Each part carries the hash it was exported with, so an import tells a designer's edit from
4
5
  // an edit made in gcf/ after the export — and never overwrites the second one silently.
5
6
  import { readFile } from 'node:fs/promises';
6
7
  import { existsSync } from 'node:fs';
7
8
  import { createHash } from 'node:crypto';
8
9
  import path from 'node:path';
9
- import { readDesign, SLUG_RE } from './design.js';
10
+ import { bodyIssues } from 'cnlp-kit';
11
+ import { readDesign, loadDocProfile, PILLARS_MAX, SLUG_RE } from './design.js';
10
12
  import { buildLedger } from './ledger.js';
11
- import { designCheck } from './design-check.js';
13
+ import { designCheck, recordsIn } from './design-check.js';
12
14
  import { atomicWrite, withFileRollback, resolveInside } from './safe-path.js';
13
15
  import { writeIndex } from './index-gen.js';
14
16
 
15
- const DOCS = ['game', 'glossary'];
17
+ // The singleton documents a bundle carries, each with its file under gcf/.
18
+ export const DOC_FILES = { game: 'game.md', glossary: 'glossary.md', pillars: 'PILLARS.md' };
19
+ const DOCS = Object.keys(DOC_FILES);
16
20
  // A part opens with a marker comment, not with a heading: a `# notes` line inside game.md or a
17
21
  // purpose is content, and a heading boundary would cut the document there.
18
22
  const PART_RE =
@@ -25,13 +29,13 @@ export const hashOf = (text) =>
25
29
  createHash('sha1').update(String(text).replace(/\r\n/g, '\n').trim()).digest('hex').slice(0, 8);
26
30
 
27
31
  /** The text of one unit as it stands in its design file: header and body, no heading. */
28
- function unitText(u) {
32
+ export function unitText(u) {
29
33
  const header = Object.entries(u.header).map(([k, v]) => `${k}: ${v}`);
30
34
 
31
35
  return `${header.join('\n')}\n\n${u.body.trim()}`.trim();
32
36
  }
33
37
 
34
- const purposeOf = (preamble) =>
38
+ export const purposeOf = (preamble) =>
35
39
  preamble
36
40
  .trimStart()
37
41
  .replace(/^# .*\n?/, '')
@@ -49,7 +53,7 @@ export async function exportBundle(projectDir, { system = null, milestone = null
49
53
  // A doc goes as it stands, its own heading included: a title added over it would be a second
50
54
  // `# game` a designer deletes, and the import could not tell which one was the file's.
51
55
  for (const name of DOCS) {
52
- const file = path.join(root, `${name}.md`);
56
+ const file = path.join(root, DOC_FILES[name]);
53
57
  if (existsSync(file)) part(`doc ${name}`, [], (await readFile(file, 'utf8')).trim());
54
58
  }
55
59
 
@@ -133,7 +137,7 @@ function verdict(part, current) {
133
137
  async function currentParts(root) {
134
138
  const cur = new Map();
135
139
  for (const name of DOCS) {
136
- const file = path.join(root, `${name}.md`);
140
+ const file = path.join(root, DOC_FILES[name]);
137
141
  if (existsSync(file)) cur.set(`doc:${name}`, (await readFile(file, 'utf8')).trim());
138
142
  }
139
143
 
@@ -223,7 +227,7 @@ const NOTES = {
223
227
  /** The file each write touches. */
224
228
  function fileOf(root, w) {
225
229
  // validName already holds a doc to DOCS; resolveInside is the second lock on the path.
226
- if (w.kind === 'doc') return resolveInside(root, `${w.name}.md`);
230
+ if (w.kind === 'doc') return resolveInside(root, DOC_FILES[w.name]);
227
231
 
228
232
  return resolveInside(path.join(root, 'design'), `${w.kind === 'system' ? w.name : w.system}.md`);
229
233
  }
@@ -233,8 +237,11 @@ async function applyWrite(root, w) {
233
237
  const text = existsSync(file)
234
238
  ? await readFile(file, 'utf8')
235
239
  : `# ${w.system ?? w.name}\n\npurpose: TBD\n`;
236
- if (w.kind === 'doc') return atomicWrite(file, `${w.text}\n`);
237
- if (w.kind === 'system') return atomicWrite(file, putPurpose(text, w.name, w.text));
240
+ // A file kept with CRLF stays CRLF: the part comes in LF.
241
+ const eol = text.match(/\r?\n/)?.[0] ?? '\n';
242
+ const own = (t) => t.replace(/\r\n/g, '\n').replace(/\n/g, eol);
243
+ if (w.kind === 'doc') return atomicWrite(file, own(`${w.text}\n`));
244
+ if (w.kind === 'system') return atomicWrite(file, own(putPurpose(text, w.name, w.text)));
238
245
  await atomicWrite(file, putUnit(text, w.name, w.text));
239
246
  if (w.outcome !== 'new') return;
240
247
  const backlog = path.join(root, 'backlog.md');
@@ -242,6 +249,32 @@ async function applyWrite(root, w) {
242
249
  await atomicWrite(backlog, `${order}\n- ${w.name}\n`.replace(/^\n/, ''));
243
250
  }
244
251
 
252
+ /**
253
+ * Why a new PILLARS.md text may not land, or null. The design check does not read the file's
254
+ * shape, so the import does: a pillar id that units cite goes only by its own move (rename,
255
+ * retire), which follows every citation and keeps the reason.
256
+ */
257
+ async function pillarsProblem(text, current) {
258
+ const records = recordsIn(text, 'pillars');
259
+ const ids = records.map((p) => p.id).filter(Boolean);
260
+ const lost = recordsIn(current ?? '', 'pillars')
261
+ .map((p) => p.id)
262
+ .filter((id) => id && !ids.includes(id));
263
+ if (lost.length)
264
+ return (
265
+ `pillar ${lost.join(', ')} left the text: a pillar id goes by gcf pillar rename, ` +
266
+ 'or by gcf pillar retire with a reason'
267
+ );
268
+ const twice = ids.filter((id, i) => ids.indexOf(id) !== i);
269
+ if (twice.length) return `pillar id ${twice[0]} is there twice`;
270
+ const bad = ids.filter((id) => !SLUG_RE.test(id));
271
+ if (bad.length) return `pillar id ${bad[0]}: a pillar id is a lowercase hyphen slug`;
272
+ if (records.length > PILLARS_MAX) return `${records.length} pillars: at most ${PILLARS_MAX}`;
273
+ const shape = bodyIssues(text, await loadDocProfile('pillars'));
274
+
275
+ return shape.length ? shape.map((i) => `line ${i.line}: ${i.message}`).join('; ') : null;
276
+ }
277
+
245
278
  /**
246
279
  * Bring a bundle back into gcf/. A part the bundle changed and gcf/ did not is written; a part
247
280
  * both changed is reported, never merged. Writes land only if the design check after them has
@@ -251,7 +284,19 @@ export async function importBundle(projectDir, bundleText) {
251
284
  const root = path.join(path.resolve(projectDir), 'gcf');
252
285
  const bundle = parseBundle(bundleText);
253
286
  const ledger = await buildLedger(projectDir);
254
- const { writes, report } = plan(bundle, await currentParts(root), ledger);
287
+ const current = await currentParts(root);
288
+ const planned = plan(bundle, current, ledger);
289
+ const { report } = planned;
290
+ const writes = [];
291
+ for (const w of planned.writes) {
292
+ const problem =
293
+ w.kind === 'doc' && w.name === 'pillars'
294
+ ? await pillarsProblem(w.text, current.get('doc:pillars'))
295
+ : null;
296
+ if (problem) report.push({ part: 'doc:pillars', outcome: 'invalid', note: problem });
297
+ else writes.push(w);
298
+ }
299
+
255
300
  const applied = writes.map((w) => `${w.kind}:${w.name} (${w.outcome})`);
256
301
  if (!writes.length) return { applied, report };
257
302
  // Only the findings the bundle brings refuse it: a project with open findings can still take
package/lib/config-set.js CHANGED
@@ -97,13 +97,13 @@ export const SETTINGS = [
97
97
  key: 'agent.model',
98
98
  kind: 'word',
99
99
  presets: 'model',
100
- label: "the model an item or a chat thread without its own runs on (empty: the agent's choice)",
100
+ label: 'the model an item or a chat thread without its own runs on (not set: Opus)',
101
101
  },
102
102
  {
103
103
  key: 'agent.effort',
104
104
  kind: 'word',
105
105
  presets: 'effort',
106
- label: "the effort an item or a chat thread without its own runs with (empty: the agent's)",
106
+ label: 'the effort an item or a chat thread without its own runs with (not set: High)',
107
107
  },
108
108
  {
109
109
  key: 'chat.ask',
@@ -38,7 +38,15 @@ const COMPARISON_RE = new RegExp(
38
38
  const ENVELOPE_BLOCKS = ['feel', 'sources', 'sinks'];
39
39
  const OPERATOR_BLOCKS = ['tuning', 'notes'];
40
40
  const FLAGS = ['src-changed', 'orphan', 'impl?'];
41
- const REQUIRED_HEADER = ['type', 'route', 'system', 'milestone', 'pillars', 'depends', 'source'];
41
+ export const REQUIRED_HEADER = [
42
+ 'type',
43
+ 'route',
44
+ 'system',
45
+ 'milestone',
46
+ 'pillars',
47
+ 'depends',
48
+ 'source',
49
+ ];
42
50
  const ws = (t) => String(t).replace(/\s+/g, ' ').trim();
43
51
  const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
44
52
 
@@ -122,6 +130,21 @@ function itemsIn(text, key) {
122
130
  export const recordsIn = (text, key) =>
123
131
  readRecords(itemsIn(text, key)).records.map((r) => r.values);
124
132
 
133
+ /**
134
+ * The milestones of game.md, its closed vocabulary of a unit's and an item's `milestone`: name and
135
+ * goal each; null without game.md, and then nothing is checked against them. A name that is no
136
+ * slug (`TBD`, words) names no milestone: no field can hold it.
137
+ */
138
+ export async function gameMilestones(root) {
139
+ const game = await readIf(path.join(root, 'game.md'));
140
+
141
+ return game === null
142
+ ? null
143
+ : recordsIn(game, 'milestones')
144
+ .filter((m) => SLUG_RE.test(m.name ?? ''))
145
+ .map((m) => ({ name: m.name, goal: m.goal ?? null }));
146
+ }
147
+
125
148
  /** A D1 record nobody answered yet: only such a question holds its units. */
126
149
  const blocksUnits = (rec) => /^D1\b/.test(fieldOf(rec, 'class') ?? '') && !fieldOf(rec, 'answer');
127
150
 
@@ -150,7 +173,7 @@ export function questionBlocks(text) {
150
173
  /** Everything outside a unit that its references resolve against. */
151
174
  async function loadContext(root) {
152
175
  const glossary = await readIf(path.join(root, 'glossary.md'));
153
- const game = await readIf(path.join(root, 'game.md'));
176
+ const milestones = await gameMilestones(root);
154
177
  const pillars = await readIf(path.join(root, 'PILLARS.md'));
155
178
  const forbidden = recordsIn(glossary, 'terms').flatMap((t) => {
156
179
  const not = listOf(t.not ?? '');
@@ -159,7 +182,7 @@ async function loadContext(root) {
159
182
  });
160
183
 
161
184
  return {
162
- milestones: game === null ? null : recordsIn(game, 'milestones').map((m) => m.name),
185
+ milestones: milestones?.map((m) => m.name) ?? null,
163
186
  pillarIds: recordsIn(pillars, 'pillars')
164
187
  .map((p) => p.id)
165
188
  .filter(Boolean),
@@ -446,9 +469,13 @@ function preambleIssues(design) {
446
469
  }));
447
470
  }
448
471
 
449
- /** M2 over a work item's references: depends, parent, children, reopens. */
450
- function itemRefIssues(item, ledger, add) {
472
+ /** M2 over a work item's references: depends, parent, children, reopens, milestone. */
473
+ function itemRefIssues(item, ctx, ledger, add) {
451
474
  const d = item.data;
475
+ // A milestone outside game.md drops the item out of the phase gates that read it. A reading,
476
+ // not a block: an item tagged before game.md listed it holds no commit; `item new` refuses one.
477
+ if (d.milestone && ctx.milestones !== null && !ctx.milestones.includes(d.milestone))
478
+ add('M2', 1, `milestone ${d.milestone} is not a milestone of game.md`, 'report');
452
479
  const unknown = (d.depends ?? []).filter((x) => x === d.id || !ledger.known(x));
453
480
  if (unknown.length) add('M2', 1, `depends on unknown ${unknown.join(', ')}`);
454
481
  // A parent that already ended is fine: a parked bug may outlive its feature.
@@ -474,7 +501,7 @@ async function checkItem(item, ctx, ledger) {
474
501
  const offset = raw.split('\n').length - item.body.split('\n').length;
475
502
  const add = (check, line, message, severity = 'block') =>
476
503
  issues.push({ check, severity, file, line: line + offset, id: item.data.id, message });
477
- itemRefIssues(item, ledger, add);
504
+ itemRefIssues(item, ctx, ledger, add);
478
505
  if (!UNIT_TYPES.includes(item.data.type)) return issues;
479
506
 
480
507
  const { profile, issues: shape } = await bodyProblems(item.body, item.data.type);
@@ -763,11 +790,12 @@ export async function designUnits(projectDir, ledger) {
763
790
 
764
791
  /**
765
792
  * Run every design check over a project. `blocking` counts the issues that refuse a commit;
766
- * the rest of the report (completeness, readiness, pillars) is a reading, not a gate.
793
+ * the rest of the report (completeness, readiness, pillars) is a reading, not a gate. A caller
794
+ * that has built the ledger already (the board read) passes it.
767
795
  */
768
- export async function designCheck(projectDir) {
796
+ export async function designCheck(projectDir, { ledger: built = null } = {}) {
769
797
  const root = path.join(path.resolve(projectDir), 'gcf');
770
- const ledger = await buildLedger(projectDir);
798
+ const ledger = built ?? (await buildLedger(projectDir));
771
799
  const ctx = await loadContext(root);
772
800
  const { issues, units } = await checkUnits(ledger, ctx);
773
801