yadflow 4.9.0 → 4.11.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +184 -0
- package/README.md +15 -5
- package/bin/commands.mjs +11 -1
- package/bin/yad.mjs +203 -14
- package/cli/agent-guard-worker.mjs +13 -0
- package/cli/agent-guard.mjs +1797 -73
- package/cli/agent-rules.mjs +64 -5
- package/cli/argv-flags.mjs +2 -2
- package/cli/brain/vendor/LICENSE-graphology-library.txt +21 -0
- package/cli/brain/vendor/LICENSE-graphology.txt +21 -0
- package/cli/brain/vendor/LICENSE-sigma.txt +12 -0
- package/cli/brain/vendor/graphology-library.min.js +2 -0
- package/cli/brain/vendor/graphology.umd.min.js +2 -0
- package/cli/brain/vendor/sigma.min.js +1369 -0
- package/cli/brain/view/app.js +382 -0
- package/cli/brain/view/index.html +63 -0
- package/cli/brain/view/live.css +228 -0
- package/cli/brain/view/live.html +110 -0
- package/cli/brain/view/live.js +884 -0
- package/cli/brain/view/style.css +141 -0
- package/cli/brain-about.mjs +206 -0
- package/cli/brain-activity.mjs +285 -0
- package/cli/brain-skills.mjs +118 -0
- package/cli/brain-vendor.mjs +71 -0
- package/cli/brain-view.mjs +344 -0
- package/cli/brain.mjs +810 -0
- package/cli/ci-check.mjs +48 -4
- package/cli/codeowners-command.mjs +72 -6
- package/cli/commit.mjs +17 -3
- package/cli/docs.mjs +2 -0
- package/cli/doctor.mjs +151 -25
- package/cli/epic-state.mjs +186 -4
- package/cli/epic.mjs +26 -10
- package/cli/errors.mjs +2 -1
- package/cli/find-product.mjs +69 -15
- package/cli/fold.mjs +31 -6
- package/cli/foundation-publish.mjs +256 -0
- package/cli/gate.mjs +29 -3
- package/cli/git-read.mjs +38 -0
- package/cli/guard-stream.mjs +409 -0
- package/cli/guide.mjs +3 -1
- package/cli/hook.mjs +102 -9
- package/cli/issue-links.mjs +61 -0
- package/cli/issues-act.mjs +371 -0
- package/cli/issues-write.mjs +441 -0
- package/cli/issues.mjs +513 -0
- package/cli/lib.mjs +37 -2
- package/cli/lifecycle.mjs +7 -0
- package/cli/local-page.mjs +138 -0
- package/cli/machine.mjs +1 -1
- package/cli/manifest.mjs +59 -3
- package/cli/map/view/app.js +712 -0
- package/cli/map/view/index.html +50 -0
- package/cli/map/view/style.css +142 -0
- package/cli/map-view.mjs +186 -0
- package/cli/map.mjs +637 -0
- package/cli/members.mjs +9 -15
- package/cli/next.mjs +1 -1
- package/cli/openpr.mjs +26 -6
- package/cli/plan.mjs +127 -0
- package/cli/platform.mjs +159 -4
- package/cli/product-index.mjs +1 -1
- package/cli/protection.mjs +53 -3
- package/cli/reconcile.mjs +9 -3
- package/cli/report.mjs +9 -3
- package/cli/reports-dir.mjs +391 -0
- package/cli/reports.mjs +65 -0
- package/cli/run-checks.mjs +15 -4
- package/cli/scan.mjs +314 -0
- package/cli/setup.mjs +42 -8
- package/cli/standup.mjs +120 -78
- package/cli/status.mjs +6 -5
- package/cli/story-frames.mjs +17 -6
- package/cli/test-agents-file.mjs +985 -12
- package/cli/test-brain-activity.mjs +753 -0
- package/cli/test-brain-view.mjs +381 -0
- package/cli/test-brain.mjs +795 -0
- package/cli/test-build.mjs +25 -0
- package/cli/test-ci-check.mjs +469 -10
- package/cli/test-guide.mjs +218 -0
- package/cli/test-machine.mjs +59 -0
- package/cli/test-map.mjs +615 -0
- package/cli/test-node.mjs +15 -0
- package/cli/test-reports.mjs +382 -0
- package/cli/test-run-checks.mjs +21 -0
- package/cli/test-setup-agent.mjs +14 -0
- package/cli/test-story-frames.mjs +74 -4
- package/cli/test-worktree.mjs +24 -3
- package/cli/toolbox-connect.mjs +259 -0
- package/cli/toolbox.mjs +187 -12
- package/cli/update-commit.mjs +101 -9
- package/cli/usage.mjs +8 -4
- package/package.json +12 -4
- package/skills/sdlc/config.yaml +1 -1
- package/skills/sdlc/module-help.csv +3 -1
- package/skills/yad-analysis/SKILL.md +4 -0
- package/skills/yad-architecture/SKILL.md +22 -4
- package/skills/yad-backfill/SKILL.md +4 -0
- package/skills/yad-change/SKILL.md +7 -1
- package/skills/yad-change/references/triage.md +2 -0
- package/skills/yad-checks/SKILL.md +15 -7
- package/skills/yad-checks/references/check-gates.md +70 -35
- package/skills/yad-checks/templates/checks/build-test-lint.sh +7 -0
- package/skills/yad-checks/templates/checks/install-deps.sh +6 -0
- package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
- package/skills/yad-checks/templates/checks/package-manager.sh +42 -0
- package/skills/yad-checks/templates/checks/risk-map-check.sh +2 -2
- package/skills/yad-checks/templates/checks/verified-commits.sh +3 -3
- package/skills/yad-checks/templates/github/yad-checks.yml +358 -69
- package/skills/yad-checks/templates/github/yad-pr-text.yml +118 -0
- package/skills/yad-checks/templates/github/yad-product-checks.yml +130 -54
- package/skills/yad-checks/templates/github/yad-product-pr-text.yml +131 -0
- package/skills/yad-checks/templates/github/yad-update-guard.yml +2 -1
- package/skills/yad-checks/templates/github/yad-verified-commits.yml +49 -3
- package/skills/yad-checks/templates/gitlab/yad-checks.gitlab-ci.yml +80 -20
- package/skills/yad-checks/templates/gitlab/yad-product-checks.gitlab-ci.yml +59 -9
- package/skills/yad-checks/templates/gitlab/yad-update-guard.gitlab-ci.yml +1 -0
- package/skills/yad-checks/templates/gitlab/yad-verified-commits.gitlab-ci.yml +49 -1
- package/skills/yad-checks/templates/hooks/agent-guard.mjs +44 -10
- package/skills/yad-checks/templates/hooks/ledger-guard-cursor.mjs +12 -6
- package/skills/yad-checks/templates/hooks/yad-activity.mjs +238 -0
- package/skills/yad-commit/SKILL.md +3 -1
- package/skills/yad-connect-design/SKILL.md +42 -10
- package/skills/yad-connect-design/references/design-context.md +35 -5
- package/skills/yad-connect-design/references/design-registry.md +3 -3
- package/skills/yad-connect-learning/SKILL.md +12 -2
- package/skills/yad-connect-repos/SKILL.md +18 -0
- package/skills/yad-connect-testing/SKILL.md +22 -5
- package/skills/yad-connect-testing/references/testing-context.md +1 -1
- package/skills/yad-discovery/SKILL.md +11 -0
- package/skills/yad-discovery/references/foundation-schema.md +11 -0
- package/skills/yad-docs/templates/app/package-lock.json +18 -10
- package/skills/yad-docs/templates/app/package.json +6 -1
- package/skills/yad-epic/SKILL.md +7 -0
- package/skills/yad-epic/references/state-schema.md +50 -1
- package/skills/yad-guide/SKILL.md +8 -4
- package/skills/yad-implement/SKILL.md +117 -4
- package/skills/yad-implement/references/implement-conventions.md +2 -1
- package/skills/yad-issues/SKILL.md +54 -0
- package/skills/yad-learn/SKILL.md +4 -0
- package/skills/yad-open-pr/SKILL.md +6 -0
- package/skills/yad-pr-template/SKILL.md +2 -1
- package/skills/yad-pr-template/templates/checks/pr-template.sh +8 -4
- package/skills/yad-pr-template/templates/checks/pr-title.sh +42 -6
- package/skills/yad-product-bridge/references/bridge.md +28 -0
- package/skills/yad-product-bridge/templates/github/yad-gate-sync.yml +25 -11
- package/skills/yad-product-bridge/templates/gitlab/yad-gate-sync.gitlab-ci.yml +38 -14
- package/skills/yad-run/SKILL.md +5 -0
- package/skills/yad-scan/SKILL.md +51 -0
- package/skills/yad-spec/SKILL.md +32 -2
- package/skills/yad-stories/SKILL.md +22 -4
- package/skills/yad-stories/references/story-schema.md +1 -1
- package/skills/yad-test-cases/SKILL.md +18 -2
- package/skills/yad-ui/SKILL.md +43 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/epic.mjs
CHANGED
|
@@ -40,6 +40,7 @@ import {
|
|
|
40
40
|
} from './epic-state.mjs';
|
|
41
41
|
import { epicFiles, isVerifiedLedger, productConfigPath } from './manifest.mjs';
|
|
42
42
|
import { refreshIndexAfterWrite } from './product-index.mjs';
|
|
43
|
+
import { foundationChanged, foundationReviewAgain, publishedItems } from './foundation-publish.mjs';
|
|
43
44
|
|
|
44
45
|
// `foo`, `EP-foo` and `epics/EP-foo` all name the same epic. Accepting only one spelling would make the
|
|
45
46
|
// command reject the id the user just read out of `yad next`.
|
|
@@ -51,11 +52,15 @@ export function epicIdFrom(slug) {
|
|
|
51
52
|
|
|
52
53
|
// `type` defaults to null rather than `feature` so an explicit `--type` is distinguishable from no
|
|
53
54
|
// flag at all — which is what lets an existing `epic.md` supply the answer without overriding the user.
|
|
54
|
-
export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false } = {}) {
|
|
55
|
+
export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false, returnResult = false } = {}) {
|
|
56
|
+
// `returnResult` (E170, with json): a caller that seeds as one part of its work gets the answer back, and
|
|
57
|
+
// it alone speaks, so stdout stays one JSON document.
|
|
58
|
+
const answer = returnResult ? (payload) => payload : emitJSON;
|
|
55
59
|
const bail = (message, hint) => {
|
|
56
|
-
if (json) emitJSON({ ok: false, error: message, hint });
|
|
57
|
-
else { fail(message); if (hint) hand(hint); }
|
|
58
60
|
process.exitCode = 1;
|
|
61
|
+
if (json) return answer({ ok: false, error: message, hint });
|
|
62
|
+
fail(message); if (hint) hand(hint);
|
|
63
|
+
return undefined;
|
|
59
64
|
};
|
|
60
65
|
|
|
61
66
|
const epic = epicIdFrom(slug);
|
|
@@ -169,7 +174,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
|
|
|
169
174
|
if (parent) {
|
|
170
175
|
return seedThreaded(root, {
|
|
171
176
|
epic, dir, files, mdPath, fm, type, parent, profile,
|
|
172
|
-
inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail,
|
|
177
|
+
inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail, answer,
|
|
173
178
|
});
|
|
174
179
|
}
|
|
175
180
|
profile = profile || 'classic';
|
|
@@ -230,7 +235,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
|
|
|
230
235
|
// `nextSkills` appears only for a bound chain, the same rule `yad next --json` follows — a key that
|
|
231
236
|
// showed up on every seed would be one more always-null field for every reader to ignore.
|
|
232
237
|
if (json) {
|
|
233
|
-
return
|
|
238
|
+
return answer({
|
|
234
239
|
ok: true, epic, type, profile, stub, currentStep: state.currentStep,
|
|
235
240
|
steps: state.steps.map((s) => s.id), next: skill,
|
|
236
241
|
...(skills.length > 1 ? { nextSkills: skills } : {}),
|
|
@@ -266,7 +271,7 @@ const listOf = (v) => (Array.isArray(v) ? v : String(v ?? '').replace(/^\s*\[|\]
|
|
|
266
271
|
// The threaded half of `yad epic new` (E42): a change, defect or hotfix off an epic that exists. The
|
|
267
272
|
// engine plans the chain from the parent (`planThreadedSeed`) and this writes it — the ledger, one
|
|
268
273
|
// provenance record per inherited gate, and the pointer-lock when the contract is carried.
|
|
269
|
-
function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail }) {
|
|
274
|
+
function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail, answer }) {
|
|
270
275
|
const plan = planThreadedSeed(root, { epic, parent, inherits, type, today });
|
|
271
276
|
if (!plan.ok) return bail(plan.message, plan.hint);
|
|
272
277
|
// The route is the parent's. A flag naming the same one is harmless; a different one is refused
|
|
@@ -319,7 +324,7 @@ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profil
|
|
|
319
324
|
const skills = stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
|
|
320
325
|
const carried = state.steps.filter((s) => s.inherited);
|
|
321
326
|
if (json) {
|
|
322
|
-
return
|
|
327
|
+
return answer({
|
|
323
328
|
ok: true, epic, type, profile: plan.profile, stub: false, parent, thread: plan.thread,
|
|
324
329
|
inherits, inheritedFrom: plan.owners, pointerLock: plan.lock ? plan.lock.ref : null, anchor: plan.anchor,
|
|
325
330
|
currentStep: state.currentStep, steps: state.steps.map((s) => s.id), next: skills[0] || null,
|
|
@@ -484,8 +489,18 @@ export async function runFoundationStatus(root, { json = false } = {}) {
|
|
|
484
489
|
} catch { return false; }
|
|
485
490
|
});
|
|
486
491
|
|
|
492
|
+
// E174: whether the Foundation changed after its review, so a reader is told before `publish` refuses.
|
|
493
|
+
let checkFailed = false;
|
|
494
|
+
let foundationLedger = null;
|
|
495
|
+
const changed = productId === FOUNDATION_EPIC && approved ? (() => { try { foundationLedger = loadLedger(dir); return foundationChanged(dir, foundationLedger); } catch { checkFailed = true; return true; } })() : false;
|
|
496
|
+
if (checkFailed) warnings.push('whether the Foundation changed after its review could not be checked — run `yad doctor`');
|
|
497
|
+
else if (changed) warnings.push(`the Foundation changed after its review, so \`yad foundation publish\` refuses until it is reviewed again — ${foundationReviewAgain(root, foundationLedger)}`);
|
|
498
|
+
// E174: the item each row was published as, from the record only. Null when the record cannot be read.
|
|
499
|
+
const items = productId === FOUNDATION_EPIC ? publishedItems(root) : new Map();
|
|
500
|
+
for (const f of features) f.item = items ? (items.get(f.epicId) ?? null) : null;
|
|
501
|
+
if (items === null) warnings.push('foundation/.sdlc/roadmap-items.json cannot be read, so no row shows its item');
|
|
487
502
|
if (json) {
|
|
488
|
-
return emitJSON({ ok: true, epic: productId, roadmap: rel, approved, features, unlisted, ...(warnings.length ? { warnings } : {}) });
|
|
503
|
+
return emitJSON({ ok: true, epic: productId, roadmap: rel, approved, changed, features, unlisted, ...(warnings.length ? { warnings } : {}) });
|
|
489
504
|
}
|
|
490
505
|
for (const w of warnings) warn(w);
|
|
491
506
|
log(`\n ${c.bold(`${productId} roadmap`)} ${c.dim(`${rel} — each status is read from the epic ledgers`)}`);
|
|
@@ -497,12 +512,13 @@ export async function runFoundationStatus(root, { json = false } = {}) {
|
|
|
497
512
|
const name = `${f.feature || '(no name)'} ${c.dim(f.epicId || '(no id)')}`;
|
|
498
513
|
if (f.problem) { log(` ${c.yellow('!')} ${name} ${c.yellow(f.problem)}`); continue; }
|
|
499
514
|
const mark = f.status === 'shipped' ? c.green('✓') : f.status === 'planned' ? c.dim('·') : c.cyan('•');
|
|
500
|
-
log(` ${mark} ${name} ${f.status}`);
|
|
515
|
+
log(` ${mark} ${name} ${f.status}${f.item ? c.dim(` #${f.item.number}`) : ''}`);
|
|
501
516
|
if (f.disagrees) log(` ${c.dim(`the row says "${f.written}" — that column is no longer kept by hand; the ledger's answer is shown`)}`);
|
|
502
517
|
}
|
|
503
518
|
if (unlisted.length) {
|
|
504
519
|
info(`not on the roadmap: ${unlisted.join(', ')} ${c.dim('(feature epics no row proposes — an epic may have been given a different id)')}`);
|
|
505
520
|
}
|
|
506
521
|
const next = features.find((f) => f.status === 'planned');
|
|
507
|
-
if (next) hand(`next planned feature: ${next.feature || next.epicId} — seed it with the yad-epic skill (proposed id ${next.epicId})`);
|
|
522
|
+
if (next) hand(`next planned feature: ${next.feature || next.epicId} — seed it with the yad-epic skill (proposed id ${next.epicId}${next.item ? `, from item #${next.item.number}` : ''})`);
|
|
523
|
+
if (productId === FOUNDATION_EPIC && approved && !items?.size && features.length && !changed) info('the roadmap is approved: `yad foundation publish` opens one issue / work item per feature in the Product repo');
|
|
508
524
|
}
|
package/cli/errors.mjs
CHANGED
|
@@ -27,11 +27,12 @@ export const CODES = {
|
|
|
27
27
|
'YAD-STATE-008': 'a file kept under two names (product.json + hub.json, or product-prs.json + hub-prs.json) says different things under each',
|
|
28
28
|
'YAD-STATE-009': 'a Build record cannot be written in its current state (no lane yet, a step out of order, a PR not merged, a task not shipped)',
|
|
29
29
|
'YAD-STATE-010': 'an epic worktree cannot be added or removed in its current state (a path taken, no origin, uncommitted or unpushed work, a lock)',
|
|
30
|
+
'YAD-STATE-011': 'the project brain (.sdlc/brain/graph.json) or a Graphify graph cannot be read, or names a format this yadflow does not read',
|
|
30
31
|
'YAD-CFG-001': 'the Product settings (product.json, or hub.json on a Product that has only that name) name an unknown platform (expected github, gitlab, or null)',
|
|
31
32
|
'YAD-CFG-002': 'design.json names an unknown design tool (expected one of config.yaml design.tools, or none)',
|
|
32
33
|
'YAD-CFG-003': 'testing.json names an unknown testing tool (expected one of config.yaml testing.tools, or none)',
|
|
33
34
|
'YAD-CFG-004': 'learning.json names an unknown learning tool (expected one of config.yaml learning.tools, or none)',
|
|
34
|
-
'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url (required to scope auth + open PRs)',
|
|
35
|
+
'YAD-CFG-005': 'the Product settings (product.json, or hub.json on a Product that has only that name) set a platform but are missing git_url, or name only a host in it with no repo path (required to scope auth + open PRs)',
|
|
35
36
|
'YAD-CFG-006': 'skills.json binds a step to something that is not a skill name (expected a string, or a non-empty list of strings)',
|
|
36
37
|
'YAD-CFG-007': 'toolbox.json has a line that does nothing — a tool this yadflow does not ship, a choice other than use or skip, or a custom tool that is incomplete, malformed, listed twice or uses a shipped tool\'s id',
|
|
37
38
|
'YAD-CLI-001': 'a --json run needed an answer that only a prompt could give',
|
package/cli/find-product.mjs
CHANGED
|
@@ -11,7 +11,8 @@
|
|
|
11
11
|
// - a folder that is a Product (it has `.sdlc/hub.json` or `.sdlc/product.json`) — so any subfolder of
|
|
12
12
|
// the Product finds it;
|
|
13
13
|
// - a folder holding `.yad-workspace.json` — its `product` names the Product folder beside the repos.
|
|
14
|
-
// It is used ONLY when `start` is inside a repo that Product registers in its `repos.json
|
|
14
|
+
// It is used ONLY when `start` is inside a repo that Product registers in its `repos.json`, or in a git
|
|
15
|
+
// worktree of one (yad's own, #115, or a plain one, #515). A
|
|
15
16
|
// workspace can be a shared folder (`~/Projects`, holding many teams' repos — setup always allowed
|
|
16
17
|
// that), and a file there must not send an unrelated repo's `yad epic new` or `yad kill` to this
|
|
17
18
|
// Product (E80 review 1). Anywhere else in the workspace there is no Product.
|
|
@@ -26,7 +27,7 @@ import os from 'node:os';
|
|
|
26
27
|
import path from 'node:path';
|
|
27
28
|
import { exists, readJSON, writeJSON } from './lib.mjs';
|
|
28
29
|
import { productConfigPath, PROJECT_FILES } from './manifest.mjs';
|
|
29
|
-
import { worktreeAt, sameDir } from './worktree-record.mjs';
|
|
30
|
+
import { worktreeAt, sameDir, linkedGitDir, commonDirOf } from './worktree-record.mjs';
|
|
30
31
|
|
|
31
32
|
export const WORKSPACE_FILE = '.yad-workspace.json';
|
|
32
33
|
export const WORKSPACE_VERSION = 1;
|
|
@@ -83,7 +84,11 @@ export function findProduct(start) {
|
|
|
83
84
|
for (let d = from; ; d = path.dirname(d)) {
|
|
84
85
|
if (exists(productConfigPath(d))) {
|
|
85
86
|
if (d === from) return { root: d, via: 'here' };
|
|
86
|
-
|
|
87
|
+
// A worktree of a registered repo is that repo (#115, #515 review 1), wherever it sits: a repo inside
|
|
88
|
+
// the Product's folder can have one beside it (`product/backend-wt`), past which the walk crossed.
|
|
89
|
+
// No epic routing here, unlike the workspace branch below: `yad worktree add` refuses a repo kept
|
|
90
|
+
// inside the Product's folder, so no epic worktree of one exists to route to.
|
|
91
|
+
const repo = registeredRepoHolding(d, from) ?? (codeWorktreeOf(d, from) || linkedRepoWorktreeOf(d, from))?.meta ?? null;
|
|
87
92
|
if (crossedRepo && !repo) return null;
|
|
88
93
|
return { root: d, via: 'above', ...(repo ? { repo } : {}) };
|
|
89
94
|
}
|
|
@@ -103,6 +108,9 @@ export function findProduct(start) {
|
|
|
103
108
|
const epicTree = epicProductWorktree(ws.product, wt.epic);
|
|
104
109
|
return { root: epicTree ?? ws.product, via: 'workspace', workspace: d, repo: wt.meta, ...(epicTree ? { worktree: wt.epic } : {}) };
|
|
105
110
|
}
|
|
111
|
+
// A plain git worktree of a registered repo (#515): that repo. It has no epic, so the main Product.
|
|
112
|
+
const plain = linkedRepoWorktreeOf(ws.product, from);
|
|
113
|
+
if (plain) return { root: ws.product, via: 'workspace', workspace: d, repo: plain.meta };
|
|
106
114
|
return { elsewhere: ws.product };
|
|
107
115
|
}
|
|
108
116
|
if (fs.existsSync(path.join(d, '.git'))) crossedRepo = true;
|
|
@@ -130,19 +138,49 @@ export function registeredRepoHolding(productRoot, dir) {
|
|
|
130
138
|
return best;
|
|
131
139
|
}
|
|
132
140
|
|
|
141
|
+
// Is `top` the worktree git knows by `gitDir`? Git keeps a back-link (`<gitDir>/gitdir`, absolute, or
|
|
142
|
+
// relative under `worktree.useRelativePaths`) to the worktree's `.git` file. A `.git` file written by hand
|
|
143
|
+
// that points at another worktree's git folder fails it, and so borrows nothing (#515).
|
|
144
|
+
function backLinked(top, gitDir) {
|
|
145
|
+
let back;
|
|
146
|
+
try { back = fs.readFileSync(path.join(gitDir, 'gitdir'), 'utf8').trim(); } catch { return false; }
|
|
147
|
+
return !!back && sameDir(path.resolve(gitDir, back), path.join(top, '.git'));
|
|
148
|
+
}
|
|
149
|
+
|
|
133
150
|
// The registered repo whose epic worktree (#115) holds `dir`: yad made it (its record names the repo), and
|
|
134
|
-
// its common git folder IS that repo's — a record copied into some other clone maps nothing
|
|
151
|
+
// its common git folder IS that repo's — a record copied into some other clone maps nothing, and a `.git`
|
|
152
|
+
// file pointing at the worktree from another folder is not it (`backLinked`, #515 review 2).
|
|
135
153
|
// → { meta, epic, top } or null.
|
|
136
154
|
export function codeWorktreeOf(productRoot, dir) {
|
|
137
155
|
const top = gitTopOf(dir);
|
|
138
156
|
const rec = worktreeAt(top);
|
|
139
|
-
if (!rec || typeof rec.repo !== 'string') return null;
|
|
157
|
+
if (!rec || typeof rec.repo !== 'string' || !backLinked(top, rec.gitDir)) return null;
|
|
140
158
|
const reg = readJSON(path.join(productRoot, PROJECT_FILES.reposRegistry), null);
|
|
141
159
|
const meta = (Array.isArray(reg?.repos) ? reg.repos : []).find((r) => r?.name === rec.repo && typeof r.path === 'string');
|
|
142
160
|
if (!meta || !sameDir(rec.main, path.resolve(productRoot, meta.path))) return null;
|
|
143
161
|
return { meta, epic: rec.epic, top };
|
|
144
162
|
}
|
|
145
163
|
|
|
164
|
+
// The registered repo a plain git worktree belongs to (#515): one made by `git worktree add` or by an agent
|
|
165
|
+
// tool (Claude Code's `.claude/worktrees/<name>`), with no yad record. Its main checkout — the folder holding
|
|
166
|
+
// the common `.git` — must BE the registered repo, not a folder inside it or another clone. And git's own
|
|
167
|
+
// back-link (`<common>/.git/worktrees/<id>/gitdir`) must name this worktree's `.git` file: a `.git` file
|
|
168
|
+
// written by hand could otherwise point at a registered repo's worktree folder and borrow its entry.
|
|
169
|
+
// → { meta, top } with `top` the worktree's own top (worked there, never swapped for the repo's), or null.
|
|
170
|
+
// Never the Product's own entry (`registeredRepoHolding` refuses it).
|
|
171
|
+
export function linkedRepoWorktreeOf(productRoot, dir) {
|
|
172
|
+
if (!productRoot) return null;
|
|
173
|
+
const top = gitTopOf(dir);
|
|
174
|
+
const gitDir = top && linkedGitDir(top);
|
|
175
|
+
if (!gitDir) return null;
|
|
176
|
+
if (!backLinked(top, gitDir)) return null;
|
|
177
|
+
const common = commonDirOf(gitDir);
|
|
178
|
+
if (!common || path.basename(common) !== '.git') return null;
|
|
179
|
+
const main = path.dirname(common);
|
|
180
|
+
const meta = registeredRepoHolding(productRoot, main);
|
|
181
|
+
return meta && sameDir(main, path.resolve(productRoot, meta.path)) ? { meta, top } : null;
|
|
182
|
+
}
|
|
183
|
+
|
|
146
184
|
// The epic's Product worktree beside the Product, when yad made one; else null.
|
|
147
185
|
export function epicProductWorktree(productRoot, epic) {
|
|
148
186
|
const root = path.resolve(productRoot);
|
|
@@ -235,21 +273,37 @@ export function toolsFolder(found, from) {
|
|
|
235
273
|
return best ?? from;
|
|
236
274
|
}
|
|
237
275
|
|
|
238
|
-
// The
|
|
239
|
-
//
|
|
240
|
-
//
|
|
241
|
-
//
|
|
242
|
-
export function
|
|
276
|
+
// The registered repo whose OWN checkout `dir` is in — never a worktree of it, never a nested repo. For the
|
|
277
|
+
// commands that work on the repo's files from its registered folder (`risk-map`, `codeowners`, `ci check`,
|
|
278
|
+
// which resolve `<Product>/<path>`): from a worktree they would act on the main checkout, on another
|
|
279
|
+
// branch, so they keep covering every repo there (E80 review 3, #515 review 1). → { meta, top } or null.
|
|
280
|
+
export function registeredCheckoutFor(productRoot, dir) {
|
|
243
281
|
if (!productRoot) return null;
|
|
244
282
|
const top = gitTopOf(dir);
|
|
245
283
|
if (!top) return null;
|
|
246
284
|
const meta = registeredRepoHolding(productRoot, top);
|
|
247
|
-
if (!meta)
|
|
248
|
-
// The one worktree that IS the registered repo's: an epic worktree yad made of it (#115).
|
|
249
|
-
const wt = codeWorktreeOf(productRoot, dir);
|
|
250
|
-
return wt && sameDir(wt.top, top) ? { meta: wt.meta, top } : null;
|
|
251
|
-
}
|
|
285
|
+
if (!meta) return null;
|
|
252
286
|
const at = real(path.resolve(productRoot, meta.path));
|
|
253
287
|
const topAt = real(top);
|
|
254
288
|
return at && topAt && fold(at) === fold(topAt) ? { meta, top } : null;
|
|
255
289
|
}
|
|
290
|
+
|
|
291
|
+
// The registry entry for the code repo a code-repo command runs in (E80), with the folder to work in.
|
|
292
|
+
// It is the CHECKOUT that must be the registered repo — not merely a folder inside it: a repo nested in
|
|
293
|
+
// `backend/` is another repo, and gets nothing. A git worktree of backend is backend on another branch: it
|
|
294
|
+
// gets backend's entry (its name, platform and default branch, #515), and `top` stays the worktree's own,
|
|
295
|
+
// so a command works where it runs and is never swapped for backend's checkout (E80 review 3).
|
|
296
|
+
// → { meta, top } or null. Never the Product's own entry.
|
|
297
|
+
export function registryEntryFor(productRoot, dir) {
|
|
298
|
+
if (!productRoot) return null;
|
|
299
|
+
const top = gitTopOf(dir);
|
|
300
|
+
if (!top) return null;
|
|
301
|
+
const own = registeredCheckoutFor(productRoot, dir);
|
|
302
|
+
if (own) return own;
|
|
303
|
+
// Not the registered checkout itself — a folder inside one, or beside it. Only a worktree of it counts: an
|
|
304
|
+
// epic worktree yad made (#115), or a plain git worktree, wherever it sits (#515), inside the repo
|
|
305
|
+
// (`.claude/worktrees/x`) or beside it. A repo nested inside one is neither, and gets nothing.
|
|
306
|
+
const wt = codeWorktreeOf(productRoot, dir);
|
|
307
|
+
if (wt && sameDir(wt.top, top)) return { meta: wt.meta, top };
|
|
308
|
+
return linkedRepoWorktreeOf(productRoot, dir);
|
|
309
|
+
}
|
package/cli/fold.mjs
CHANGED
|
@@ -30,7 +30,7 @@ import os from 'node:os';
|
|
|
30
30
|
import path from 'node:path';
|
|
31
31
|
import { ok, info, warn, fail, hand, readJSON } from './lib.mjs';
|
|
32
32
|
import { productConfigPath, isVerifiedLedger } from './manifest.mjs';
|
|
33
|
-
import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId } from './epic-state.mjs';
|
|
33
|
+
import { STEPS, FOUNDATION_EPIC, FOUNDATION_DIR, DISCOVERY_EPIC, artifactBase, artifactPaths, epicRoot, isValidEpicId, isDesignJunk, UI_DESIGN_DIR } from './epic-state.mjs';
|
|
34
34
|
import { capturedEpic, gitIn, isOwnerPath, statusEntries, wipName, wipBranch, runCapture } from './capture.mjs';
|
|
35
35
|
import { resolveDefaultBranch, preflightGuardReadiness } from './productcommit.mjs';
|
|
36
36
|
|
|
@@ -53,7 +53,32 @@ export function stepPaths(epic, stepId) {
|
|
|
53
53
|
if (!step) return null;
|
|
54
54
|
return [...artifactPaths(artifactBase(step.artifact)), ...(STEP_EXTRAS[stepId] || [])].map((p) => `${epicRel(epic)}/${p}`);
|
|
55
55
|
}
|
|
56
|
-
|
|
56
|
+
// A file the system or an editor drops in the UI design's `design/` folder (`.DS_Store`, `x.fig~`) is not
|
|
57
|
+
// the step's: the fingerprint leaves it out (`isDesignJunk`), so a fold that committed it would put a file
|
|
58
|
+
// in the review that no approval covers. It is left on disk like any other file. So is a nested repository
|
|
59
|
+
// there — git lists an untracked one as a folder (`design/kit/`) and a committed submodule by its folder
|
|
60
|
+
// name (`design/kit`), and `isRepo` (a folder holding `.git`) tells the second: `git add` would record a
|
|
61
|
+
// link to another repository, and the fingerprint skips it.
|
|
62
|
+
const covers = (paths, p, isRepo = null) => paths.some((s) => p === s
|
|
63
|
+
|| (p.startsWith(`${s}/`) && !(s.endsWith(`/${UI_DESIGN_DIR}`) && (isDesignJunk(p.slice(s.length + 1)) || p.endsWith('/') || !!isRepo?.(p)))));
|
|
64
|
+
// Is this Product-relative path a nested repository or a submodule — a folder holding `.git`, or a gitlink
|
|
65
|
+
// in the index (a submodule never initialised here has no `.git`)? The index's gitlinks are read once, on
|
|
66
|
+
// the first path that needs them, so many changed design files cost one git call. `GIT_LITERAL_PATHSPECS`
|
|
67
|
+
// is cleared so git reads the `:(glob)` pattern as a pattern.
|
|
68
|
+
export const repoAt = (root, env = process.env) => {
|
|
69
|
+
let gitlinks = null;
|
|
70
|
+
const links = () => {
|
|
71
|
+
if (gitlinks) return gitlinks;
|
|
72
|
+
const rest = Object.fromEntries(Object.entries(env).filter(([k]) => k !== 'GIT_LITERAL_PATHSPECS'));
|
|
73
|
+
const r = gitIn(root, rest, { GIT_OPTIONAL_LOCKS: '0' })(['ls-files', '-s', '-z', '--', `:(glob)**/${UI_DESIGN_DIR}/**`]);
|
|
74
|
+
gitlinks = new Set(r.ok ? r.out.split('\0').filter((e) => e.startsWith('160000 ')).map((e) => e.slice(e.indexOf('\t') + 1)) : []);
|
|
75
|
+
return gitlinks;
|
|
76
|
+
};
|
|
77
|
+
return (p) => {
|
|
78
|
+
const bare = p.replace(/\/$/, '');
|
|
79
|
+
return fs.existsSync(path.join(root, ...bare.split('/'), '.git')) || links().has(bare);
|
|
80
|
+
};
|
|
81
|
+
};
|
|
57
82
|
|
|
58
83
|
// The scope is the epic ID in lowercase (#413): the commit-message gate takes a lowercase scope
|
|
59
84
|
// (`[a-z0-9._-]`), so `docs(EP-x)` failed every review PR. The exact ID stays in the Yad-Epic trailer.
|
|
@@ -73,7 +98,7 @@ export const foldMessage = ({ epic, step, folded }) =>
|
|
|
73
98
|
// only while its state.json is off the base ref (#162))
|
|
74
99
|
// ci — ledger changes left for CI (verified mode, every other case)
|
|
75
100
|
// other — the epic's other changed artifacts, left on disk
|
|
76
|
-
export function sortChanges(entries, { epic, step, verified, seeding = false }) {
|
|
101
|
+
export function sortChanges(entries, { epic, step, verified, seeding = false, isRepo = null }) {
|
|
77
102
|
const own = stepPaths(epic, step) || [];
|
|
78
103
|
const dir = `${epicRel(epic)}/`;
|
|
79
104
|
const out = { step: [], seed: [], ledger: [], ci: [], other: [] };
|
|
@@ -83,7 +108,7 @@ export function sortChanges(entries, { epic, step, verified, seeding = false })
|
|
|
83
108
|
// `??` is untracked, `A` in the first column is added to the index: both are a file being created.
|
|
84
109
|
// ` A` is a file marked with `git add -N` (intent to add): new too.
|
|
85
110
|
const creating = xy === '??' || xy[0] === 'A' || xy === ' A';
|
|
86
|
-
if (covers(own, p)) out.step.push(p);
|
|
111
|
+
if (covers(own, p, isRepo)) out.step.push(p);
|
|
87
112
|
// A step owner file (E47) is never folded: an assignment is not authoring, and a fold that carried one
|
|
88
113
|
// alone would be a "docs: author <step>" commit with nothing authored. It is committed on its own.
|
|
89
114
|
else if (isOwnerPath(p)) out.other.push(p);
|
|
@@ -108,7 +133,7 @@ export function unfoldedPaths(root, epic, base, env = process.env) {
|
|
|
108
133
|
const own = stepPaths(epic, authorStepOf(base)) || [];
|
|
109
134
|
// A per-story branch (`stories-S01`) reviews that one story: another story's edit is not its business.
|
|
110
135
|
const story = /^stories-S\d+$/i.test(base) ? base.toLowerCase() : null;
|
|
111
|
-
return entries.map((e) => e.path).filter((p) => covers(own, p) && (!story || artifactBase(p).toLowerCase() === story));
|
|
136
|
+
return entries.map((e) => e.path).filter((p) => covers(own, p, repoAt(root, env)) && (!story || artifactBase(p).toLowerCase() === story));
|
|
112
137
|
}
|
|
113
138
|
|
|
114
139
|
// `yad fold <epic> <step>`. Returns a plain object (E1 turns it into the `--json` answer); a refusal
|
|
@@ -170,7 +195,7 @@ export async function runFold(root, { epic, step, env = process.env, capture = r
|
|
|
170
195
|
const seededAt = (e) => git(['cat-file', '-e', `HEAD:./${epicRel(e)}/.sdlc/state.json`]).ok;
|
|
171
196
|
const productLevel = epic === FOUNDATION_EPIC || epic === DISCOVERY_EPIC;
|
|
172
197
|
const seeding = productLevel ? !seededAt(FOUNDATION_EPIC) && !seededAt(DISCOVERY_EPIC) : !seededAt(epic);
|
|
173
|
-
const sorted = sortChanges(entries, { epic, step, verified, seeding });
|
|
198
|
+
const sorted = sortChanges(entries, { epic, step, verified, seeding, isRepo: repoAt(root, env) });
|
|
174
199
|
// What `git add` can take: a path on disk or in the index. A deletion already staged (`D `, from `git rm`
|
|
175
200
|
// or the old half of a `git mv`) is in neither, and `git add` would refuse it — but it is in HEAD, so
|
|
176
201
|
// `commit --only` commits the deletion. A path added and then deleted (`AD`) is in none of the three and
|
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
// E174 — the approved roadmap becomes work items in the Product repo. After the Foundation review passes,
|
|
2
|
+
// `yad foundation publish` opens one GitHub issue or GitLab work item per roadmap feature: type feature, a
|
|
3
|
+
// priority by phase (the first phase is the MVP: P1, then P2, then P3), the label `epic: EP-x`, and the
|
|
4
|
+
// phase as its milestone. A "parked" phase is a decision not to build yet, so it is left out.
|
|
5
|
+
//
|
|
6
|
+
// The record of what was published is `foundation/.sdlc/roadmap-items.json`. It is outside the Foundation's
|
|
7
|
+
// fingerprint (only the section files count), so publishing never makes the review stale. A lost record does
|
|
8
|
+
// not cause duplicates: each item's body carries `<!-- yad-roadmap: EP-x -->`, and those are read first.
|
|
9
|
+
import fs from 'node:fs';
|
|
10
|
+
import path from 'node:path';
|
|
11
|
+
import { run, forTerminal, readJSON, readJSONStrict, writeJSON, c, log, fail, hand, info, warn, emitJSON } from './lib.mjs';
|
|
12
|
+
import { err } from './errors.mjs';
|
|
13
|
+
import { isVerifiedLedger, productConfigPath, epicFiles } from './manifest.mjs';
|
|
14
|
+
import { acceptedHashes, artifactBase, doneStepUnapproved, epicRoot, isStaleHash, FOUNDATION_EPIC, isValidEpicId, loadLedger, PRODUCT_DONE, PRODUCT_EPICS, reviewAsItStands, roadmapFeatures, soloRereviewCovers } from './epic-state.mjs';
|
|
15
|
+
import { productGit, resolveDefaultBranch } from './productcommit.mjs';
|
|
16
|
+
import { isSolo } from './gate.mjs';
|
|
17
|
+
import { createLabel, labelRules, readLabels } from './issues.mjs';
|
|
18
|
+
import { linkAndWriteBack, readItem, recordRoute } from './issues-write.mjs';
|
|
19
|
+
import { readLinks, itemKey } from './issue-links.mjs';
|
|
20
|
+
import { targetOf } from './issues-act.mjs';
|
|
21
|
+
import { readMilestones, safeTitle } from './scan.mjs';
|
|
22
|
+
import { api } from './protection.mjs';
|
|
23
|
+
import { createMilestone, newItem } from './platform.mjs';
|
|
24
|
+
|
|
25
|
+
const RECORD = path.join('.sdlc', 'roadmap-items.json');
|
|
26
|
+
const MARKER = /<!-- yad-roadmap: (EP-[a-z0-9-]+) -->/g;
|
|
27
|
+
const PAGE = 100;
|
|
28
|
+
// The template's own heading for deferred work, exactly: a phase that merely contains the word ("Car park finder") counts.
|
|
29
|
+
const PARKED = /^(later\s*\/\s*)?parked?$/i;
|
|
30
|
+
|
|
31
|
+
// Whether the Foundation as it stands is not what its review passed. A solo re-review that merged this very
|
|
32
|
+
// content answers first (`rereviews`, written by `yad gate sync`/`gate ci`): it is newer than any approval or
|
|
33
|
+
// close, and a Product that switched to solo after a team review keeps its old, now stale, approvals. Then
|
|
34
|
+
// approvals answer when there are any. With none (a solo Product passes on the merge alone), the fingerprint
|
|
35
|
+
// the step was closed with answers. Neither: no claim.
|
|
36
|
+
export function foundationChanged(dir, ledger) {
|
|
37
|
+
const review = ledger.state?.steps?.find((st) => st.type === 'review+approve');
|
|
38
|
+
if (!review) return false;
|
|
39
|
+
if (Array.isArray(review.rereviews) && review.rereviews.length && soloRereviewCovers(review, acceptedHashes(dir, review.artifact))) return false;
|
|
40
|
+
const approved = (Array.isArray(ledger.approvals) ? ledger.approvals : []).filter((a) => a?.step === review.id && a.status === 'approved');
|
|
41
|
+
// Approvals with no fingerprint make no claim, so the closing fingerprint decides for them too.
|
|
42
|
+
const hashed = approved.filter((a) => a.artifactHash);
|
|
43
|
+
if (hashed.length) return !!doneStepUnapproved(dir, review, hashed);
|
|
44
|
+
const hash = review.closed?.hash;
|
|
45
|
+
return !!hash && isStaleHash(hash, acceptedHashes(dir, review.artifact));
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
// How a changed Foundation gets reviewed again. Not `yad gate reopen`: that refuses the Foundation
|
|
49
|
+
// (reopenStep, "it runs once per product"). Each arm says the step that really clears `foundationChanged`:
|
|
50
|
+
// - no platform: `yad gate approve` records an approval bound to today's content, on a passed step too
|
|
51
|
+
// (gate-local) — the person's command, never the agent's;
|
|
52
|
+
// - a platform: the review as it stands on a fresh PR/MR (#418), the steps `yad next` prints. In team mode
|
|
53
|
+
// its approvals clear it; in solo mode its merge does (`rereviews`), recorded by `yad gate sync` on a
|
|
54
|
+
// local ledger and by CI at the merge on a verified one.
|
|
55
|
+
export function foundationReviewAgain(root, ledger) {
|
|
56
|
+
const review = ledger?.state?.steps?.find((st) => st.type === 'review+approve');
|
|
57
|
+
const artifact = review?.artifact ?? 'foundation/';
|
|
58
|
+
const productConfig = readJSON(productConfigPath(root), null);
|
|
59
|
+
const platform = productConfig?.platform;
|
|
60
|
+
if (platform !== 'github' && platform !== 'gitlab') {
|
|
61
|
+
return `review it again on this machine (your command, not the agent's): \`yad gate approve ${FOUNDATION_EPIC} ${artifact} --by <your name>\``;
|
|
62
|
+
}
|
|
63
|
+
const fresh = reviewAsItStands(FOUNDATION_EPIC, artifact, resolveDefaultBranch(productGit(root), productConfig));
|
|
64
|
+
if (!isSolo(productConfig)) return `${fresh}; once it is approved and merged, its approvals cover the Foundation`;
|
|
65
|
+
return isVerifiedLedger(productConfig)
|
|
66
|
+
? `${fresh}; merge it yourself (solo mode) — CI records the merge as the new review (CI must run this yadflow release or later; if that run failed, run it again: \`yad gate ci --branch review/${FOUNDATION_EPIC}/${artifactBase(artifact)} --pr <n> --merged\`)`
|
|
67
|
+
: `${fresh}; merge it yourself (solo mode), then \`yad gate sync ${FOUNDATION_EPIC}\` records the merge as the new review`;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
export const priorityForPhase = (index) => (index === 0 ? 'P1' : index === 1 ? 'P2' : 'P3');
|
|
71
|
+
const recordPath = (root) => path.join(epicRoot(root, FOUNDATION_EPIC), RECORD);
|
|
72
|
+
|
|
73
|
+
const validEntry = (e) => !!e && typeof e === 'object' && !Array.isArray(e) && isValidEpicId(e.epicId) && !!e.host && !!e.repo && Number.isInteger(e.number);
|
|
74
|
+
// Strict, as every read before a write is: a record that cannot be understood is refused, never replaced.
|
|
75
|
+
export function readRecord(root) {
|
|
76
|
+
const p = recordPath(root);
|
|
77
|
+
const doc = readJSONStrict(p, { items: [] });
|
|
78
|
+
if (!doc || typeof doc !== 'object' || !Array.isArray(doc.items) || !doc.items.every(validEntry)) throw err('YAD-STATE-001', `${p} is not a roadmap-items file`, 'fix the file or restore it from git');
|
|
79
|
+
return doc.items;
|
|
80
|
+
}
|
|
81
|
+
const writeRecord = (root, items) => { fs.mkdirSync(path.dirname(recordPath(root)), { recursive: true }); writeJSON(recordPath(root), { items }); };
|
|
82
|
+
|
|
83
|
+
// The rows to publish, with each one's phase, priority and milestone title. The first table row of an id wins.
|
|
84
|
+
export function roadmapRows(text, skipped = [], nearMiss = []) {
|
|
85
|
+
const phases = [];
|
|
86
|
+
const seen = new Set();
|
|
87
|
+
const rows = [];
|
|
88
|
+
for (const r of roadmapFeatures(text)) {
|
|
89
|
+
const phase = (r.phase ?? 'Roadmap').trim();
|
|
90
|
+
if (PARKED.test(phase)) { if (!skipped.includes(phase)) skipped.push(phase); continue; }
|
|
91
|
+
if (/\b(later|parked?)\b/i.test(phase) && !nearMiss.includes(phase)) nearMiss.push(phase);
|
|
92
|
+
if (!isValidEpicId(r.epicId) || PRODUCT_EPICS.includes(r.epicId) || seen.has(r.epicId)) continue;
|
|
93
|
+
seen.add(r.epicId);
|
|
94
|
+
if (!phases.includes(phase)) phases.push(phase);
|
|
95
|
+
rows.push({ epicId: r.epicId, feature: forTerminal(r.feature).replace(/\s+/g, ' ').trim() || r.epicId, phase, priority: priorityForPhase(phases.indexOf(phase)) });
|
|
96
|
+
}
|
|
97
|
+
return rows;
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
// The item already published for one row: open or closed, carrying both the row's `epic: EP-x` label and its body
|
|
101
|
+
// marker. The label matters: a person who can only open issues cannot set one, so a stranger's issue that copies
|
|
102
|
+
// the marker does not claim the row. Asked per row, so a busy repo is never too big to read.
|
|
103
|
+
// `{ found: {number,url} | null }`, or `{ unread: true }`.
|
|
104
|
+
function publishedOn(t, epicId, runner) {
|
|
105
|
+
const gh = t.platform === 'github';
|
|
106
|
+
const label = encodeURIComponent(`epic: ${epicId}`);
|
|
107
|
+
const at = gh ? `repos/${t.repo}/issues?labels=${label}&state=all&per_page=${PAGE}` : `projects/${encodeURIComponent(t.repo)}/issues?labels=${label}&scope=all&per_page=${PAGE}`;
|
|
108
|
+
// An epic's defects and changes may carry its label too, so the pages are followed until the marker turns up.
|
|
109
|
+
for (let page = 1; page <= 10; page++) {
|
|
110
|
+
const res = api(runner, t.cli, t.host, `${at}&page=${page}`);
|
|
111
|
+
if (!res.ok || !Array.isArray(res.body)) return { unread: true };
|
|
112
|
+
for (const it of res.body) {
|
|
113
|
+
if (gh && it?.pull_request) continue;
|
|
114
|
+
const n = gh ? it?.number : it?.iid;
|
|
115
|
+
const marks = [...String((gh ? it?.body : it?.description) ?? '').matchAll(MARKER)].map((m) => m[1]);
|
|
116
|
+
if (Number.isInteger(n) && marks.includes(epicId)) return { found: { number: n, url: (gh ? it?.html_url : it?.web_url) ?? null } };
|
|
117
|
+
}
|
|
118
|
+
if (res.body.length < PAGE) return { found: null };
|
|
119
|
+
}
|
|
120
|
+
return { unread: true };
|
|
121
|
+
}
|
|
122
|
+
|
|
123
|
+
// The phase is the team's heading; `safeTitle` breaks a mention or reference so one publish notifies nobody.
|
|
124
|
+
const bodyFor = (row) => `A feature on the approved roadmap, phase: ${safeTitle(row.phase.replace(/[*_`<>[\]]/g, ''))}. Its proposed epic is \`${row.epicId}\`.\n\nStart the epic with \`yad epic new ${row.epicId} --issue <this item's number>\` to link it here, so this item's status follows the epic. \`yad foundation publish\` also links an epic that already exists.\n\n<!-- yad-roadmap: ${row.epicId} -->`;
|
|
125
|
+
// GitLab allows 255 characters in a title; cut by character, never inside one.
|
|
126
|
+
const titleFor = (feature) => [...feature].slice(0, 255).join('');
|
|
127
|
+
|
|
128
|
+
export async function runFoundationPublish(root, { dryRun = false, json = false, env = process.env, runner = run, now = Date.now() } = {}) {
|
|
129
|
+
const refuse = (message, hint) => {
|
|
130
|
+
process.exitCode = 1;
|
|
131
|
+
if (json) return emitJSON({ ok: false, error: message, hint: hint ?? null });
|
|
132
|
+
fail(message); if (hint) hand(hint);
|
|
133
|
+
return undefined;
|
|
134
|
+
};
|
|
135
|
+
if (!fs.existsSync(productConfigPath(root))) return refuse('not a Product (no .sdlc/product.json here)', 'run it from the Product, or pass --dir');
|
|
136
|
+
const dir = epicRoot(root, FOUNDATION_EPIC);
|
|
137
|
+
if (!fs.existsSync(epicFiles(dir).state)) return refuse('this product has no Foundation', 'run `yad foundation new`, then the yad-discovery skill');
|
|
138
|
+
let ledger;
|
|
139
|
+
try { ledger = loadLedger(dir); } catch { return refuse('the Foundation\'s ledger cannot be read', 'run `yad doctor`'); }
|
|
140
|
+
// Only an approved roadmap: a draft could still lose or rename features.
|
|
141
|
+
if (!PRODUCT_DONE.includes(ledger.state?.currentStep)) return refuse('the Foundation has not passed its review yet, so the roadmap is not final', 'publish it after the review: the backlog should hold only approved features');
|
|
142
|
+
// Approved once is not enough: a roadmap edited since its review holds rows nobody approved.
|
|
143
|
+
let changed;
|
|
144
|
+
try { changed = foundationChanged(dir, ledger); } catch { return refuse('the Foundation\'s review could not be checked', 'run `yad doctor`'); }
|
|
145
|
+
if (changed) return refuse('the Foundation changed after its review, so the review no longer covers the roadmap', `have the Foundation reviewed again, then publish — ${foundationReviewAgain(root, ledger)}`);
|
|
146
|
+
const file = path.join(dir, 'roadmap.md');
|
|
147
|
+
if (!fs.existsSync(file)) return refuse('foundation/roadmap.md does not exist');
|
|
148
|
+
const skipped = [];
|
|
149
|
+
const nearMiss = [];
|
|
150
|
+
const rows = roadmapRows(fs.readFileSync(file, 'utf8'), skipped, nearMiss);
|
|
151
|
+
const record = readRecord(root);
|
|
152
|
+
if (env.YAD_PLATFORM_READ === '0') return refuse('platform reads are turned off (YAD_PLATFORM_READ=0)');
|
|
153
|
+
let where;
|
|
154
|
+
try { where = targetOf(root, null, { env, runner }); } catch (e) { return refuse(e.message, e.hint); }
|
|
155
|
+
const { t, productConfig } = where;
|
|
156
|
+
const rules = labelRules(productConfig);
|
|
157
|
+
const out = { ok: true, dryRun, created: [], recovered: [], alreadyPublished: 0, linked: [], failed: [], notes: [...skipped.map((p) => `the phase "${forTerminal(p)}" is parked, so its rows were left out`), ...nearMiss.map((p) => `the phase "${forTerminal(p)}" is published; only a heading of "Parked" or "Later / parked" is left out`)] };
|
|
158
|
+
// Whether the record file changed (#512 review 2): an item is recorded before its labels are checked, so a row
|
|
159
|
+
// in `failed` may still have been written. Not in `out`: the --json envelope keeps its keys.
|
|
160
|
+
let wroteRecord = false;
|
|
161
|
+
const known = new Map(record.filter((e) => e.host === t.host && e.repo === t.repo).map((e) => [e.epicId, e]));
|
|
162
|
+
const todo = rows.filter((r) => !known.has(r.epicId));
|
|
163
|
+
out.alreadyPublished = rows.length - todo.length;
|
|
164
|
+
|
|
165
|
+
if (todo.length) {
|
|
166
|
+
// A lost or uncommitted record must not mean a second item for the same feature.
|
|
167
|
+
const markers = new Map();
|
|
168
|
+
for (const r of todo) {
|
|
169
|
+
const p = publishedOn(t, r.epicId, runner);
|
|
170
|
+
if (p.unread) return refuse(`the items labelled "epic: ${r.epicId}" could not be read, so nothing was created`, 'run it again; already published features are never created twice');
|
|
171
|
+
if (p.found) markers.set(r.epicId, p.found);
|
|
172
|
+
}
|
|
173
|
+
const fresh = [];
|
|
174
|
+
for (const r of todo) {
|
|
175
|
+
const m = markers.get(r.epicId);
|
|
176
|
+
if (m) { out.recovered.push({ epicId: r.epicId, number: m.number, url: m.url }); if (!dryRun) record.push({ epicId: r.epicId, platform: t.platform, host: t.host, repo: t.repo, number: m.number, url: m.url, publishedAt: new Date(now).toISOString() }); }
|
|
177
|
+
else fresh.push(r);
|
|
178
|
+
}
|
|
179
|
+
if (out.recovered.length && !dryRun) { writeRecord(root, record); wroteRecord = true; }
|
|
180
|
+
const labelsOf = (r) => [rules.type.feature[0], rules.priority[r.priority][0], `epic: ${r.epicId}`];
|
|
181
|
+
if (t.platform === 'gitlab' && fresh.some((r) => labelsOf(r).some((l) => l.includes(',')))) return refuse('a GitLab label name with a comma cannot be sent', 'rename that label in the issues settings of .sdlc/product.json');
|
|
182
|
+
if (dryRun) for (const r of fresh) out.created.push({ epicId: r.epicId, feature: r.feature, phase: r.phase, priority: r.priority, number: null, url: null, wouldCreate: true });
|
|
183
|
+
else if (fresh.length) {
|
|
184
|
+
const have = readLabels(t, runner);
|
|
185
|
+
if (have.ok) for (const name of new Set(fresh.flatMap(labelsOf))) if (!have.names.has(name.toLowerCase())) createLabel(t, name, name.startsWith('epic: ') ? 'c5def5' : '1d76db', runner);
|
|
186
|
+
const milestones = readMilestones(t, runner);
|
|
187
|
+
if (!milestones) out.notes.push('the milestones could not be read, so these items have none');
|
|
188
|
+
const idOf = new Map();
|
|
189
|
+
const milestoneFor = (phase) => {
|
|
190
|
+
if (!milestones) return null;
|
|
191
|
+
if (idOf.has(phase)) return idOf.get(phase);
|
|
192
|
+
let id = milestones.get(phase) ?? null;
|
|
193
|
+
if (id === null) {
|
|
194
|
+
const r = createMilestone(t, phase, { runner });
|
|
195
|
+
try { id = r.ok ? (t.platform === 'github' ? JSON.parse(r.stdout).number : JSON.parse(r.stdout).id) ?? null : null; } catch { id = null; }
|
|
196
|
+
if (id === null) out.notes.push(`the milestone "${forTerminal(phase)}" could not be created`);
|
|
197
|
+
}
|
|
198
|
+
idOf.set(phase, id);
|
|
199
|
+
return id;
|
|
200
|
+
};
|
|
201
|
+
for (const r of fresh) {
|
|
202
|
+
const labels = labelsOf(r);
|
|
203
|
+
const milestone = milestoneFor(r.phase);
|
|
204
|
+
const res = newItem(t, { title: titleFor(r.feature), body: bodyFor(r), labels, milestone }, { runner });
|
|
205
|
+
if (!res.ok) { out.failed.push({ epicId: r.epicId, why: 'the platform refused to create it' }); continue; }
|
|
206
|
+
let b = {};
|
|
207
|
+
try { b = JSON.parse(res.stdout); } catch { /* checked below */ }
|
|
208
|
+
const number = t.platform === 'github' ? b.number : b.iid;
|
|
209
|
+
if (!Number.isInteger(number)) { out.failed.push({ epicId: r.epicId, why: 'the answer named no item number' }); continue; }
|
|
210
|
+
const url = b.html_url ?? b.web_url ?? null;
|
|
211
|
+
record.push({ epicId: r.epicId, platform: t.platform, host: t.host, repo: t.repo, number, url, publishedAt: new Date(now).toISOString() });
|
|
212
|
+
writeRecord(root, record);
|
|
213
|
+
wroteRecord = true;
|
|
214
|
+
const got = (Array.isArray(b.labels) ? b.labels : []).map((l) => String(typeof l === 'string' ? l : l?.name).toLowerCase());
|
|
215
|
+
const missing = labels.filter((l) => !got.includes(l.toLowerCase()));
|
|
216
|
+
const row = { epicId: r.epicId, feature: r.feature, phase: r.phase, priority: r.priority, number, url };
|
|
217
|
+
if (missing.length) out.failed.push({ ...row, why: `created, but the labels ${missing.join(', ')} were not set: add them on #${number}, or a later publish cannot recognise it` });
|
|
218
|
+
else if (milestone !== null && !b.milestone) out.failed.push({ ...row, why: 'created, but the milestone was not set' });
|
|
219
|
+
else out.created.push(row);
|
|
220
|
+
}
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
|
|
224
|
+
// A feature whose epic already exists is linked, so its status flows back to the item.
|
|
225
|
+
for (const e of record.filter((x) => x.host === t.host && x.repo === t.repo)) {
|
|
226
|
+
if (!rows.some((r) => r.epicId === e.epicId) || !fs.existsSync(epicFiles(epicRoot(root, e.epicId)).state)) continue;
|
|
227
|
+
let links;
|
|
228
|
+
try { links = readLinks(root, e.epicId); } catch { out.notes.push(`${e.epicId}: its .sdlc/issue-links.json could not be read, so it was not linked`); continue; }
|
|
229
|
+
if (links.some((l) => itemKey(l) === itemKey(e))) continue;
|
|
230
|
+
if (dryRun) { out.linked.push({ epicId: e.epicId, number: e.number, wouldLink: true }); continue; }
|
|
231
|
+
const item = readItem(t, e.number, { runner });
|
|
232
|
+
if (!item.ok) { out.notes.push(`${e.epicId}: item ${e.number} could not be read, so it was not linked`); continue; }
|
|
233
|
+
const epicType = (() => { try { return loadLedger(epicRoot(root, e.epicId)).state?.type ?? null; } catch { return null; } })();
|
|
234
|
+
try {
|
|
235
|
+
const { back } = linkAndWriteBack(root, e.epicId, t, item, { rules, epicType, now, runner });
|
|
236
|
+
out.linked.push({ epicId: e.epicId, number: e.number, failed: back.failed });
|
|
237
|
+
} catch (x) { out.notes.push(`${e.epicId}: it could not be linked (${forTerminal(x?.message ?? String(x))})`); }
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
if (out.failed.length) { out.ok = false; process.exitCode = 1; }
|
|
241
|
+
if (json) return out;
|
|
242
|
+
for (const x of out.created) log(` ${x.priority} ${forTerminal(x.feature)} ${c.dim(`(${x.epicId}, ${forTerminal(x.phase)})`)} ${dryRun ? c.dim('would be created') : x.url ?? `#${x.number}`}`);
|
|
243
|
+
for (const x of out.recovered) info(`${x.epicId} was already on the Product repo as #${x.number}; ${dryRun ? 'it would be recorded' : 'recorded it'}`);
|
|
244
|
+
for (const x of out.linked) info(`${x.epicId} ${x.wouldLink ? 'would be linked' : 'linked'} to #${x.number}`);
|
|
245
|
+
for (const x of out.failed) warn(`${x.epicId}: ${forTerminal(x.why)}${x.url ? ` ${x.url}` : ''}`);
|
|
246
|
+
for (const n of out.notes) info(n);
|
|
247
|
+
info(`${out.created.length} ${dryRun ? 'would be created' : 'created'}, ${out.alreadyPublished} already published`);
|
|
248
|
+
const records = [wroteRecord && 'foundation/.sdlc/roadmap-items.json', out.linked.length && 'the epics\' .sdlc/issue-links.json'].filter(Boolean);
|
|
249
|
+
if (!dryRun && records.length) info(`${recordRoute(root, records.join(' and '))}, so the team keeps the record`);
|
|
250
|
+
return undefined;
|
|
251
|
+
}
|
|
252
|
+
|
|
253
|
+
// For `yad foundation status`: the item each row was published as, read from the record only (no network).
|
|
254
|
+
export function publishedItems(root) {
|
|
255
|
+
try { return new Map(readRecord(root).map((e) => [e.epicId, { number: e.number, url: e.url ?? null }])); } catch { return null; }
|
|
256
|
+
}
|