@veda-hq/niyam 0.6.21 → 0.6.23

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,32 @@
1
+ import { existsSync, realpathSync, rmSync } from 'node:fs';
2
+ import { devNull, tmpdir } from 'node:os';
3
+ import { isAbsolute, relative } from 'node:path';
4
+ /**
5
+ * Removes a test's fixture folder and all in it, once links are followed; refuses any path that is not strictly
6
+ * inside the system's temporary folder, so a cleanup can never reach a real checkout. Nothing there is fine.
7
+ */
8
+ export function removeFixtureRoot(path) {
9
+ if (!existsSync(path))
10
+ return;
11
+ const inside = relative(realpathSync(tmpdir()), realpathSync(path));
12
+ if (inside === '' || inside.startsWith('..') || isAbsolute(inside))
13
+ throw new Error(`refusing to remove ${path}: it is not inside ${tmpdir()}`);
14
+ rmSync(path, { recursive: true, force: true });
15
+ }
16
+ /**
17
+ * git without the caller's repository or configuration, for tests that build git fixtures: under a git hook the
18
+ * environment carries GIT_DIR and GIT_INDEX_FILE, so a child that inherited them would read and write the hook's
19
+ * repository instead of the fixture, and the machine's global config (hooks, trace targets) would reach it.
20
+ */
21
+ const HERMETIC = { GIT_CONFIG_GLOBAL: devNull, GIT_CONFIG_NOSYSTEM: '1', GIT_TERMINAL_PROMPT: '0' };
22
+ /** `env` (the process's own by default) without any GIT_ variable, and with no global or system config. */
23
+ export function hermeticGitEnv(env = process.env) {
24
+ return { ...Object.fromEntries(Object.entries(env).filter(([key]) => !key.startsWith('GIT_'))), ...HERMETIC };
25
+ }
26
+ /** The same for this process itself, whose git children (the code under test) inherit its environment. */
27
+ export function maskProcessGitEnv(env = process.env) {
28
+ for (const key of Object.keys(env))
29
+ if (key.startsWith('GIT_'))
30
+ Reflect.deleteProperty(env, key);
31
+ Object.assign(env, HERMETIC);
32
+ }
package/dist/onboard.js CHANGED
@@ -9,7 +9,7 @@ import { DEFAULT_SCHEDULE, FEATURES, FIGMA_FILE_KEY, NEEDS_ISSUE_TYPES, features
9
9
  import { CLOUD_SETUP_PATH, HOOKS_PATH, LEFTOVER_CLOUD_SETUP_PATH, ONBOARD_BRANCH, SARATHI_PATH, WORKFLOW_PATH, autoMerge, mergeQueue, openPull, remoteFile, } from './onboard-pull.js';
10
10
  import { cloudRepoScript, cloudScriptVersion, releaseSha256 } from './cloud.js';
11
11
  import { tagOnMain } from './release-tag.js';
12
- import { setSecret } from './secrets.js';
12
+ import { secretNames, setSecret } from './secrets.js';
13
13
  import { UPGRADE } from './upgrade.js';
14
14
  import { isNewer, packageVersion } from './version.js';
15
15
  import { GITHUB_WEB } from './host.js';
@@ -442,12 +442,46 @@ function workflowHead(branch, version, comments, schedule = DEFAULT_SCHEDULE, ty
442
442
  const FIGMA_SECRETS = [' secrets:', ' FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}', ' FIGMA_LIBRARY: ${{ secrets.FIGMA_LIBRARY }}'];
443
443
  /** The secrets every job passed before P-23, whether figma was on or not. */
444
444
  const OLDER_SECRETS = [' secrets:', ' FIGMA_TOKEN: ${{ secrets.FIGMA_TOKEN }}'];
445
+ /** The board GitHub App's secrets, which the Slice started job makes its board token from (P-70). */
446
+ export const BOARD_SECRETS = ['NIYAM_BOARD_APP_ID', 'NIYAM_BOARD_APP_KEY'];
447
+ const BOARD_SECRET_LINES = BOARD_SECRETS.map((name) => ` ${name}: \${{ secrets.${name} }}`);
448
+ /** What each board app secret holds. */
449
+ const BOARD_SECRET_HOLDS = { NIYAM_BOARD_APP_ID: 'client id', NIYAM_BOARD_APP_KEY: 'private key' };
445
450
  /**
446
- * A job's `niyam-ref` line and the block of Figma secrets after it, as
447
- * either list writes it, or the line alone when no secrets follow: a block
448
- * with secrets of the client's own is left as it is.
451
+ * The owner's steps, once per organization, to give `slug`'s Slice started
452
+ * job the board app's token: make the app, install it, and set the secrets
453
+ * `missing`. `unknown` when GitHub would not list the secrets, so they may be
454
+ * set already.
449
455
  */
450
- const SECRETS_AFTER_REF = /^( {6}niyam-ref:[^\n]*\n)(?: {4}secrets:\n(?: {6}FIGMA_(?:TOKEN|LIBRARY): \$\{\{ secrets\.FIGMA_(?:TOKEN|LIBRARY) \}\}\n)+(?! {6})|(?! {4}secrets:))/gm;
456
+ export function boardAppSteps(slug, missing, unknown = false) {
457
+ const org = slug.split('/')[0];
458
+ const set = missing.map((name) => `its ${BOARD_SECRET_HOLDS[name]} as ${name}`).join(' and ');
459
+ return (`${unknown ? `Unless ${slug} has the Actions secrets ${BOARD_SECRETS.join(' and ')} already, once` : 'Once'} for ${org}: ` +
460
+ `make a GitHub App with organization Projects read and write and repository Issues read at ${GITHUB_WEB}/organizations/${org}/settings/apps/new, ` +
461
+ `install it on ${slug}, and set ${set}, Actions secrets of the organization or of ${GITHUB_WEB}/${slug}/settings/secrets/actions. ` +
462
+ 'Until then a slice moves to In Progress on the board only from a desktop push.');
463
+ }
464
+ /**
465
+ * The secrets block job `id` passes the shared checks: the Figma secrets on
466
+ * every job, and the board app's on the pull request job alone, since only
467
+ * its Slice started job uses them.
468
+ */
469
+ function secretsOf(id, { figma, board }) {
470
+ const lines = [...(figma ? FIGMA_SECRETS.slice(1) : []), ...(board && id === CLI ? BOARD_SECRET_LINES : [])];
471
+ return lines.length > 0 ? [' secrets:', ...lines] : [];
472
+ }
473
+ /** A secret onboard writes, by name, as a line of a job's block. */
474
+ const OWN_SECRET = String.raw `(?:FIGMA_(?:TOKEN|LIBRARY)|NIYAM_BOARD_APP_(?:ID|KEY))`;
475
+ /**
476
+ * A job's `niyam-ref` line and the block of onboard's secrets after it, as
477
+ * any release writes it, or the line alone when no secrets follow: a block
478
+ * with secrets of the client's own, or `secrets: inherit`, is left as it is.
479
+ */
480
+ const SECRETS_AFTER_REF = new RegExp(String.raw `^( {6}niyam-ref:[^\n]*\n)(?: {4}secrets:\n(?: {6}${OWN_SECRET}: \$\{\{ secrets\.${OWN_SECRET} \}\}\n)+(?! {6})|(?! {4}secrets:))`, 'gm');
481
+ /** The id of the job whose lines run through `offset` in workflow `text`: the last two-space key before it. */
482
+ function jobAt(text, offset) {
483
+ return [...text.slice(0, offset).matchAll(/^ {2}([\w-]+):[ \t]*$/gm)].at(-1)?.[1];
484
+ }
451
485
  /**
452
486
  * The jobs of a workflow that call the shared checks without passing them
453
487
  * FIGMA_LIBRARY, by name: each job's own block is read, so one job missing it
@@ -471,10 +505,11 @@ function callChecks(version, secrets) {
471
505
  * to the default branch and weekly, at the niyam release `version`.
472
506
  * Pull request and push runs are read-only; the weekly job alone writes to
473
507
  * issues. Upgrading is changing that version, which each job names twice.
474
- * The Figma secrets are passed only when the figma feature is on; the
508
+ * The Figma secrets are passed only when the figma feature is on, and the
509
+ * board app's, by the pull request job alone, only when `board` is; the
475
510
  * weekly job runs on the settings' `schedule`.
476
511
  */
477
- export function workflow(branch, version, figma, schedule = DEFAULT_SCHEDULE, settings = SETTINGS_PATH) {
512
+ export function workflow(branch, version, figma, schedule = DEFAULT_SCHEDULE, settings = SETTINGS_PATH, board = false) {
478
513
  const secrets = figma ? FIGMA_SECRETS : [];
479
514
  return [
480
515
  ...workflowHead(branch, version, [
@@ -485,7 +520,7 @@ export function workflow(branch, version, figma, schedule = DEFAULT_SCHEDULE, se
485
520
  ` ${CLI}:`,
486
521
  jobName(CLI),
487
522
  READ_ONLY_IF,
488
- ...callChecks(version, secrets),
523
+ ...callChecks(version, secretsOf(CLI, { figma, board })),
489
524
  '',
490
525
  ' # The weekly run alone writes to issues: it comments and opens undo issues.',
491
526
  ` ${CLI}-weekly:`,
@@ -537,17 +572,23 @@ function flowScalar(value, quote) {
537
572
  * already split into a read-only `niyam` job and a `niyam-weekly` job, move
538
573
  * the version pins, the one branch pushes run on when the default branch has
539
574
  * changed, the one cron the weekly job runs on when the settings' schedule
540
- * has changed, and each job's Figma secrets to what the figma feature needs,
575
+ * has changed, and each job's Figma secrets to what the figma feature needs
576
+ * and the pull request job's board app secrets to what `board` needs,
541
577
  * leaving the rest as the client has it; any other workflow is replaced.
542
578
  */
543
- export function workflowUpdate(before, branch, version, figma, schedule = DEFAULT_SCHEDULE, settings = SETTINGS_PATH) {
579
+ export function workflowUpdate(before, branch, version, figma, schedule = DEFAULT_SCHEDULE, settings = SETTINGS_PATH, board = false) {
544
580
  if (before === undefined)
545
- return { kind: 'write', text: workflow(branch, version, figma, schedule, settings) };
546
- return repinned(before, branch, version, figma, schedule, settings);
581
+ return { kind: 'write', text: workflow(branch, version, figma, schedule, settings, board) };
582
+ return repinned(before, branch, version, figma, schedule, settings, board);
583
+ }
584
+ /** The secrets of onboard's own a block of a job names, by what they are for. */
585
+ function ownSecrets(block) {
586
+ const names = [...block.matchAll(/^ {6}([\w-]+):/gm)].map((match) => match[1]);
587
+ return { figma: names.filter((name) => name.startsWith('FIGMA_')).join(','), board: names.filter((name) => name.startsWith('NIYAM_BOARD_')).join(',') };
547
588
  }
548
589
  /** workflowUpdate on a workflow that is there. */
549
- function repinned(before, branch, version, figma, schedule, settings) {
550
- const wanted = workflow(branch, version, figma, schedule, settings);
590
+ function repinned(before, branch, version, figma, schedule, settings, board) {
591
+ const wanted = workflow(branch, version, figma, schedule, settings, board);
551
592
  if (before === wanted)
552
593
  return { kind: 'same' };
553
594
  const pins = workflowPins(before);
@@ -558,13 +599,13 @@ function repinned(before, branch, version, figma, schedule, settings) {
558
599
  const merged = job(`${CLI}-merged`);
559
600
  const added = split && !merged && pins.length === 4 && from !== undefined ? addMergedJob(before, from, figma) : undefined;
560
601
  if (added !== undefined) {
561
- const update = repinned(added, branch, version, figma, schedule, settings);
602
+ const update = repinned(added, branch, version, figma, schedule, settings, board);
562
603
  return { ...(update.kind === 'repin' ? update : { text: added }), kind: 'repin', merged: true };
563
604
  }
564
605
  const asks = job(`${CLI}-asks`);
565
606
  const withAsks = split && merged && !asks && pins.length === 6 && from !== undefined ? addAsksJob(before, from, figma) : undefined;
566
607
  if (withAsks !== undefined) {
567
- const update = repinned(withAsks, branch, version, figma, schedule, settings);
608
+ const update = repinned(withAsks, branch, version, figma, schedule, settings, board);
568
609
  // The asks job it adds also types each new issue, so the plan says so.
569
610
  return { ...(update.kind === 'repin' ? update : { text: withAsks }), kind: 'repin', asks: true, types: true };
570
611
  }
@@ -590,12 +631,31 @@ function repinned(before, branch, version, figma, schedule, settings) {
590
631
  .replace(HEADER_PIN, (_, _head, _old, dot) => `# Written by ${CLI} onboard: the shared ${CLI} checks at v${version}${dot}`)
591
632
  .replace(PUSH_BRANCH, (line, head, quote, _old, tail) => moved ? `${head}${flowScalar(branch, quote)}${tail}` : line)
592
633
  .replace(SCHEDULE, (line, comment, head, quote, _old, tail) => rescheduled ? `${comment === undefined ? '' : `${scheduleComment(schedule, settings)}\n`}${head}${quote || "'"}${schedule}${quote || "'"}${tail}` : line);
593
- const secrets = figma ? `${FIGMA_SECRETS.join('\n')}\n` : '';
594
- const text = pinned.replace(SECRETS_AFTER_REF, (_, ref) => `${ref}${secrets}`);
634
+ // Each job's block as that job passes it; which part changed, Figma's or the board app's, is said apart.
635
+ const changed = { figma: false, board: false };
636
+ const text = pinned.replace(SECRETS_AFTER_REF, (block, ref, offset, whole) => {
637
+ const lines = secretsOf(jobAt(whole, offset) ?? '', { figma, board });
638
+ const now = `${ref}${lines.map((line) => `${line}\n`).join('')}`;
639
+ const had = ownSecrets(block);
640
+ const has = ownSecrets(now);
641
+ changed.figma ||= had.figma !== has.figma;
642
+ changed.board ||= had.board !== has.board;
643
+ return now;
644
+ });
595
645
  if (text === before)
596
646
  return { kind: 'same' };
597
647
  const stale = pins.find((pin) => pin !== version);
598
- return { kind: 'repin', text, ...(stale ? { from: stale } : {}), ...(moved ? { branch } : {}), ...(rescheduled ? { schedule } : {}), ...(text !== pinned ? { secrets: true } : {}), ...(authors ? { authors: true } : {}), ...(types ? { types: true } : {}) };
648
+ return {
649
+ kind: 'repin',
650
+ text,
651
+ ...(stale ? { from: stale } : {}),
652
+ ...(moved ? { branch } : {}),
653
+ ...(rescheduled ? { schedule } : {}),
654
+ ...(changed.figma ? { secrets: true } : {}),
655
+ ...(changed.board ? { board: true } : {}),
656
+ ...(authors ? { authors: true } : {}),
657
+ ...(types ? { types: true } : {}),
658
+ };
599
659
  }
600
660
  return { kind: 'replace', text: wanted };
601
661
  }
@@ -992,7 +1052,7 @@ export function onboardArgs(args) {
992
1052
  return { named, ...(features ? { features } : {}), ...(add ? { add } : {}), ...(yes ? { yes: true } : {}), ...(dryRun ? { dryRun: true } : {}) };
993
1053
  }
994
1054
  /** What a workflow update changes, in a few words for the plan. */
995
- function workflowDetail(update, version, figma) {
1055
+ function workflowDetail(update, version, { figma, board }) {
996
1056
  if (update.kind !== 'repin')
997
1057
  return { write: 'new', replace: 'replaced' }[update.kind];
998
1058
  return ([
@@ -1000,6 +1060,7 @@ function workflowDetail(update, version, figma) {
1000
1060
  ...(update.branch ? [`branch → ${update.branch}`] : []),
1001
1061
  ...(update.schedule ? [`schedule → ${update.schedule}`] : []),
1002
1062
  ...(update.secrets ? [figma ? 'Figma secrets' : 'no Figma secrets'] : []),
1063
+ ...(update.board ? [board ? 'board app secrets' : 'no board app secrets'] : []),
1003
1064
  ...(update.merged ? ['merged job'] : []),
1004
1065
  ...(update.asks ? ['needs-owner job'] : []),
1005
1066
  ...(update.authors ? ['needs-owner job only for owners, members and collaborators'] : []),
@@ -1007,7 +1068,7 @@ function workflowDetail(update, version, figma) {
1007
1068
  ].join(', ') || `header → v${version}`);
1008
1069
  }
1009
1070
  /** What a workflow update changes, in full for the pull request's description. */
1010
- function workflowWhat(update, version, figma, schedulePath, file = WORKFLOW_PATH) {
1071
+ function workflowWhat(update, version, { figma, board }, schedulePath, file = WORKFLOW_PATH) {
1011
1072
  if (update.kind !== 'repin') {
1012
1073
  return {
1013
1074
  write: `write ${WORKFLOW_PATH}, which runs the shared niyam checks`,
@@ -1019,6 +1080,9 @@ function workflowWhat(update, version, figma, schedulePath, file = WORKFLOW_PATH
1019
1080
  ...(update.branch ? [`run pushes on the default branch, ${update.branch}`] : []),
1020
1081
  ...(update.schedule ? [`run the weekly decisions job on the schedule ${schedulePath} sets, cron ${update.schedule} UTC`] : []),
1021
1082
  ...(update.secrets ? [figma ? 'pass the FIGMA_TOKEN and FIGMA_LIBRARY secrets' : 'stop passing Figma secrets, with figma off'] : []),
1083
+ ...(update.board
1084
+ ? [board ? `pass the pull request job's checks the board app's ${BOARD_SECRETS.join(' and ')} secrets, which move a slice to In Progress when its pull request opens` : 'stop passing the board app secrets, with board off']
1085
+ : []),
1022
1086
  ...(update.merged ? ['add a job that closes the slice a merged pull request names, the one pull request run that writes to issues'] : []),
1023
1087
  ...(update.asks ? ["add a job that labels an issue needs-owner where the agent asks the owner, and takes it off at the owner's approved label, Decision: comment or (hourly) 👍"] : []),
1024
1088
  ...(update.authors ? ['start the needs-owner job only on a comment by the owner, a member or a collaborator'] : []),
@@ -1369,14 +1433,26 @@ export async function onboard(sys, io, args = []) {
1369
1433
  }
1370
1434
  // The shared checks run only for features that need them.
1371
1435
  const workflowFrom = workflowPins(fileAt(WORKFLOW_PATH) ?? '')[0];
1436
+ const passed = { figma: on('figma'), board: on('board') };
1372
1437
  const workflowFor = (branch) => {
1373
- const update = workflowUpdate(fileAt(WORKFLOW_PATH), branch, version, on('figma'), schedule);
1438
+ const update = workflowUpdate(fileAt(WORKFLOW_PATH), branch, version, passed.figma, schedule, SETTINGS_PATH, passed.board);
1374
1439
  if (update.kind !== 'same')
1375
- change(WORKFLOW_PATH, update.text, workflowWhat(update, version, on('figma'), SETTINGS_PATH));
1440
+ change(WORKFLOW_PATH, update.text, workflowWhat(update, version, passed, SETTINGS_PATH));
1376
1441
  };
1442
+ // The Slice started job's board token comes from the board app's secrets, which only the owner can make (P-70).
1443
+ // A personal repository's checks skip the work rules, so it needs none.
1444
+ if (workflowNeeded && passed.board && (await byOrganisation())) {
1445
+ const names = await secretNames(sys, slug, token);
1446
+ const missing = BOARD_SECRETS.filter((name) => !names?.includes(name));
1447
+ if (missing.length > 0) {
1448
+ const steps = boardAppSteps(slug, missing, names === undefined);
1449
+ byHand.push(steps);
1450
+ later.push(steps);
1451
+ }
1452
+ }
1377
1453
  if (workflowNeeded) {
1378
- const update = planned === undefined ? undefined : workflowUpdate(fileAt(WORKFLOW_PATH), planned, version, on('figma'), schedule);
1379
- const detail = update === undefined ? (fileAt(WORKFLOW_PATH) === undefined ? 'new' : 'write or update') : update.kind === 'same' ? undefined : workflowDetail(update, version, on('figma'));
1454
+ const update = planned === undefined ? undefined : workflowUpdate(fileAt(WORKFLOW_PATH), planned, version, passed.figma, schedule, SETTINGS_PATH, passed.board);
1455
+ const detail = update === undefined ? (fileAt(WORKFLOW_PATH) === undefined ? 'new' : 'write or update') : update.kind === 'same' ? undefined : workflowDetail(update, version, passed);
1380
1456
  if (detail !== undefined)
1381
1457
  pull.push({ label: 'workflow', detail });
1382
1458
  }
@@ -0,0 +1,321 @@
1
+ import { posix } from 'node:path';
2
+ import { SETTINGS_PATH, repoAt } from './agent.js';
3
+ import { basenamesOnRef, gitOut, kindNamed, loadDocSettings, localBasenames } from './doc-numbers.js';
4
+ /**
5
+ * Moves a numbered document to another number, taking every reference with it: the file (`git mv`, or a plain
6
+ * rename when git does not track it yet), its own frontmatter key, every citation (`ADR-0057`) and full or relative
7
+ * path in tracked files, and the bare relationship values (`supersedes: '0040'`) the settings name. The rename was
8
+ * never the expensive part of a clash; finding every reference is, so this does it. A dry run by default: some prose
9
+ * narrates history, and only a person can tell, so `--apply` writes.
10
+ */
11
+ const FOUR_DIGITS = /^\d{4}$/;
12
+ const literal = (text) => text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
13
+ const citationOf = (kind, number) => `${kind.citation}-${number}`;
14
+ /** Tracked files that contain `needle`, by path; under `dir` when given. */
15
+ export function filesContaining(sys, root, needle, dir) {
16
+ const out = gitOut(sys, root, ['grep', '-l', '-F', '--', needle, ...(dir === undefined ? [] : [dir])]);
17
+ return out === null ? [] : out.split('\n').filter(Boolean);
18
+ }
19
+ /** Whether a renumber leaves `path` as written: it records what a document was called then. */
20
+ export function isHistory(settings, path) {
21
+ const matches = (pattern) => (pattern.endsWith('/') ? path.startsWith(pattern) : path === pattern);
22
+ if (settings.history.some((pattern) => pattern.startsWith('!') && matches(pattern.slice(1))))
23
+ return false;
24
+ return settings.history.some((pattern) => !pattern.startsWith('!') && matches(pattern));
25
+ }
26
+ /** The relationship keys `path` carries for `kind`, or none. */
27
+ export function relationshipKeysFor(kind, path) {
28
+ for (const [dir, keys] of Object.entries(kind.relationships))
29
+ if (path.startsWith(`${dir}/`))
30
+ return keys;
31
+ return [];
32
+ }
33
+ /**
34
+ * Citations of `from` become `to`, and paths to the old file name the new one. A citation needs a non-digit after
35
+ * it, so `ADR-0057` never matches in `ADR-00571`. A relative path (`../rfcs/…`, `../../rfcs/…`) is rewritten only
36
+ * when, resolved against the file that holds it (`path`), it lands on this very document.
37
+ */
38
+ export function rewriteReferences(text, kind, from, to, oldName, newName, path) {
39
+ const citation = new RegExp(`${citationOf(kind, literal(from))}(?!\\d)`, 'g');
40
+ const sibling = kind.dir.slice(kind.dir.lastIndexOf('/') + 1);
41
+ const relative = new RegExp(`(?<![\\w./-])((?:\\.\\./)+${literal(sibling)}/)${literal(oldName)}`, 'g');
42
+ const fromDir = posix.dirname(path);
43
+ return text
44
+ .replaceAll(`${kind.dir}/${oldName}`, `${kind.dir}/${newName}`)
45
+ .replace(relative, (match, prefix) => (posix.normalize(posix.join(fromDir, `${prefix}${oldName}`)) === `${kind.dir}/${oldName}` ? `${prefix}${newName}` : match))
46
+ .replace(citation, citationOf(kind, to));
47
+ }
48
+ /**
49
+ * Bare numbers under the relationship keys `path` carries for `kind`: a scalar (`key: '0040'`, `key: 0040`,
50
+ * `key: '0040 (a note)'`), a flow list (`key: ["0022", 0023]`), a block list (`- '0022 (…)'`) and a flow list
51
+ * wrapped over lines, with `# comments`, blank lines in a block and CRLF. A value that is only numbers and commas
52
+ * names each of them; any other value names one document, its leading number, and the rest is description. Keys the
53
+ * kind does not own are left alone: a bare number there could name either kind.
54
+ */
55
+ export function rewriteRelationships(text, kind, from, to, path) {
56
+ const keys = new Set(relationshipKeysFor(kind, path));
57
+ if (keys.size === 0)
58
+ return text;
59
+ const swap = (value) => (value === from ? to : value);
60
+ const LIST = /^\s*\d{4}(\s*,\s*\d{4})*\s*$/;
61
+ const swapInner = (inner) => (LIST.test(inner) ? inner.replace(/\d{4}/g, swap) : inner.replace(/^(\s*)(\d{4})(?!\d)/, (_whole, lead, number) => `${lead}${swap(number)}`));
62
+ const swapElement = (element) => {
63
+ const quoted = /^(\s*)(['"])([\s\S]*)\2(\s*)$/.exec(element);
64
+ if (quoted === null)
65
+ return swapInner(element);
66
+ const [, pre, quote, inner, post] = quoted;
67
+ return `${pre}${quote}${swapInner(inner)}${quote}${post}`;
68
+ };
69
+ // Top-level commas only; a backslash escapes only inside double quotes, as in YAML.
70
+ const splitElements = (segment) => {
71
+ const parts = [];
72
+ let current = '';
73
+ let quote = null;
74
+ let escaped = false;
75
+ for (const ch of segment) {
76
+ if (escaped)
77
+ escaped = false;
78
+ else if (quote === '"' && ch === '\\')
79
+ escaped = true;
80
+ else if (quote !== null) {
81
+ if (ch === quote)
82
+ quote = null;
83
+ }
84
+ else if (ch === "'" || ch === '"')
85
+ quote = ch;
86
+ else if (ch === ',') {
87
+ parts.push(current);
88
+ current = '';
89
+ continue;
90
+ }
91
+ current += ch;
92
+ }
93
+ parts.push(current);
94
+ return parts;
95
+ };
96
+ const swapElements = (segment) => splitElements(segment).map(swapElement).join(',');
97
+ // A comment starts at a # outside quotes that opens the segment or follows whitespace.
98
+ const splitComment = (segment) => {
99
+ let quote = null;
100
+ let escaped = false;
101
+ for (const [i, ch] of [...segment].entries()) {
102
+ if (escaped)
103
+ escaped = false;
104
+ else if (quote === '"' && ch === '\\')
105
+ escaped = true;
106
+ else if (quote !== null) {
107
+ if (ch === quote)
108
+ quote = null;
109
+ }
110
+ else if (ch === "'" || ch === '"')
111
+ quote = ch;
112
+ else if (ch === '#' && (i === 0 || /\s/.test(segment[i - 1])))
113
+ return [segment.slice(0, i), segment.slice(i)];
114
+ }
115
+ return [segment, ''];
116
+ };
117
+ const swapFlowLine = (body) => {
118
+ const [, open, inner, close] = /^(\s*\[?)([\s\S]*?)(\]?\s*)$/.exec(body);
119
+ return `${open}${swapElements(inner)}${close}`;
120
+ };
121
+ const lines = text.split('\n');
122
+ let mode = null;
123
+ for (let i = 0; i < lines.length; i += 1) {
124
+ const whole = lines[i];
125
+ const eol = whole.endsWith('\r') ? '\r' : '';
126
+ const [body, comment] = splitComment(eol === '' ? whole : whole.slice(0, -1));
127
+ if (mode === 'flow') {
128
+ lines[i] = `${swapFlowLine(body)}${comment}${eol}`;
129
+ if (/\]\s*$/.test(body))
130
+ mode = null;
131
+ continue;
132
+ }
133
+ if (mode === 'block') {
134
+ const item = /^(\s+-\s*)(.*)$/.exec(body);
135
+ if (item !== null) {
136
+ if (/^['"]?\d{4}/.test(item[2]))
137
+ lines[i] = `${item[1]}${swapElements(item[2])}${comment}${eol}`;
138
+ continue;
139
+ }
140
+ if (/^\s*$/.test(body))
141
+ continue;
142
+ if (/^\s+\[/.test(body)) {
143
+ lines[i] = `${swapFlowLine(body)}${comment}${eol}`;
144
+ mode = /\]\s*$/.test(body) ? null : 'flow';
145
+ continue;
146
+ }
147
+ mode = null;
148
+ }
149
+ const entry = /^\s*([A-Za-z_][A-Za-z0-9_]*):(.*)$/.exec(body);
150
+ if (entry === null || !keys.has(entry[1]))
151
+ continue;
152
+ const key = entry[1];
153
+ const rest = entry[2];
154
+ const head = body.slice(0, body.indexOf(`${key}:`) + key.length + 1);
155
+ if (/^\s*$/.test(rest)) {
156
+ mode = 'block';
157
+ continue;
158
+ }
159
+ if (/^\s*\[/.test(rest)) {
160
+ lines[i] = `${head}${swapFlowLine(rest)}${comment}${eol}`;
161
+ if (!/\]\s*$/.test(rest))
162
+ mode = 'flow';
163
+ continue;
164
+ }
165
+ if (/^\s*['"]?\d{4}/.test(rest))
166
+ lines[i] = `${head}${swapElements(rest)}${comment}${eol}`;
167
+ }
168
+ return lines.join('\n');
169
+ }
170
+ /** Every rewrite that applies to `path`. */
171
+ export function rewriteAll(text, kind, from, to, oldName, newName, path) {
172
+ return rewriteRelationships(rewriteReferences(text, kind, from, to, oldName, newName, path), kind, from, to, path);
173
+ }
174
+ /**
175
+ * Frontmatter lines that still name `from` bare after the rewrite, under keys no kind owns for `path` (`related:`):
176
+ * a bare number there could name either kind, so a person decides, and the command says so rather than exit 0 in
177
+ * silence. A block list's items count under their key.
178
+ */
179
+ export function residualBareRefs(settings, text, from, path) {
180
+ // The frontmatter's lines: after a first line of ---, up to the next line that starts with ---. Read line by line
181
+ // on purpose, not parsed: a malformed block must still be read.
182
+ const all = text.split('\n').map((line) => line.replace(/\r$/, ''));
183
+ const end = all.findIndex((line, i) => i > 0 && line.startsWith('---'));
184
+ if (all[0] !== '---' || end < 0)
185
+ return [];
186
+ const bare = new RegExp(`(?<![A-Za-z0-9-])${literal(from)}(?!\\d)`);
187
+ const classified = new Set(Object.values(settings.kinds).flatMap((kind) => [kind.frontmatterKey, ...relationshipKeysFor(kind, path)]));
188
+ const flagged = [];
189
+ let enclosing = null;
190
+ for (const line of all.slice(1, end)) {
191
+ const entry = /^\s*([A-Za-z_][A-Za-z0-9_]*):/.exec(line);
192
+ if (entry !== null)
193
+ enclosing = entry[1];
194
+ else if (!/^\s*-\s/.test(line) && line.trim() !== '')
195
+ enclosing = null;
196
+ if (!bare.test(line) || (enclosing !== null && classified.has(enclosing)))
197
+ continue;
198
+ flagged.push(line.trim());
199
+ }
200
+ return flagged;
201
+ }
202
+ /** The document's own frontmatter key (`adr: '0057'`) moved to `to`. */
203
+ export function rewriteFrontmatter(text, kind, from, to) {
204
+ return text.replace(new RegExp(`^(${kind.frontmatterKey}:\\s*['"]?)${literal(from)}(['"]?\\s*)$`, 'm'), `$1${to}$2`);
205
+ }
206
+ /** What a renumber would change, or why it cannot: the target must be free here and on origin/main. */
207
+ export function plan(sys, root, settings, kind, from, to) {
208
+ const local = localBasenames(sys, kind, root);
209
+ const sources = local.filter((name) => name.startsWith(`${from}-`));
210
+ if (sources.length === 0)
211
+ return { ok: false, error: `no ${kind.citation} numbered ${from} in ${kind.dir}/` };
212
+ if (sources.length > 1)
213
+ return { ok: false, error: `${String(sources.length)} files claim ${from} (${sources.join(', ')}) — resolve that collision first, one file at a time` };
214
+ const here = local.filter((name) => name.startsWith(`${to}-`));
215
+ if (here.length > 0)
216
+ return { ok: false, error: `${to} is already used locally by ${here.join(', ')}` };
217
+ const onMain = basenamesOnRef(sys, kind, 'origin/main', root);
218
+ if (onMain === null)
219
+ return { ok: false, error: 'could not read `origin/main` — run `git fetch origin main` first, or the new number may collide exactly as the old one did' };
220
+ const there = onMain.filter((name) => name.startsWith(`${to}-`));
221
+ if (there.length > 0)
222
+ return { ok: false, error: `${to} is already used on origin/main by ${there.join(', ')}` };
223
+ const oldName = sources[0];
224
+ const newName = `${to}-${oldName.slice(from.length + 1)}`;
225
+ const oldPath = `${kind.dir}/${oldName}`;
226
+ const newPath = `${kind.dir}/${newName}`;
227
+ const tracked = gitOut(sys, root, ['ls-files', '--error-unmatch', '--', oldPath]) !== null;
228
+ const candidates = new Set([...filesContaining(sys, root, citationOf(kind, from)), ...filesContaining(sys, root, oldPath)]);
229
+ for (const dir of Object.keys(kind.relationships))
230
+ for (const path of filesContaining(sys, root, from, dir))
231
+ candidates.add(path);
232
+ candidates.delete(oldPath);
233
+ // A file kept only if the rewrite changes it: `git grep -F ADR-0057` also finds ADR-00571.
234
+ const referencing = [];
235
+ const residual = [];
236
+ const docDirs = Object.keys(kind.relationships);
237
+ for (const path of [...candidates].sort()) {
238
+ if (isHistory(settings, path))
239
+ continue;
240
+ const before = sys.read(`${root}/${path}`);
241
+ const after = rewriteAll(before, kind, from, to, oldName, newName, path);
242
+ if (after !== before)
243
+ referencing.push(path);
244
+ if (docDirs.some((dir) => path.startsWith(`${dir}/`)))
245
+ for (const line of residualBareRefs(settings, after, from, path))
246
+ residual.push({ path, line });
247
+ }
248
+ return { ok: true, plan: { from, to, oldPath, newPath, oldName, newName, tracked, referencing, residual } };
249
+ }
250
+ /** Writes the plan: the move, then every rewrite; returns the files written. */
251
+ export function applyPlan(sys, root, kind, p) {
252
+ if (p.tracked) {
253
+ const moved = sys.exec('git', ['mv', p.oldPath, p.newPath], { cwd: root });
254
+ if (moved.code !== 0)
255
+ throw new Error(`git mv ${p.oldPath} ${p.newPath}: ${moved.stderr.trim()}`);
256
+ }
257
+ else {
258
+ sys.confine(root, `${root}/${p.newPath}`);
259
+ sys.write(`${root}/${p.newPath}`, sys.read(`${root}/${p.oldPath}`));
260
+ sys.remove(`${root}/${p.oldPath}`);
261
+ }
262
+ const movedAt = `${root}/${p.newPath}`;
263
+ sys.confine(root, movedAt);
264
+ sys.write(movedAt, rewriteAll(rewriteFrontmatter(sys.read(movedAt), kind, p.from, p.to), kind, p.from, p.to, p.oldName, p.newName, p.newPath));
265
+ const changed = [p.newPath];
266
+ for (const path of p.referencing) {
267
+ const at = `${root}/${path}`;
268
+ const before = sys.read(at);
269
+ const after = rewriteAll(before, kind, p.from, p.to, p.oldName, p.newName, path);
270
+ if (after === before)
271
+ continue;
272
+ sys.confine(root, at);
273
+ sys.write(at, after);
274
+ changed.push(path);
275
+ }
276
+ return changed;
277
+ }
278
+ /** renumber-doc's arguments: a kind, two four-digit numbers, and --apply. */
279
+ export function renumberArgs(args) {
280
+ const rest = args.filter((arg) => arg !== '--apply');
281
+ const odd = rest.find((arg) => arg.startsWith('-'));
282
+ if (odd !== undefined)
283
+ throw new Error(`renumber-doc: unknown option "${odd}"`);
284
+ const [kind, from, to, extra] = rest;
285
+ if (kind === undefined || from === undefined || to === undefined || extra !== undefined || !FOUR_DIGITS.test(from) || !FOUR_DIGITS.test(to))
286
+ throw new Error('renumber-doc needs a document kind and two four-digit numbers: renumber-doc <kind> <from> <to> [--apply]');
287
+ if (from === to)
288
+ throw new Error(`renumber-doc: ${from} and ${to} are the same number`);
289
+ return { kind, from, to, apply: args.includes('--apply') };
290
+ }
291
+ /** `niyam renumber-doc <kind> <from> <to> [--apply]`: shows the plan, and with --apply writes it. */
292
+ export function renumberDoc(sys, io, args) {
293
+ const parsed = renumberArgs(args);
294
+ const { root } = repoAt(sys);
295
+ const settings = loadDocSettings(sys, root);
296
+ const kind = kindNamed(settings, parsed.kind);
297
+ if (kind === undefined) {
298
+ io.err(`niyam renumber-doc: no document kind "${parsed.kind}"; ${SETTINGS_PATH} names ${Object.keys(settings.kinds).join(', ')}`);
299
+ return 2;
300
+ }
301
+ const result = plan(sys, root, settings, kind, parsed.from, parsed.to);
302
+ if (!result.ok) {
303
+ io.err(`❌ ${result.error}`);
304
+ return 1;
305
+ }
306
+ const p = result.plan;
307
+ io.out(`${p.oldPath}\n → ${p.newPath}\n`);
308
+ if (p.referencing.length === 0)
309
+ io.out('No other tracked file references it.');
310
+ else
311
+ io.out([`${String(p.referencing.length)} referencing file(s):`, ...p.referencing.map((path) => ` - ${path}`)].join('\n'));
312
+ if (p.residual.length > 0)
313
+ io.out([`\n⚠️ ${String(p.residual.length)} bare reference(s) to ${p.from} under keys this tool does not rewrite (ambiguous namespace) — review by hand:`, ...p.residual.map(({ path, line }) => ` - ${path}: ${line}`)].join('\n'));
314
+ if (!parsed.apply) {
315
+ io.out('\nDry run — nothing changed. Review the list above (some prose narrates history rather than citing a live decision), then re-run with --apply.');
316
+ return 0;
317
+ }
318
+ const changed = applyPlan(sys, root, kind, p);
319
+ io.out(`\n✅ Renumbered ${p.from} → ${p.to}; ${String(changed.length)} file(s) written.\n Review with \`git diff\` and \`git status\`, then commit.`);
320
+ return 0;
321
+ }