@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.
- package/README.md +136 -12
- package/dist/agent.js +33 -12
- package/dist/board-audit.js +177 -0
- package/dist/board.js +30 -4
- package/dist/cloud-key.js +193 -0
- package/dist/cloud.js +122 -4
- package/dist/doc-numbers.js +508 -0
- package/dist/doctor.js +77 -16
- package/dist/hermetic-git.js +32 -0
- package/dist/onboard.js +101 -25
- package/dist/renumber-doc.js +321 -0
- package/dist/run.js +45 -4
- package/dist/secrets.js +21 -0
- package/dist/session-start.js +31 -4
- package/dist/work-item-number.js +262 -0
- package/dist/work.js +78 -4
- package/package.json +2 -2
|
@@ -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
|
-
*
|
|
447
|
-
*
|
|
448
|
-
*
|
|
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
|
-
|
|
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
|
|
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,
|
|
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
|
-
|
|
594
|
-
const
|
|
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 {
|
|
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,
|
|
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,
|
|
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,
|
|
1379
|
-
const detail = update === undefined ? (fileAt(WORKFLOW_PATH) === undefined ? 'new' : 'write or update') : update.kind === 'same' ? undefined : workflowDetail(update, version,
|
|
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
|
+
}
|