yadflow 4.8.0 → 4.10.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 +114 -0
- package/README.md +4 -3
- package/bin/commands.mjs +7 -0
- package/bin/yad.mjs +123 -8
- package/cli/agent-guard.mjs +793 -65
- package/cli/agent-rules.mjs +40 -5
- package/cli/argv-flags.mjs +1 -1
- package/cli/build.mjs +1 -1
- package/cli/ci-check.mjs +45 -1
- package/cli/codeowners-command.mjs +72 -6
- package/cli/commit.mjs +17 -3
- package/cli/docs.mjs +2 -0
- package/cli/doctor.mjs +176 -12
- package/cli/epic-state.mjs +94 -4
- package/cli/epic.mjs +11 -7
- package/cli/fold.mjs +31 -6
- package/cli/guide.mjs +3 -1
- package/cli/hook.mjs +50 -7
- package/cli/issue-links.mjs +61 -0
- package/cli/issues-act.mjs +327 -0
- package/cli/issues-write.mjs +428 -0
- package/cli/issues.mjs +474 -0
- package/cli/lifecycle.mjs +7 -0
- package/cli/machine.mjs +141 -0
- package/cli/manifest.mjs +9 -3
- package/cli/openpr.mjs +69 -9
- package/cli/plan.mjs +2 -0
- package/cli/platform.mjs +157 -2
- package/cli/preview.mjs +253 -0
- package/cli/protection.mjs +21 -3
- package/cli/reconcile.mjs +1 -1
- package/cli/repo.mjs +64 -3
- package/cli/review.mjs +4 -0
- package/cli/run-checks.mjs +10 -2
- package/cli/scan.mjs +314 -0
- package/cli/setup.mjs +12 -3
- package/cli/standup.mjs +33 -7
- package/cli/story-frames.mjs +307 -0
- package/cli/test-agents-file.mjs +378 -11
- package/cli/test-build.mjs +25 -0
- package/cli/test-ci-check.mjs +469 -10
- package/cli/test-guide.mjs +7 -0
- package/cli/test-machine.mjs +140 -0
- package/cli/test-node.mjs +15 -0
- package/cli/test-preview.mjs +511 -0
- package/cli/test-run-checks.mjs +17 -0
- package/cli/test-setup-agent.mjs +14 -0
- package/cli/test-story-frames.mjs +409 -0
- package/cli/toolbox-connect.mjs +244 -0
- package/cli/toolbox.mjs +159 -5
- package/package.json +7 -3
- 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-backfill/SKILL.md +4 -0
- package/skills/yad-change/SKILL.md +4 -0
- package/skills/yad-checks/SKILL.md +13 -7
- package/skills/yad-checks/references/check-gates.md +62 -30
- package/skills/yad-checks/templates/checks/member-check.mjs +3 -2
- 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 +357 -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 +79 -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-commit/SKILL.md +3 -1
- package/skills/yad-connect-design/SKILL.md +48 -13
- package/skills/yad-connect-design/references/design-context.md +56 -3
- package/skills/yad-connect-design/references/design-registry.md +4 -4
- package/skills/yad-connect-learning/SKILL.md +12 -2
- package/skills/yad-connect-repos/SKILL.md +12 -0
- package/skills/yad-connect-testing/SKILL.md +22 -5
- package/skills/yad-connect-testing/references/testing-context.md +1 -1
- package/skills/yad-engineer-review/SKILL.md +13 -0
- package/skills/yad-epic/SKILL.md +4 -0
- package/skills/yad-epic/references/state-schema.md +21 -0
- package/skills/yad-guide/SKILL.md +8 -4
- package/skills/yad-implement/SKILL.md +69 -3
- package/skills/yad-implement/references/implement-conventions.md +2 -1
- package/skills/yad-issues/SKILL.md +53 -0
- package/skills/yad-learn/SKILL.md +4 -0
- package/skills/yad-open-pr/SKILL.md +10 -1
- package/skills/yad-pair-review/SKILL.md +5 -0
- package/skills/yad-pr-template/SKILL.md +2 -1
- package/skills/yad-pr-template/templates/checks/pr-title.sh +34 -2
- package/skills/yad-pr-template/templates/github/pull_request_template.md +1 -0
- package/skills/yad-pr-template/templates/gitlab/merge_request_templates/Default.md +1 -0
- 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-review-companion/SKILL.md +4 -1
- package/skills/yad-run/SKILL.md +5 -0
- package/skills/yad-scan/SKILL.md +51 -0
- package/skills/yad-spec/SKILL.md +32 -0
- package/skills/yad-stories/SKILL.md +22 -0
- package/skills/yad-stories/references/story-schema.md +1 -0
- package/skills/yad-test-cases/SKILL.md +18 -2
- package/skills/yad-ui/SKILL.md +48 -8
- package/skills/yad-checks/templates/gitlab/.gitlab-ci.yml +0 -49
package/cli/doctor.mjs
CHANGED
|
@@ -3,6 +3,7 @@
|
|
|
3
3
|
// real repos), shape (what schemaVersion the files are on vs the engine), epics (each ledger loads),
|
|
4
4
|
// and threads (feature-thread lineage). Pure reporting: exit 1 on any FAIL, 0 with warnings.
|
|
5
5
|
// `--json` emits the checks for CI / bug reports.
|
|
6
|
+
import os from 'node:os';
|
|
6
7
|
import path from 'node:path';
|
|
7
8
|
import fs from 'node:fs';
|
|
8
9
|
import { c, log, ok, info, warn, fail, hand, run, has, exists, isPlainObject, readJSON, readJSONStrict, emitJSON, asArg, nodeSupport, nodeEndOfLife, NODE_FLOOR, NODE_SUPPORTED } from './lib.mjs';
|
|
@@ -18,7 +19,7 @@ import { judgeRepo, runnable, shown as forTerminal } from './workspace.mjs';
|
|
|
18
19
|
import { cliFor, hostFromGitUrl, ambiguousLegacyNames, plainHost, detectPlatform } from './platform.mjs';
|
|
19
20
|
import { legacyLogins, stampLegacyLogins } from './gate.mjs';
|
|
20
21
|
import { checkRepo } from './riskmap-command.mjs';
|
|
21
|
-
import { checkCodeowners, codeownersFindings } from './codeowners-command.mjs';
|
|
22
|
+
import { checkCodeowners, codeownersFindings, unguardedHint, unguardedWords } from './codeowners-command.mjs';
|
|
22
23
|
import { RISK_MAP_FILE } from './riskmap.mjs';
|
|
23
24
|
import { readProtection, protectionLine, protectionJSON, hideAddresses, repoPathFromGitUrl, shown } from './protection.mjs';
|
|
24
25
|
import { readTokenPlacement, tokenLine, readExpiringProductTokens, TOKEN_NAME } from './product-token.mjs';
|
|
@@ -30,6 +31,18 @@ import { readOwners } from './owners.mjs';
|
|
|
30
31
|
import { readMembers, judgedMemberFiles } from './members.mjs';
|
|
31
32
|
import { loadChoices, readToolboxFile } from './toolbox.mjs';
|
|
32
33
|
import { signingDoctorLine } from './signing.mjs';
|
|
34
|
+
import { nodePins, satisfies, nodeFix, dockerReasons, dockerState, glabConfigs } from './machine.mjs';
|
|
35
|
+
import { allStoryFrames, FRAMES_KEY } from './story-frames.mjs';
|
|
36
|
+
import { previewPattern, PREVIEW_KEY } from './preview.mjs';
|
|
37
|
+
|
|
38
|
+
// The design, testing and learning rows (E165 follow-up). The files are the team's, committed: `source` says
|
|
39
|
+
// what was found on the machine of whoever refreshed last, so a row says what was RECORDED, and the refresh
|
|
40
|
+
// checks this machine. A refresh with no `tool` checks the skill's default tool, not the team's, so every
|
|
41
|
+
// hint names it. The tool is one of DESIGN_TOOLS / TESTING_TOOLS / LEARNING_TOOLS by the time these run,
|
|
42
|
+
// each with a connect recipe; one that is installed but cannot be reached (signed out, its app closed)
|
|
43
|
+
// needs the person, not a connect step.
|
|
44
|
+
const connectThenRefresh = (skill, tool) => `if ${tool} is not on this machine, your agent can connect it: \`yad toolbox connect ${tool} --json\` (it asks you first); if it is, make sure it can be reached (signed in, its app open). Then run \`${skill}\` with \`action: refresh\` and \`tool: ${tool}\``;
|
|
45
|
+
const confirmByRefresh = (skill, tool) => `run \`${skill}\` with \`action: refresh\` and \`tool: ${tool}\` in your AI agent to check it on this machine`;
|
|
33
46
|
|
|
34
47
|
// A registered path doctor may run git in (E81): a checkout the judgement accepts — never a refused
|
|
35
48
|
// entry (git run in a folder the Product shaped as a repo reads its `config`, which can run a command),
|
|
@@ -110,6 +123,60 @@ export function signingChecks(checks, root) {
|
|
|
110
123
|
check(checks, 'signing', 'environment', line.status, line.message, line.hint, { alwaysHint: true });
|
|
111
124
|
}
|
|
112
125
|
|
|
126
|
+
// #352 — the machine setup local work depends on (cli/machine.mjs): the active Node against each repo's
|
|
127
|
+
// pinned version, Docker where a repo asks for it, and duplicate glab config files. The Product folder and
|
|
128
|
+
// every registered repo cloned here are read; the rest is not this machine's to judge.
|
|
129
|
+
export function machineChecks(checks, root, { nodeVersion = process.versions.node, env = process.env, home = os.homedir(), platform = process.platform, runner } = {}) {
|
|
130
|
+
const tilde = (p) => (p.startsWith(home + path.sep) ? `~${p.slice(home.length)}` : p);
|
|
131
|
+
const folders = [];
|
|
132
|
+
if (exists(productConfigPath(root))) folders.push({ name: 'the Product', dir: root, id: 'product' });
|
|
133
|
+
const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
|
|
134
|
+
for (const repo of Array.isArray(registry?.repos) ? registry.repos : []) {
|
|
135
|
+
if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
|
|
136
|
+
const dir = path.resolve(root, repo.path);
|
|
137
|
+
if (path.resolve(dir) === path.resolve(root) || !isCheckout(root, repo)) continue;
|
|
138
|
+
folders.push({ name: forTerminal(repo.name), dir, id: `repo:${forTerminal(repo.name)}` });
|
|
139
|
+
}
|
|
140
|
+
|
|
141
|
+
// Node: one warning per folder with the pins the running Node does not meet; one ok line when every pin
|
|
142
|
+
// read is met. A pin yad cannot read as a version is counted as skipped, never judged.
|
|
143
|
+
let read = 0;
|
|
144
|
+
let skipped = 0;
|
|
145
|
+
let wrong = 0;
|
|
146
|
+
for (const { name, dir, id } of folders) {
|
|
147
|
+
const unmet = [];
|
|
148
|
+
for (const { source, want } of nodePins(dir)) {
|
|
149
|
+
const meets = satisfies(nodeVersion, want);
|
|
150
|
+
if (meets === null) { skipped += 1; continue; }
|
|
151
|
+
read += 1;
|
|
152
|
+
if (!meets) unmet.push({ source, want });
|
|
153
|
+
}
|
|
154
|
+
if (!unmet.length) continue;
|
|
155
|
+
wrong += 1;
|
|
156
|
+
check(checks, `node-version:${id}`, 'environment', 'warn',
|
|
157
|
+
`node ${nodeVersion} does not meet what ${name} pins: ${unmet.map((u) => `${forTerminal(u.want)} (${u.source})`).join(', ')}`,
|
|
158
|
+
`${nodeFix(unmet[0].want, { env, home })} — the Node that runs yad is the active one (your version manager's default in a new shell)`);
|
|
159
|
+
}
|
|
160
|
+
if (read && !wrong) check(checks, 'node-version', 'environment', 'ok', `node ${nodeVersion} meets every Node version the repos pin (${read} read${skipped ? `, ${skipped} not a version yad reads` : ''})`);
|
|
161
|
+
|
|
162
|
+
// Docker: asked only where a repo names it.
|
|
163
|
+
const needs = folders.map((f) => ({ ...f, why: dockerReasons(f.dir) })).filter((f) => f.why.length);
|
|
164
|
+
if (needs.length) {
|
|
165
|
+
const who = needs.map((f) => `${f.name} (${f.why.join('; ')})`).join(', ');
|
|
166
|
+
const state = dockerState(runner ? { runner } : {});
|
|
167
|
+
if (state === 'running') check(checks, 'docker', 'environment', 'ok', `Docker is running, as ${who} needs`);
|
|
168
|
+
else check(checks, 'docker', 'environment', 'warn', state === 'missing' ? `Docker is not installed, and ${who} asks for it` : `Docker is not running, and ${who} asks for it`,
|
|
169
|
+
state === 'missing' ? 'install Docker (Docker Desktop, or the docker engine), start it, then run those local checks again' : 'start Docker (Docker Desktop, or the docker service), then run those local checks again — the CI runs them either way');
|
|
170
|
+
}
|
|
171
|
+
|
|
172
|
+
// glab: more than one config file.
|
|
173
|
+
const confs = glabConfigs({ env, home, platform });
|
|
174
|
+
if (confs.length > 1) {
|
|
175
|
+
check(checks, 'glab-config', 'environment', 'warn', `glab has ${confs.length} config files: ${confs.map((f) => forTerminal(tilde(f))).join(', ')}`,
|
|
176
|
+
'glab reads only one of them and ignores the other (a login saved there is not used), and warns about it on every run, which also breaks JSON for any tool that reads glab\'s output and errors together — keep the file glab\'s warning says it uses, copy into it any host it lacks from the other, then delete the other');
|
|
177
|
+
}
|
|
178
|
+
}
|
|
179
|
+
|
|
113
180
|
// `headCount` is a count of people the caller already read (E74); the CLI passes none, a test passes one.
|
|
114
181
|
export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
115
182
|
const productPath = productConfigPath(root);
|
|
@@ -410,8 +477,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
410
477
|
else if (design.tool === 'none') check(checks, 'design', 'project', 'ok', 'design: markdown-only');
|
|
411
478
|
else if (!DESIGN_TOOLS.includes(design.tool)) check(checks, 'design', 'project', 'fail', `${PROJECT_FILES.designConfig}: unknown or missing design tool '${design.tool}' [YAD-CFG-002]`, `expected one of ${DESIGN_TOOLS.join(', ')}, or none`);
|
|
412
479
|
else if (design.source && design.source !== 'unavailable') check(checks, 'design', 'project', 'ok', `design: ${design.tool} (${design.source})`);
|
|
413
|
-
else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool}
|
|
414
|
-
else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but
|
|
480
|
+
else if (design.source === 'unavailable') check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded as not found when last checked — yad-ui runs markdown-only`, connectThenRefresh('yad-connect-design', design.tool));
|
|
481
|
+
else check(checks, 'design', 'project', 'warn', `design: ${design.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-design', design.tool));
|
|
415
482
|
}
|
|
416
483
|
|
|
417
484
|
// testing.json: parse + shape + tool + MCP confirmation (absent is the normal artifacts-only default —
|
|
@@ -430,8 +497,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
430
497
|
else if (testing.tool === 'none') check(checks, 'testing', 'project', 'ok', 'testing: artifacts-only');
|
|
431
498
|
else if (!TESTING_TOOLS.includes(testing.tool)) check(checks, 'testing', 'project', 'fail', `${PROJECT_FILES.testingConfig}: unknown or missing testing tool '${testing.tool}' [YAD-CFG-003]`, `expected one of ${TESTING_TOOLS.join(', ')}, or none`);
|
|
432
499
|
else if (testing.source && testing.source !== 'unavailable') check(checks, 'testing', 'project', 'ok', `testing: ${testing.tool} (${testing.source})`);
|
|
433
|
-
else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool}
|
|
434
|
-
else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but
|
|
500
|
+
else if (testing.source === 'unavailable') check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded as not found when last checked — yad-test-cases runs artifacts-only`, connectThenRefresh('yad-connect-testing', testing.tool));
|
|
501
|
+
else check(checks, 'testing', 'project', 'warn', `testing: ${testing.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-testing', testing.tool));
|
|
435
502
|
}
|
|
436
503
|
|
|
437
504
|
// learning.json: parse + shape + tool + CLI confirmation (absent is the normal harness-native default —
|
|
@@ -451,8 +518,8 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
451
518
|
else if (learning.tool === 'none') check(checks, 'learning', 'project', 'ok', 'learning: harness-native');
|
|
452
519
|
else if (!LEARNING_TOOLS.includes(learning.tool)) check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown or missing learning tool '${learning.tool}' [YAD-CFG-004]`, `expected one of ${LEARNING_TOOLS.join(', ')}, or none`);
|
|
453
520
|
else if (learning.source === 'deeptutor-cli') check(checks, 'learning', 'project', 'ok', `learning: ${learning.tool} (${learning.source})`);
|
|
454
|
-
else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool}
|
|
455
|
-
else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but
|
|
521
|
+
else if (learning.source === 'harness-native') check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded as not found when last checked — yad-learn tutors harness-native`, connectThenRefresh('yad-connect-learning', learning.tool));
|
|
522
|
+
else if (learning.source == null) check(checks, 'learning', 'project', 'warn', `learning: ${learning.tool} recorded but not confirmed`, confirmByRefresh('yad-connect-learning', learning.tool));
|
|
456
523
|
else check(checks, 'learning', 'project', 'fail', `${PROJECT_FILES.learningConfig}: unknown source '${learning.source}' [YAD-STATE-002]`, 'expected deeptutor-cli, harness-native, or null');
|
|
457
524
|
}
|
|
458
525
|
|
|
@@ -513,6 +580,7 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
513
580
|
else check(checks, `repo:${repo.name}`, 'project', 'ok', `${nm}: git repo, context fresh`);
|
|
514
581
|
}
|
|
515
582
|
if (!registry.repos.length) check(checks, 'repos', 'project', 'warn', 'no code repos registered', 'run `yad setup` to connect one');
|
|
583
|
+
previewChecks(checks, repoEntries);
|
|
516
584
|
// Per-repo owners went with the roster (E62). Named only where a repo actually lists someone: every
|
|
517
585
|
// repo an older setup connected carries an EMPTY `domain_owner`, which says nothing.
|
|
518
586
|
const owned = repoEntries.filter((r) => (Array.isArray(r.domain_owners) && r.domain_owners.length) || (typeof r.domain_owner === 'string' && r.domain_owner));
|
|
@@ -597,12 +665,13 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
597
665
|
const blindGates = gateRoots.flatMap((x) => PRODUCT_PATH_GATES.map((rel) => ({ ...x, rel })))
|
|
598
666
|
.filter((x) => productRecordBlindGate(path.join(x.root, x.rel)))
|
|
599
667
|
.map((x) => `${x.rel} in ${x.where}`);
|
|
600
|
-
// A `#` line naming the script is prose, not a step that runs it (review 1).
|
|
668
|
+
// A `#` line naming the script is prose, not a step that runs it (review 1). Since #426 the shipped
|
|
669
|
+
// workflow runs the base branch's copy, `"$YAD_CHECKS/product-checkout.sh"`; an older one, `checks/…`.
|
|
601
670
|
const blindFlows = gateRoots.filter((x) => x.where !== 'the Product').flatMap((x) => CHECK_WORKFLOWS.map((rel) => ({ ...x, rel })))
|
|
602
671
|
.filter((x) => {
|
|
603
672
|
let src;
|
|
604
673
|
try { src = fs.readFileSync(path.join(x.root, x.rel), 'utf8'); } catch { return false; }
|
|
605
|
-
return !src.split('\n').some((l) => !/^\s*#/.test(l) && /
|
|
674
|
+
return !src.split('\n').some((l) => !/^\s*#/.test(l) && /(?:\bchecks|\$\{?YAD_CHECKS\}?)\/product-checkout\.sh/.test(l));
|
|
606
675
|
})
|
|
607
676
|
.map((x) => `${x.rel} in ${x.where}`);
|
|
608
677
|
const said = [
|
|
@@ -613,6 +682,17 @@ export function projectChecks(checks, root, { headCount = null } = {}) {
|
|
|
613
682
|
check(checks, 'checks:product-record-blind', 'project', 'warn', said.join('; '),
|
|
614
683
|
'run `yad check --fix` (it refreshes wired files nobody changed by hand); otherwise copy the shipped gate or workflow over it from skills/yad-checks/templates/');
|
|
615
684
|
}
|
|
685
|
+
// #425. A gate workflow that still starts on `edited`: its gate jobs skip that run, a skipped job counts as
|
|
686
|
+
// passed, and the newer run turns a failed gate green. The shipped copies no longer start on it; one the
|
|
687
|
+
// team changed by hand is kept by `yad update`, so name it.
|
|
688
|
+
const editRun = gateRoots.flatMap((x) => EDIT_RUN_WORKFLOWS.map((rel) => ({ ...x, rel })))
|
|
689
|
+
.filter((x) => editRunWorkflow(path.join(x.root, x.rel)))
|
|
690
|
+
.map((x) => `${x.rel} in ${x.where}`);
|
|
691
|
+
if (editRun.length) {
|
|
692
|
+
check(checks, 'checks:edit-run', 'project', 'warn',
|
|
693
|
+
`${editRun.join(', ')} ${editRun.length > 1 ? 'start' : 'starts'} on an edit of the PR text (\`edited\`) — the gate jobs skip that run, GitHub counts a skipped job as passed, so editing the title or description can turn a failed gate green`,
|
|
694
|
+
'run `yad update --overwrite-local` — it replaces every hand-edited managed file, keeping a `.yad-orig` copy of each; the PR-text checks now run from yad-pr-text.yml / yad-product-pr-text.yml. Or, by hand, remove `edited` from that file\'s `types:` and delete its `pr-title` and `pr-template` jobs: the PR-text file runs them now, and two runs under one check name let either decide');
|
|
695
|
+
}
|
|
616
696
|
// E120. A wired code repo (not the Product's own git repo) whose record is not COMMITTED: its gates
|
|
617
697
|
// fall back to link.md, and CI has nothing to check the Product out from. Committed, not on disk
|
|
618
698
|
// (review 1): the gates read it from the default branch, and one that setup wrote and nobody
|
|
@@ -1603,6 +1683,35 @@ export function themeChecks(checks, root) {
|
|
|
1603
1683
|
}
|
|
1604
1684
|
}
|
|
1605
1685
|
|
|
1686
|
+
// #354 — the design frames each story records (`design-frames: [id, …]`). The rule is `frameFindings` in
|
|
1687
|
+
// cli/story-frames.mjs, the same one `yad story frames` prints, and every finding is a warning there too,
|
|
1688
|
+
// so the two never disagree. No row at all when no story records frames: most Products have no design
|
|
1689
|
+
// tool, and a line saying so on every run would teach people to skip the section.
|
|
1690
|
+
export function storyFrameChecks(checks, root) {
|
|
1691
|
+
const epicsDir = path.join(root, 'epics');
|
|
1692
|
+
if (!exists(epicsDir)) return;
|
|
1693
|
+
const stories = allStoryFrames(root, epicIds(root).sort());
|
|
1694
|
+
if (!stories.length) return;
|
|
1695
|
+
const problems = stories.flatMap((s) => s.findings.map((f) => `${forTerminal(s.story)}: ${f.message}`));
|
|
1696
|
+
if (!problems.length) {
|
|
1697
|
+
const withFrames = stories.filter((s) => s.frames > 0).length;
|
|
1698
|
+
const noScreens = stories.length - withFrames;
|
|
1699
|
+
const parts = [
|
|
1700
|
+
...(withFrames ? [`${withFrames} story(ies) record design frames, and every frame ID is in its epic's design-links.json`] : []),
|
|
1701
|
+
...(noScreens ? [`${noScreens} story(ies) say they have no screens (\`${FRAMES_KEY}: []\`)`] : []),
|
|
1702
|
+
];
|
|
1703
|
+
check(checks, 'stories:design-frames', 'shape', 'ok', parts.join('; '));
|
|
1704
|
+
return;
|
|
1705
|
+
}
|
|
1706
|
+
const shownN = 3;
|
|
1707
|
+
const list = `${problems.slice(0, shownN).join('; ')}${problems.length > shownN ? ` (+${problems.length - shownN} more)` : ''}`;
|
|
1708
|
+
check(
|
|
1709
|
+
checks, 'stories:design-frames', 'shape', 'warn',
|
|
1710
|
+
`${problems.length} problem(s) with the design frames stories record: ${list}`,
|
|
1711
|
+
`run \`yad story frames <story>\` for one story's frames and findings, and rename a story file whose name is not \`<epic>-S<n>.md\` (the command cannot read it). Fixing \`${FRAMES_KEY}\` changes the story file, so a stories review that already passed must approve it again`,
|
|
1712
|
+
);
|
|
1713
|
+
}
|
|
1714
|
+
|
|
1606
1715
|
// A project's chain against the step catalogue (E4). `phaseChecks` below asks whether a step id is
|
|
1607
1716
|
// KNOWN; this asks whether a known step is set up the way the catalogue says it is.
|
|
1608
1717
|
//
|
|
@@ -2013,6 +2122,16 @@ export function productRecordBlindGate(file) {
|
|
|
2013
2122
|
try { src = fs.readFileSync(file, 'utf8'); } catch { return false; }
|
|
2014
2123
|
return productRecordBlindText(src);
|
|
2015
2124
|
}
|
|
2125
|
+
// #425. The GitHub gate workflows that must never start on `edited` (the Product's under the old name too).
|
|
2126
|
+
export const EDIT_RUN_WORKFLOWS = Object.freeze(['.github/workflows/yad-checks.yml', '.github/workflows/yad-product-checks.yml', '.github/workflows/yad-hub-checks.yml']);
|
|
2127
|
+
// `edited` in a `types:` list, inline or as a block item; a `#` comment is prose, not a trigger.
|
|
2128
|
+
export const editRunText = (src) => src.split('\n').map((l) => l.replace(/(^|\s)#.*$/, '')).some((l) =>
|
|
2129
|
+
/^\s*types:.*(?:^|[\s[,'"])edited(?:$|[\s\],'"])/.test(l) || /^\s*-\s*(['"]?)edited\1\s*$/.test(l));
|
|
2130
|
+
export function editRunWorkflow(file) {
|
|
2131
|
+
let src;
|
|
2132
|
+
try { src = fs.readFileSync(file, 'utf8'); } catch { return false; }
|
|
2133
|
+
return editRunText(src);
|
|
2134
|
+
}
|
|
2016
2135
|
// The checks workflows a connected repo may carry (one per platform).
|
|
2017
2136
|
export const CHECK_WORKFLOWS = ['.github/workflows/yad-checks.yml', '.gitlab/ci/yad-checks.yml'];
|
|
2018
2137
|
// E117: a Product-reading gate that does not read link.md from the base (`git show`) or a tracked Product
|
|
@@ -2489,20 +2608,31 @@ export function riskMapChecks(checks, root) {
|
|
|
2489
2608
|
// a guess, and it prints only in `yad codeowners check`, never here. Advisory — a warning, never a
|
|
2490
2609
|
// failure: CODEOWNERS is a hint (Part 3). No file at all is a note; a repo with no review rules at all is
|
|
2491
2610
|
// E70's to warn about. A repo not on disk, or not a git repo, is the repos check's to report.
|
|
2611
|
+
// #426: gate files (checks/, every CI file) with no owner whose review the platform can require are a warning
|
|
2612
|
+
// too, with or without a CODEOWNERS file — on each code repo and on the Product, which runs its own gates (once:
|
|
2613
|
+
// a Product registered as one of its own repos is not said twice). The hint gives the lines.
|
|
2492
2614
|
export function codeownersChecks(checks, root) {
|
|
2493
2615
|
const registry = readJSON(path.join(root, PROJECT_FILES.reposRegistry), { repos: [] });
|
|
2494
2616
|
const repos = Array.isArray(registry?.repos) ? registry.repos : [];
|
|
2617
|
+
const real = (d) => { try { return fs.realpathSync.native(d); } catch { return d; } };
|
|
2618
|
+
const seen = new Set();
|
|
2619
|
+
const can = { github: 'GitHub', gitlab: 'GitLab' };
|
|
2495
2620
|
for (const repo of repos) {
|
|
2496
2621
|
if (!repo || typeof repo.name !== 'string' || typeof repo.path !== 'string' || !repo.path) continue;
|
|
2497
2622
|
const repoRoot = path.resolve(root, repo.path);
|
|
2498
2623
|
if (!isCheckout(root, repo) || !gitHead(repoRoot)) continue;
|
|
2624
|
+
seen.add(real(repoRoot));
|
|
2499
2625
|
const r = checkCodeowners(repoRoot, { platform: repo.platform || null });
|
|
2500
2626
|
if (!r.git) continue;
|
|
2501
2627
|
const id = `codeowners:${repo.name}`;
|
|
2502
2628
|
const nm = forTerminal(repo.name); // printed as in riskMapChecks (E81 review 11)
|
|
2503
2629
|
const more = `\`yad codeowners check ${asArg(repo.name)}\``;
|
|
2504
2630
|
if (r.unknown) { check(checks, id, 'codeowners', 'warn', `${nm}: CODEOWNERS could not be checked — ${forTerminal(r.unknown)}`, more); continue; }
|
|
2505
|
-
if (r.none) { check(checks, id, 'codeowners', 'ok', `${nm}: no CODEOWNERS — nothing to check`); continue; }
|
|
2631
|
+
if (r.none && !r.unguarded) { check(checks, id, 'codeowners', 'ok', `${nm}: no CODEOWNERS — nothing to check`); continue; }
|
|
2632
|
+
if (r.none) {
|
|
2633
|
+
check(checks, id, 'codeowners', 'warn', `${nm}: no CODEOWNERS, so ${unguardedWords(r.unguarded)} have no code owner`, unguardedHint(r.platform, r.unguarded), { findings: codeownersFindings(r) });
|
|
2634
|
+
continue;
|
|
2635
|
+
}
|
|
2506
2636
|
const findings = codeownersFindings(r);
|
|
2507
2637
|
if (!findings.length) { check(checks, id, 'codeowners', 'ok', `${nm}: every ${r.path} line yad can read matches a file`); continue; }
|
|
2508
2638
|
const lines = (code) => findings.filter((f) => f.code === code).map((f) => f.line);
|
|
@@ -2514,10 +2644,27 @@ export function codeownersChecks(checks, root) {
|
|
|
2514
2644
|
if (dead.length) said.push(`in ${r.path}, ${dead.length === 1 ? '1 line matches' : `${dead.length} lines match`} no file (line${dead.length === 1 ? '' : 's'} ${listed(dead)})`);
|
|
2515
2645
|
const unread = lines('not-read');
|
|
2516
2646
|
if (unread.length) said.push(`in ${r.path}, ${unread.length === 1 ? '1 line' : `${unread.length} lines`} yad could not read (line${unread.length === 1 ? '' : 's'} ${listed(unread)})`);
|
|
2517
|
-
|
|
2518
|
-
|
|
2647
|
+
const stale = said.length ? [`${nm}: CODEOWNERS may be out of date — ${said.join('; ')}`] : [];
|
|
2648
|
+
const gates = r.unguarded ? [`${stale.length ? '' : `${nm}: `}no line in ${r.path} that yad can read gives ${unguardedWords(r.unguarded)} an owner whose review ${can[r.platform] || 'the platform'} can require`] : [];
|
|
2649
|
+
check(checks, id, 'codeowners', 'warn', [...stale, ...gates].join('; '),
|
|
2650
|
+
[...(stale.length ? [`${more} lists each one; fix it in ${nm} through a PR (advisory — CODEOWNERS is a hint, and yad never enforces it)`] : []),
|
|
2651
|
+
...(r.unguarded ? [unguardedHint(r.platform, r.unguarded)] : [])].join('; '),
|
|
2519
2652
|
{ findings });
|
|
2520
2653
|
}
|
|
2654
|
+
// The Product's own gates (#426). Only the gate-file finding: the stale-line facts above are for code repos.
|
|
2655
|
+
const productConfig = readJSON(productConfigPath(root), null);
|
|
2656
|
+
if (!isPlainObject(productConfig) || !gitHead(root) || seen.has(real(root))) return;
|
|
2657
|
+
const platform = ['github', 'gitlab'].includes(productConfig.platform) ? productConfig.platform : null;
|
|
2658
|
+
const p = checkCodeowners(root, { platform });
|
|
2659
|
+
if (!p.git || p.unknown || p.tooBig || !p.platform) return;
|
|
2660
|
+
if (!p.unguarded) {
|
|
2661
|
+
// No CODEOWNERS and nothing unguarded means no gate files at all: nothing to say.
|
|
2662
|
+
if (!p.none && fs.existsSync(path.join(root, 'checks'))) check(checks, 'codeowners:(the Product)', 'codeowners', 'ok', `the Product: checks/ and the CI files have a code owner in ${p.path}`);
|
|
2663
|
+
return;
|
|
2664
|
+
}
|
|
2665
|
+
check(checks, 'codeowners:(the Product)', 'codeowners', 'warn',
|
|
2666
|
+
`the Product: ${p.none ? 'no CODEOWNERS, so ' : `no line in ${p.path} that yad can read gives `}${unguardedWords(p.unguarded)}${p.none ? ' have no code owner' : ` an owner whose review ${can[p.platform] || 'the platform'} can require`}`,
|
|
2667
|
+
unguardedHint(p.platform, p.unguarded), { findings: codeownersFindings(p).filter((f) => f.code === 'unguarded') });
|
|
2521
2668
|
}
|
|
2522
2669
|
|
|
2523
2670
|
// E70 — what the platform holds on the Product's branch and on each connected repo's: branch
|
|
@@ -2718,6 +2865,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
|
|
|
2718
2865
|
const checks = [];
|
|
2719
2866
|
envChecks(checks);
|
|
2720
2867
|
signingChecks(checks, root);
|
|
2868
|
+
machineChecks(checks, root);
|
|
2721
2869
|
projectChecks(checks, root, { headCount });
|
|
2722
2870
|
riskMapChecks(checks, root);
|
|
2723
2871
|
codeownersChecks(checks, root);
|
|
@@ -2732,6 +2880,7 @@ export function collectDoctor(root, { headCount = null } = {}) {
|
|
|
2732
2880
|
legacyModuleChecks(checks, root);
|
|
2733
2881
|
typeChecks(checks, root);
|
|
2734
2882
|
themeChecks(checks, root);
|
|
2883
|
+
storyFrameChecks(checks, root);
|
|
2735
2884
|
catalogueChecks(checks, root);
|
|
2736
2885
|
profileChecks(checks, root);
|
|
2737
2886
|
skipChecks(checks, root);
|
|
@@ -2979,3 +3128,18 @@ function gitHookCheck(root, checks) {
|
|
|
2979
3128
|
check(checks, 'git-hook', 'project', 'ok', `git pre-commit ledger guard installed in this clone (${where})`);
|
|
2980
3129
|
}
|
|
2981
3130
|
}
|
|
3131
|
+
|
|
3132
|
+
// The preview address patterns (#359), by the same rule `yad repo preview` writes with. Said only when
|
|
3133
|
+
// some repo records one: a repo with no pattern is the normal case, and its review says "locally only".
|
|
3134
|
+
export function previewChecks(checks, repoEntries) {
|
|
3135
|
+
const withPreview = repoEntries.filter((r) => PREVIEW_KEY in r && r[PREVIEW_KEY] != null);
|
|
3136
|
+
if (!withPreview.length) return;
|
|
3137
|
+
const bad = withPreview.map((r) => ({ r, problems: previewPattern(r).problems })).filter((x) => x.problems);
|
|
3138
|
+
if (bad.length) {
|
|
3139
|
+
check(checks, 'repos:preview', 'project', 'warn',
|
|
3140
|
+
`${bad.length} preview address pattern${bad.length > 1 ? 's' : ''} in ${PROJECT_FILES.reposRegistry} cannot be used: ${bad.map((x) => `${forTerminal(x.r.name || '(unnamed)')}: it ${x.problems.join('; ')}`).join(', ')}`,
|
|
3141
|
+
`set ${bad.length > 1 ? 'each' : 'it'} again with \`yad repo preview ${bad.length === 1 ? asArg(bad[0].r.name) : '<name>'} <pattern>\` (or --clear) — until then its review checks the page locally only`);
|
|
3142
|
+
} else {
|
|
3143
|
+
check(checks, 'repos:preview', 'project', 'ok', `${withPreview.length} repo${withPreview.length > 1 ? 's record' : ' records'} a preview address pattern`);
|
|
3144
|
+
}
|
|
3145
|
+
}
|
package/cli/epic-state.mjs
CHANGED
|
@@ -440,6 +440,8 @@ export function artifactFromBase(base) {
|
|
|
440
440
|
// The files (relative to the epic dir) a review of this artifact covers — what `gate open` commits
|
|
441
441
|
// on the review branch (the owner's artifact), and what CI re-reads to bind the approval at merge.
|
|
442
442
|
// Architecture mirrors artifactHash(): the approval is bound to the locked contract surface too.
|
|
443
|
+
// E164: the folder beside ui-design.md that holds the epic's design file.
|
|
444
|
+
export const UI_DESIGN_DIR = 'design';
|
|
443
445
|
export function artifactPaths(base) {
|
|
444
446
|
if (base === 'architecture') return ['architecture.md', 'contract.md', '.sdlc/contract-lock.json'];
|
|
445
447
|
if (base === 'stories') return ['stories'];
|
|
@@ -447,6 +449,10 @@ export function artifactPaths(base) {
|
|
|
447
449
|
// Every section, optional ones included: this names what a Foundation review COVERS, and a section
|
|
448
450
|
// that is absent today is still one a reviewer may be asked to look at tomorrow.
|
|
449
451
|
if (base === 'foundation') return [...FOUNDATION_FILES];
|
|
452
|
+
// E164: the UI step's design file lives in the epic's `design/` folder (an OpenPencil file in the repo),
|
|
453
|
+
// so the UI review covers it: `yad fold` commits it, and a change to it after approval needs a fresh
|
|
454
|
+
// review. A folder, so `fold` and `artifactHashAt` take everything under it.
|
|
455
|
+
if (base === 'ui-design') return ['ui-design.md', UI_DESIGN_DIR];
|
|
450
456
|
return [`${base}.md`];
|
|
451
457
|
}
|
|
452
458
|
|
|
@@ -595,6 +601,85 @@ export function storiesHash(epicDir, sha = reviewedSha) {
|
|
|
595
601
|
return 'sha256:' + createHash('sha256').update(parts.join('\n')).digest('hex');
|
|
596
602
|
}
|
|
597
603
|
|
|
604
|
+
// E164: the UI design's fingerprint. With no file under `design/`, it is the fingerprint of ui-design.md
|
|
605
|
+
// alone — byte for byte what every release before E164 recorded, so no approval of a Figma or Pencil
|
|
606
|
+
// design moves. With design files, it covers them too: ui-design.md as reviewed (`sha`), then each design
|
|
607
|
+
// file (`designSha`, never with a status line left out), sorted by path.
|
|
608
|
+
//
|
|
609
|
+
// Which files count is decided here, and the copy `artifactHashAt` makes of a commit is read by the same
|
|
610
|
+
// walk, so the disk and the approved commit agree:
|
|
611
|
+
// - regular files only (a link is skipped; so is a `design` folder that is itself a link — a commit
|
|
612
|
+
// holds it as a link, not a folder);
|
|
613
|
+
// - never a file the system or an editor drops beside a design (`isDesignJunk`: `.DS_Store`, macOS's
|
|
614
|
+
// `._<name>` copies, a `.~lock.<name>#` lock file, a name ending in `~`, `Thumbs.db`, `desktop.ini`)
|
|
615
|
+
// — git often does not ignore those, and counting one would make every approval look changed on that
|
|
616
|
+
// machine only. Any other name, a dot-name included, is a design file;
|
|
617
|
+
// - never inside a folder holding `.git` (a submodule or a nested repository: a commit holds it as one
|
|
618
|
+
// entry, not its files).
|
|
619
|
+
const DESIGN_JUNK = /^(?:\.ds_store|\._.*|\.~lock\..*|.*~|thumbs\.db|desktop\.ini)$/i;
|
|
620
|
+
export const isDesignJunk = (rel) => rel.split('/').some((seg) => DESIGN_JUNK.test(seg));
|
|
621
|
+
function designFiles(dir, rel = '') {
|
|
622
|
+
if (rel === '') {
|
|
623
|
+
try { if (!fs.lstatSync(dir).isDirectory()) return []; } catch { return []; }
|
|
624
|
+
}
|
|
625
|
+
let entries;
|
|
626
|
+
try { entries = fs.readdirSync(path.join(dir, rel), { withFileTypes: true }); } catch { return []; }
|
|
627
|
+
if (entries.some((e) => e.name === '.git')) return [];
|
|
628
|
+
const out = [];
|
|
629
|
+
for (const e of entries) {
|
|
630
|
+
if (DESIGN_JUNK.test(e.name)) continue;
|
|
631
|
+
const r = rel ? `${rel}/${e.name}` : e.name;
|
|
632
|
+
if (e.isDirectory()) out.push(...designFiles(dir, r));
|
|
633
|
+
else if (e.isFile()) out.push(r);
|
|
634
|
+
}
|
|
635
|
+
return out;
|
|
636
|
+
}
|
|
637
|
+
// One design file's fingerprint: the SHA-256 of its content. A Git LFS pointer (the small text file a
|
|
638
|
+
// checkout without LFS leaves in place of a large file) names that same SHA-256 as its `oid`, so the
|
|
639
|
+
// pointer and the real file give one fingerprint — CI checks out pointers, `artifactHashAt` may read
|
|
640
|
+
// the real file through the LFS filter, and the two must agree.
|
|
641
|
+
// Only the exact pointer format git-lfs writes counts — its version line, any `ext-` lines, the oid, the
|
|
642
|
+
// size and nothing else — so no other text can ride in a file whose fingerprint is its oid alone.
|
|
643
|
+
const LFS_POINTER = /^version https:\/\/git-lfs\.github\.com\/spec\/v1\r?\n(?:ext-[^\r\n]*\r?\n)*oid sha256:([0-9a-f]{64})\r?\nsize \d+\r?\n?$/;
|
|
644
|
+
function designSha(p) {
|
|
645
|
+
const bytes = fs.readFileSync(p);
|
|
646
|
+
if (bytes.length < 1024) {
|
|
647
|
+
const oid = bytes.toString('utf8').match(LFS_POINTER);
|
|
648
|
+
if (oid) return `sha256:${oid[1]}`;
|
|
649
|
+
}
|
|
650
|
+
return shaOf(bytes);
|
|
651
|
+
}
|
|
652
|
+
// The files under `design/` that git ignores here (an exports folder in .gitignore, an editor's settings
|
|
653
|
+
// folder): no commit holds them, so counting them would make the approval look changed on this machine
|
|
654
|
+
// only. Never asked for the scratch copy `artifactHashAt` makes (`askGit: false`): it holds only committed
|
|
655
|
+
// files, and a temporary folder inside some checkout would be judged by that checkout's rules. A tracked
|
|
656
|
+
// file is never reported, even when a pattern matches it. The variables that point git at another
|
|
657
|
+
// repository (set inside a git hook, or by a script) are dropped, so git finds the Product's checkout from
|
|
658
|
+
// the folder itself — the same list hook.mjs drops. Names are compared in one Unicode form, because git
|
|
659
|
+
// on macOS may print a name precomposed that it was given decomposed.
|
|
660
|
+
const REPO_ENV = /^GIT_(DIR|WORK_TREE|PREFIX|INDEX_FILE|COMMON_DIR|OBJECT_DIRECTORY|ALTERNATE_OBJECT_DIRECTORIES)$/;
|
|
661
|
+
function ignoredByGit(dir, files) {
|
|
662
|
+
if (!files.length) return new Set();
|
|
663
|
+
const env = { ...Object.fromEntries(Object.entries(process.env).filter(([k]) => !REPO_ENV.test(k))), GIT_OPTIONAL_LOCKS: '0' };
|
|
664
|
+
const r = spawnSync('git', ['check-ignore', '-z', '--stdin'], { cwd: dir, input: files.map((f) => `${f}\0`).join(''), env, maxBuffer: 64 * 1024 * 1024 });
|
|
665
|
+
return r.status === 0 ? new Set(r.stdout.toString('utf8').split('\0').filter(Boolean).map((f) => f.normalize('NFC'))) : new Set();
|
|
666
|
+
}
|
|
667
|
+
// The design files' part of the fingerprint, read once: `acceptedHashes` combines it with each form of
|
|
668
|
+
// ui-design.md, so a large design file is not read again for every form.
|
|
669
|
+
function designParts(epicDir, { askGit = true } = {}) {
|
|
670
|
+
const dir = path.join(epicDir, UI_DESIGN_DIR);
|
|
671
|
+
const all = designFiles(dir);
|
|
672
|
+
const ignored = askGit ? ignoredByGit(dir, all) : new Set();
|
|
673
|
+
return all.filter((f) => !ignored.has(f.normalize('NFC'))).sort().map((f) => `${UI_DESIGN_DIR}/${f}:${designSha(path.join(dir, ...f.split('/')))}`);
|
|
674
|
+
}
|
|
675
|
+
export function uiDesignHash(epicDir, sha = reviewedSha, parts = null, { askGit = true } = {}) {
|
|
676
|
+
const doc = sha(path.join(epicDir, 'ui-design.md'));
|
|
677
|
+
if (doc === null) return null;
|
|
678
|
+
parts ??= designParts(epicDir, { askGit });
|
|
679
|
+
if (!parts.length) return doc;
|
|
680
|
+
return 'sha256:' + createHash('sha256').update([`ui-design.md:${doc}`, ...parts].join('\n')).digest('hex');
|
|
681
|
+
}
|
|
682
|
+
|
|
598
683
|
// The reserved id of the Product level in its OLD spelling ("epic zero", `epics/EP-discovery/`), written
|
|
599
684
|
// by every release before E75 and still read. yad-epic / yad-analysis must never pick this slug — or
|
|
600
685
|
// `EP-foundation` — for a feature.
|
|
@@ -940,12 +1025,14 @@ export function discoveryHash(epicDir, sha = reviewedSha) {
|
|
|
940
1025
|
// the whole discovery file set; for every other artifact it is the file. Every file is fingerprinted
|
|
941
1026
|
// without its frontmatter `status:` line (see `reviewedSha`). `sha` swaps that for a legacy form —
|
|
942
1027
|
// only `acceptedHashes` passes one.
|
|
943
|
-
|
|
1028
|
+
// `askGit: false` is for a scratch copy of a commit (`artifactHashAt`): see `ignoredByGit`.
|
|
1029
|
+
export function artifactHash(epicDir, artifact, sha = reviewedSha, { askGit = true } = {}) {
|
|
944
1030
|
const b = artifactBase(artifact);
|
|
945
1031
|
if (b === 'architecture') return contractSurfaceHash(epicDir);
|
|
946
1032
|
if (b === 'stories') return storiesHash(epicDir, sha);
|
|
947
1033
|
if (b === 'discovery') return discoveryHash(epicDir, sha);
|
|
948
1034
|
if (b === 'foundation') return foundationHash(epicDir, FOUNDATION_SECTIONS, sha);
|
|
1035
|
+
if (b === 'ui-design') return uiDesignHash(epicDir, sha, null, { askGit });
|
|
949
1036
|
return sha(path.join(epicDir, artifact.replace(/\/$/, '')));
|
|
950
1037
|
}
|
|
951
1038
|
|
|
@@ -953,9 +1040,12 @@ export function artifactHash(epicDir, artifact, sha = reviewedSha) {
|
|
|
953
1040
|
// legacy forms (see LEGACY_FORMS). Empty when there is nothing to fingerprint — the same "no claim"
|
|
954
1041
|
// answer a null `artifactHash` gives. What is WRITTEN is always `artifactHash`; this is for reading.
|
|
955
1042
|
export function acceptedHashes(epicDir, artifact) {
|
|
956
|
-
|
|
1043
|
+
// The UI design's files are read once and combined with each form of ui-design.md (E164).
|
|
1044
|
+
const parts = artifactBase(artifact) === 'ui-design' ? designParts(epicDir) : null;
|
|
1045
|
+
const hashWith = parts ? (sha) => uiDesignHash(epicDir, sha, parts) : (sha) => artifactHash(epicDir, artifact, sha);
|
|
1046
|
+
const current = hashWith(reviewedSha);
|
|
957
1047
|
if (current === null) return [];
|
|
958
|
-
return [...new Set([current, ...LEGACY_FORMS.map(
|
|
1048
|
+
return [...new Set([current, ...LEGACY_FORMS.map(hashWith)].filter(Boolean))];
|
|
959
1049
|
}
|
|
960
1050
|
|
|
961
1051
|
// Is a recorded fingerprint stale against the accepted ones? Never when nothing was recorded (a manual
|
|
@@ -1017,7 +1107,7 @@ export function artifactHashAt(root, epicDir, artifact, rev) {
|
|
|
1017
1107
|
copied++;
|
|
1018
1108
|
}
|
|
1019
1109
|
} catch (e) { return { ok: false, reason: `the files at ${rev.slice(0, 12)} could not be copied (${e.code || e.message})` }; }
|
|
1020
|
-
return { ok: true, hash: artifactHash(dir, artifact), copied };
|
|
1110
|
+
return { ok: true, hash: artifactHash(dir, artifact, reviewedSha, { askGit: false }), copied };
|
|
1021
1111
|
} finally {
|
|
1022
1112
|
fs.rmSync(tmp, { recursive: true, force: true });
|
|
1023
1113
|
}
|
package/cli/epic.mjs
CHANGED
|
@@ -51,11 +51,15 @@ export function epicIdFrom(slug) {
|
|
|
51
51
|
|
|
52
52
|
// `type` defaults to null rather than `feature` so an explicit `--type` is distinguishable from no
|
|
53
53
|
// 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 } = {}) {
|
|
54
|
+
export async function runEpicNew(root, { slug, type = null, profile = null, stub = false, parent = null, inherits = null, today, json = false, returnResult = false } = {}) {
|
|
55
|
+
// `returnResult` (E170, with json): a caller that seeds as one part of its work gets the answer back, and
|
|
56
|
+
// it alone speaks, so stdout stays one JSON document.
|
|
57
|
+
const answer = returnResult ? (payload) => payload : emitJSON;
|
|
55
58
|
const bail = (message, hint) => {
|
|
56
|
-
if (json) emitJSON({ ok: false, error: message, hint });
|
|
57
|
-
else { fail(message); if (hint) hand(hint); }
|
|
58
59
|
process.exitCode = 1;
|
|
60
|
+
if (json) return answer({ ok: false, error: message, hint });
|
|
61
|
+
fail(message); if (hint) hand(hint);
|
|
62
|
+
return undefined;
|
|
59
63
|
};
|
|
60
64
|
|
|
61
65
|
const epic = epicIdFrom(slug);
|
|
@@ -169,7 +173,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
|
|
|
169
173
|
if (parent) {
|
|
170
174
|
return seedThreaded(root, {
|
|
171
175
|
epic, dir, files, mdPath, fm, type, parent, profile,
|
|
172
|
-
inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail,
|
|
176
|
+
inherits: flagInherits ?? declaredInherits ?? [], headerLists: declaredInherits !== null, today, json, bail, answer,
|
|
173
177
|
});
|
|
174
178
|
}
|
|
175
179
|
profile = profile || 'classic';
|
|
@@ -230,7 +234,7 @@ export async function runEpicNew(root, { slug, type = null, profile = null, stub
|
|
|
230
234
|
// `nextSkills` appears only for a bound chain, the same rule `yad next --json` follows — a key that
|
|
231
235
|
// showed up on every seed would be one more always-null field for every reader to ignore.
|
|
232
236
|
if (json) {
|
|
233
|
-
return
|
|
237
|
+
return answer({
|
|
234
238
|
ok: true, epic, type, profile, stub, currentStep: state.currentStep,
|
|
235
239
|
steps: state.steps.map((s) => s.id), next: skill,
|
|
236
240
|
...(skills.length > 1 ? { nextSkills: skills } : {}),
|
|
@@ -266,7 +270,7 @@ const listOf = (v) => (Array.isArray(v) ? v : String(v ?? '').replace(/^\s*\[|\]
|
|
|
266
270
|
// The threaded half of `yad epic new` (E42): a change, defect or hotfix off an epic that exists. The
|
|
267
271
|
// engine plans the chain from the parent (`planThreadedSeed`) and this writes it — the ledger, one
|
|
268
272
|
// 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 }) {
|
|
273
|
+
function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profile, inherits, headerLists, today, json, bail, answer }) {
|
|
270
274
|
const plan = planThreadedSeed(root, { epic, parent, inherits, type, today });
|
|
271
275
|
if (!plan.ok) return bail(plan.message, plan.hint);
|
|
272
276
|
// The route is the parent's. A flag naming the same one is harmless; a different one is refused
|
|
@@ -319,7 +323,7 @@ function seedThreaded(root, { epic, dir, files, mdPath, fm, type, parent, profil
|
|
|
319
323
|
const skills = stepSkills(first.id, bindingsForEpic(loadSkillBindings(root), state));
|
|
320
324
|
const carried = state.steps.filter((s) => s.inherited);
|
|
321
325
|
if (json) {
|
|
322
|
-
return
|
|
326
|
+
return answer({
|
|
323
327
|
ok: true, epic, type, profile: plan.profile, stub: false, parent, thread: plan.thread,
|
|
324
328
|
inherits, inheritedFrom: plan.owners, pointerLock: plan.lock ? plan.lock.ref : null, anchor: plan.anchor,
|
|
325
329
|
currentStep: state.currentStep, steps: state.steps.map((s) => s.id), next: skills[0] || null,
|
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
|
package/cli/guide.mjs
CHANGED
|
@@ -32,6 +32,7 @@ import { RULES, HUMAN_ONLY_ACTS, NEVER, classify, askFor, reaches } from './agen
|
|
|
32
32
|
import { seededSlugs } from './hook.mjs';
|
|
33
33
|
import { setupQuestions } from './setup.mjs';
|
|
34
34
|
import { reposBeside, insideGitRepo, PRODUCT_DIR } from './workspace.mjs';
|
|
35
|
+
import { PREAPPROVED } from './agent-guard.mjs';
|
|
35
36
|
|
|
36
37
|
export const GUIDE_VERSION = 1;
|
|
37
38
|
|
|
@@ -422,7 +423,8 @@ const thenFor = (person, epic) => (person.some((p) => p.verify)
|
|
|
422
423
|
// Build the guide. `root` is the Product, or null when there is none here. `cwd` is where the agent is.
|
|
423
424
|
// `productElsewhere`: no Product here, but one is a `cd` away (bin/yad.mjs finds it).
|
|
424
425
|
export function buildGuide(root, { epic = null, cwd = root ?? process.cwd(), runner, productElsewhere = null } = {}) {
|
|
425
|
-
|
|
426
|
+
// `preapproved` (E167): what the agent guard lets run with no permission prompt, and what it never does.
|
|
427
|
+
const base = { guideVersion: GUIDE_VERSION, rules: RULES, humanOnly: HUMAN_ONLY_ACTS, never: NEVER, preapproved: PREAPPROVED };
|
|
426
428
|
if (!root && productElsewhere) {
|
|
427
429
|
const where = clean(productElsewhere);
|
|
428
430
|
const q = shellPath(where);
|