@futurelastic/colab-handbook 1.22.1-rc.1 → 1.22.1-rc.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/package.json +1 -1
- package/templates/README.md +3 -2
- package/templates/dist-refs.yml +51 -2
- package/templates/docs-README.md +39 -0
- package/templates/docs-lint.mjs +263 -0
- package/templates/release-tag.yml +27 -2
- package/tools/lib/template-trunk.js +3 -1
package/package.json
CHANGED
package/templates/README.md
CHANGED
|
@@ -95,7 +95,7 @@ header naming its new home ([`docs/compat-surfaces.md`](../docs/compat-surfaces.
|
|
|
95
95
|
| `pre-commit-dispatch`, `pre-commit-identity`, `identity-vocabulary.example` | git (this repo's own `.githooks/` run them in place) | stays here, as an optional starting file |
|
|
96
96
|
| `pre-commit-instruction-files`, `instruction-files.yml` | `colab instruction-files`; the reusable workflow in this repo | the `colab instruction-files` command; the reusable workflow is the one remote call this folder keeps, for compatibility |
|
|
97
97
|
| `docs-lint.mjs`, `docs-lint.yml`, `branch-name.yml` | your CI (advisory or opt-in); `code-wrap`'s docs step | stays here, as an optional starting file |
|
|
98
|
-
| `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
|
|
98
|
+
| `repo-CLAUDE-block.md`, `gotchas-d-README.md`, `adr-README.md`, `docs-README.md` | nothing — text you paste or copy (`colab adopt` pastes the block) | stays here |
|
|
99
99
|
|
|
100
100
|
Nothing in this table changes what a copied file does. A stamp, a drift report or a `colab`
|
|
101
101
|
check that reads one of these files is that tool's behaviour, documented with the tool.
|
|
@@ -124,7 +124,8 @@ check that reads one of these files is that tool's behaviour, documented with th
|
|
|
124
124
|
| `repo-CLAUDE-block.md` | *paste into* `CLAUDE.md` | Every adopting repo | The discovery hook — how an agent finds the handbook at all. |
|
|
125
125
|
| `gotchas-d-README.md` | `docs/gotchas.d/README.md` | Any repo starting a `docs/gotchas.d/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Naming rule (`<issue>-<slug>.md`) and the don't-copy-back rule against an existing `docs/gotchas.md`. Optional — writing the first gotcha entry does not require copying this in first. |
|
|
126
126
|
| `adr-README.md` | `docs/adr/README.md` | Any repo starting a `docs/adr/` directory ([`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 step) | Same issue-keyed naming rule as `gotchas-d-README.md`, applied to architecture decision records instead of gotchas — an existing sequentially-numbered `docs/adr/` is left as-is; only new decisions use `<issue>-<slug>.md`. Optional, same as above. |
|
|
127
|
-
| `docs-
|
|
127
|
+
| `docs-README.md` | `docs/README.md` | Any repo whose `docs/` has three or more root entries and no index (`handbook-sync` offers it at adoption; [`code-wrap`](../skills/code-wrap/SKILL.md)'s A2 *`docs/` layout*, #686) | The index: one line per root entry, the `merge=union` line for `.gitattributes`, the reserved root names and the layout in brief. Delete the example lines you do not have yet. Optional — a repo may write its index by hand. |
|
|
128
|
+
| `docs-lint.mjs` | anywhere in-repo (e.g. `tools/docs-lint.mjs`) | Every repo — checks the STRUCTURE of the doc graph (router integrity, orphans, drafts-in-`docs/`, router size budget, dated files, §-citation resolution, `gotchas.d/` registry discipline, two-surface linkage) and, as WARN only, the `docs/` layout (#686: the index, plan/report and dated names, non-kebab names, design artifacts outside `design/<slug>-<N>/`, images over 1 MB, fonts outside `design/_assets/`) | Zero-dependency, plain Node — but it does **shell out to `git check-ignore`** once per enumeration, so that a git-ignored scratch file (your `.plans/` plan file, say) can never fail a structural check on your repo (#310). No git, or no repo, and it filters nothing and lints exactly as before. **Enumerated by `colab template` and DOES take an automatic version stamp** (colab-handbook #252): `colab template docs-lint.mjs --dest tools/docs-lint.mjs` copies it stamped on its **second** line (`// colab-handbook: docs-lint @ <version>`, after the `#!/usr/bin/env node` shebang — a bare `#` on any other line is a JS syntax error, unlike the YAML templates above) — `--dest` is required, since this file has no formulaic destination the way a workflow does. Pairs with `docs-lint.yml`. Also runs from `code-wrap`'s docs step and a weekly fleet sweep (colab-handbook #249) — this row is the third of its three seats. |
|
|
128
129
|
| `docs-lint.yml` | `.github/workflows/docs-lint.yml` | Every repo that copied `docs-lint.mjs` | Advisory job — `continue-on-error: true` on the lint step, so a finding never blocks a merge until a repo deliberately removes that line. Requires `docs-lint.mjs` to already be in the repo; does not vendor it. |
|
|
129
130
|
| `instruction-files.yml` | `.github/workflows/instruction-files.yml` | Every repo with a `CLAUDE.md` (#588) | **A caller, not a copy:** its one job `uses:` the handbook's reusable `.github/workflows/instruction-files.yml`, so the judgement is maintained once and works from any org. Fails when a `CLAUDE.md` carries repo prose instead of `@AGENTS.md` + tool blocks — **ratcheted**: only when the change touches `CLAUDE.md`/`AGENTS.md`, or the repo had already migrated. An unmigrated repo stays green until it edits those files. Pin `@<tag>` plus `with: handbook-ref: <tag>` to freeze the checker. No GitHub-hosted minutes (self-hosted-only org)? `with: runs-on: <label>` or a JSON list `'["self-hosted","linux"]'` (#594) — any Linux runner with git; the job sets up its own Node. |
|
|
130
131
|
| `branch-name.yml` | `.github/workflows/branch-name.yml` | Opt-in — any repo that wants §4's branch shape checked on every PR | One step, no dependencies: the PR's head branch against CONVENTIONS.md §4's regex, both shapes (`<type>/<slug>-<N>` and the `<login>/<machine>/` prefixed one) passing as shipped. Once the repo declares `branchPrefix: machine`, delete the `?` after the regex's first group to require the prefix. The head ref reaches the script through `env:`, never interpolated — on a public repo it is attacker-chosen. |
|
package/templates/dist-refs.yml
CHANGED
|
@@ -37,15 +37,30 @@
|
|
|
37
37
|
# artifact per platform named `<artifact-prefix><os>-<arch>`, then:
|
|
38
38
|
#
|
|
39
39
|
# dist:
|
|
40
|
-
# needs: [build] # your matrix build, one upload
|
|
40
|
+
# needs: [build] # your matrix build, one artifact-store/upload per platform
|
|
41
41
|
# uses: ./.github/workflows/dist-refs.yml
|
|
42
42
|
# permissions:
|
|
43
43
|
# contents: write
|
|
44
|
+
# secrets: inherit # the artifact-store secrets below — a called workflow
|
|
45
|
+
# # reads no secret it is not passed
|
|
44
46
|
# with:
|
|
45
47
|
# version: ${{ needs.release.outputs.tag }} # vX.Y.Z or vX.Y.Z-rc.N
|
|
46
48
|
# platforms: darwin-arm64 darwin-x64 linux-x64 linux-arm64 win32-x64
|
|
47
49
|
# bin: mytool # EDIT: the launcher's binary name
|
|
48
50
|
#
|
|
51
|
+
# THE ARTIFACTS GO THROUGH YOUR ARTIFACT STORE, not GitHub's capped artifact allowance
|
|
52
|
+
# (CONVENTIONS.md §7, "CI artifacts", #601). The build uploads each platform with
|
|
53
|
+
# artifact-store/upload, and the download step below reads them back with
|
|
54
|
+
# artifact-store/download, both with the same five secrets: ARTIFACT_STORE_ENDPOINT,
|
|
55
|
+
# ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
|
|
56
|
+
# ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Pass them with
|
|
57
|
+
# `secrets: inherit` as above, or one by one under `secrets:`. With no bucket secret the
|
|
58
|
+
# download runs with `backend: github`, i.e. GitHub's own artifact action, so a copy works
|
|
59
|
+
# before its store exists — the build's uploads must then use the same fallback.
|
|
60
|
+
# ⚠ REGION: requests are signed for the region and default to us-east-1. A store configured
|
|
61
|
+
# with any other region answers 400 to every GET signed for the wrong one, so set
|
|
62
|
+
# ARTIFACT_STORE_REGION and pass it on every call site, uploads included.
|
|
63
|
+
#
|
|
49
64
|
# Each artifact must hold the binary at its top level, named `<bin>` (`<bin>.exe` on win32-*).
|
|
50
65
|
# Anything else in the artifact rides along in the same ref and is covered by SHA256SUMS.
|
|
51
66
|
#
|
|
@@ -92,6 +107,24 @@ on:
|
|
|
92
107
|
required: false
|
|
93
108
|
type: string
|
|
94
109
|
default: 'dist-'
|
|
110
|
+
# The artifact store's connection (#601). All optional: with no bucket the download falls
|
|
111
|
+
# back to GitHub's artifact action. `secrets: inherit` from the caller passes them too.
|
|
112
|
+
secrets:
|
|
113
|
+
ARTIFACT_STORE_ENDPOINT:
|
|
114
|
+
description: 'S3 endpoint URL. Empty means the AWS default endpoint.'
|
|
115
|
+
required: false
|
|
116
|
+
ARTIFACT_STORE_BUCKET:
|
|
117
|
+
description: 'Bucket the build uploaded to. Empty = backend github.'
|
|
118
|
+
required: false
|
|
119
|
+
ARTIFACT_STORE_ACCESS_KEY:
|
|
120
|
+
description: 'Access key id for the store.'
|
|
121
|
+
required: false
|
|
122
|
+
ARTIFACT_STORE_SECRET_KEY:
|
|
123
|
+
description: 'Secret access key for the store.'
|
|
124
|
+
required: false
|
|
125
|
+
ARTIFACT_STORE_REGION:
|
|
126
|
+
description: 'Region the store signs for. Empty means us-east-1.'
|
|
127
|
+
required: false
|
|
95
128
|
|
|
96
129
|
permissions:
|
|
97
130
|
contents: write
|
|
@@ -120,10 +153,26 @@ jobs:
|
|
|
120
153
|
with:
|
|
121
154
|
fetch-depth: 1
|
|
122
155
|
|
|
123
|
-
|
|
156
|
+
# Through the artifact store (#601): the secrets and the region trap are in the header.
|
|
157
|
+
# EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls — `colab template` writes
|
|
158
|
+
# the version it stamps; by hand, pin a tag or a commit, never a branch. Copied the action
|
|
159
|
+
# into this repo instead? `uses: ./.github/actions/artifact-store/download`.
|
|
160
|
+
- name: Download the per-platform artifacts
|
|
161
|
+
uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
|
|
124
162
|
with:
|
|
163
|
+
# Empty name + pattern = every `<artifact-prefix>*` artifact of this run, each in
|
|
164
|
+
# dist-in/<name>/ — the layout the push step reads.
|
|
125
165
|
pattern: ${{ inputs.artifact-prefix }}*
|
|
126
166
|
path: dist-in
|
|
167
|
+
# No bucket secret → GitHub's own artifact action, unchanged. The bucket, not the
|
|
168
|
+
# endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
|
|
169
|
+
# bucket is none.
|
|
170
|
+
backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
|
|
171
|
+
endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
|
|
172
|
+
bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
|
|
173
|
+
access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
|
|
174
|
+
secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
|
|
175
|
+
region: ${{ secrets.ARTIFACT_STORE_REGION }}
|
|
127
176
|
|
|
128
177
|
- name: Push one orphan ref per platform
|
|
129
178
|
env:
|
|
@@ -0,0 +1,39 @@
|
|
|
1
|
+
# `docs/` — what lives here
|
|
2
|
+
|
|
3
|
+
The index of this repo's `docs/`: **one line per root entry**, file or folder. A folder's own
|
|
4
|
+
contents are listed by its own `README.md`, not here. Add the line in the same commit that adds
|
|
5
|
+
the entry; a file no line names is one nobody will find.
|
|
6
|
+
|
|
7
|
+
Keep this file's merges conflict-free — `.gitattributes` carries:
|
|
8
|
+
|
|
9
|
+
```gitattributes
|
|
10
|
+
docs/README.md merge=union
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Two branches that each add a line then merge cleanly; check the order by eye afterwards.
|
|
14
|
+
|
|
15
|
+
## Entries
|
|
16
|
+
|
|
17
|
+
<!-- One line each, in this shape. Delete the examples you do not have yet: reserved names are
|
|
18
|
+
created when their first content arrives, never as empty placeholders. -->
|
|
19
|
+
|
|
20
|
+
- [`architecture.md`](architecture.md) — the system as it is now, edited in place.
|
|
21
|
+
- [`deploy.md`](deploy.md) — how this repo reaches production, and its runbook.
|
|
22
|
+
- [`adr/`](adr/README.md) — one file per decision, `<issue>-<slug>.md`.
|
|
23
|
+
- [`gotchas.d/`](gotchas.d/README.md) — one file per long-lived gotcha, `<issue>-<slug>.md`.
|
|
24
|
+
- [`design/`](design/README.md) — one folder per design issue, `design/<slug>-<N>/`.
|
|
25
|
+
|
|
26
|
+
## The layout, in brief
|
|
27
|
+
|
|
28
|
+
The full rule is `code-wrap` A2, *The `docs/` layout*, in the colab-handbook.
|
|
29
|
+
|
|
30
|
+
- **Current truth only.** Plans, proposals, reports, audits and session notes go on the Issue,
|
|
31
|
+
never in `docs/`.
|
|
32
|
+
- **Names:** lower-kebab-case, no dates; the issue number is the only key (`README.md` excepted).
|
|
33
|
+
- **Reserved root names:** `architecture.md`, `deploy.md`, `operations.md`, `data.md`,
|
|
34
|
+
`design-spec.md`, `guides/`, `reference/` — plus `adr/`, `gotchas.d/`, `design/`.
|
|
35
|
+
- **Design artifacts:** `design/<slug>-<N>/` holds `<slug>-<N>-spec.md`, `<slug>-<N>-mockup.html`
|
|
36
|
+
and `frames/`. Fonts and shared CSS live once, in `design/_assets/`, or are linked from the
|
|
37
|
+
design-system package.
|
|
38
|
+
- **Binaries stay light:** an image over 1 MB is exported smaller.
|
|
39
|
+
- **Existing files stay where they are** (lazy migration); new entries follow the layout.
|
package/templates/docs-lint.mjs
CHANGED
|
@@ -12,6 +12,12 @@
|
|
|
12
12
|
// know whether a gotcha is still true; that stays with `code-wrap`'s stale-docs
|
|
13
13
|
// step and a human hygiene pass. This split is deliberate (colab-handbook #249).
|
|
14
14
|
//
|
|
15
|
+
// Checks 9-14 (colab-handbook #686) read the `docs/` LAYOUT `code-wrap` A2
|
|
16
|
+
// states: an index (`docs/README.md`, one line per root entry), no plan/
|
|
17
|
+
// proposal/report/audit or dated names, lower-kebab-case names, one folder per
|
|
18
|
+
// design issue (`docs/design/<slug>-<N>/`), images under 1 MB, and fonts only
|
|
19
|
+
// in `docs/design/_assets/`. All WARN — existing files may stay where they are.
|
|
20
|
+
//
|
|
15
21
|
// ZERO DEPENDENCIES. Plain Node (>= 18), no npm install, no package.json needed
|
|
16
22
|
// to run it — only `node:fs`, `node:path`, (for the receipt hashes below) the
|
|
17
23
|
// builtin `node:crypto`, and `node:child_process` to shell out to `git
|
|
@@ -428,6 +434,9 @@ const LINK_RE = /\]\(([^)#\s]*\.md)?#?([^)\s]*)\)/g;
|
|
|
428
434
|
// A simpler "does this file link anywhere" scanner for the orphan check
|
|
429
435
|
// (check 2), which only needs the TARGET path, not the fragment.
|
|
430
436
|
const ANY_MD_LINK_RE = /\]\(([^)#\s]+\.md)(#[^)\s]*)?\)/g;
|
|
437
|
+
// Any link target, markdown or not (`](adr/)`, `](design/README.md)`) — the
|
|
438
|
+
// index check (9) asks which docs/ root entries a link reaches, files or folders.
|
|
439
|
+
const ANY_LINK_TARGET_RE = /\]\(([^)#\s]+)(#[^)\s]*)?\)/g;
|
|
431
440
|
|
|
432
441
|
function isExternalTarget(t) {
|
|
433
442
|
return /^[a-z][a-z0-9+.-]*:/i.test(t) || t.startsWith("//");
|
|
@@ -925,6 +934,254 @@ function checkTwoSurfaceLinkage(ctx) {
|
|
|
925
934
|
return { receipt };
|
|
926
935
|
}
|
|
927
936
|
|
|
937
|
+
// ===========================================================================
|
|
938
|
+
// Checks 9-14 — the docs/ LAYOUT (colab-handbook #686; `code-wrap` A2,
|
|
939
|
+
// a2-docs-layout.md). Every one is WARN: a layout finding is a tidy-up for the
|
|
940
|
+
// repo's own issue, never a broken reference, and existing files are allowed
|
|
941
|
+
// to stay where they are (lazy migration). They read FILE NAMES, not content,
|
|
942
|
+
// and they see every file under docs/ — not only markdown — because the
|
|
943
|
+
// patterns they look for (a 6 MB screenshot, a font copied into a design
|
|
944
|
+
// folder, a loose mockup.html) are mostly not markdown.
|
|
945
|
+
// ===========================================================================
|
|
946
|
+
|
|
947
|
+
// Every file under docs/ (any extension), repo-relative, git-ignore filtered.
|
|
948
|
+
// Cached on ctx: six checks share one walk and one `git check-ignore` call.
|
|
949
|
+
function docsAllFiles(ctx) {
|
|
950
|
+
if (ctx.docsAll) return ctx.docsAll;
|
|
951
|
+
const { repoRoot, config } = ctx;
|
|
952
|
+
const out = [];
|
|
953
|
+
const exists = existsSync(join(repoRoot, config.docsDir));
|
|
954
|
+
const stack = [config.docsDir];
|
|
955
|
+
while (exists && stack.length) {
|
|
956
|
+
const rel = stack.pop();
|
|
957
|
+
let entries;
|
|
958
|
+
try { entries = readdirSync(join(repoRoot, rel), { withFileTypes: true }); } catch { continue; }
|
|
959
|
+
for (const e of entries) {
|
|
960
|
+
const childRel = `${rel}/${e.name}`;
|
|
961
|
+
if (SKIP_DIR_RE.test(`/${childRel}/`)) continue;
|
|
962
|
+
if (e.isDirectory()) stack.push(childRel);
|
|
963
|
+
else if (e.isFile()) out.push(childRel.split(sep).join("/"));
|
|
964
|
+
}
|
|
965
|
+
}
|
|
966
|
+
const { files } = ctx.ignoreFilter(out.sort());
|
|
967
|
+
ctx.docsAll = { exists, files };
|
|
968
|
+
return ctx.docsAll;
|
|
969
|
+
}
|
|
970
|
+
|
|
971
|
+
// A file's size, as a receipt input: layout checks never read content.
|
|
972
|
+
function sizeOf(repoRoot, rel) {
|
|
973
|
+
try { return statSync(join(repoRoot, rel)).size; } catch { return 0; }
|
|
974
|
+
}
|
|
975
|
+
|
|
976
|
+
// Check 9 — the index. `docs/README.md` names every ROOT entry of docs/ (one
|
|
977
|
+
// line per entry — a link to it, or the name in backticks); entries below the
|
|
978
|
+
// root are reached through their own directory's README, which is check 2's
|
|
979
|
+
// business, not this one. No index at all is only a finding once docs/ has
|
|
980
|
+
// INDEX_MIN_ENTRIES root entries — the same threshold handbook-sync uses to
|
|
981
|
+
// offer templates/docs-README.md, so a two-file docs/ is never nagged.
|
|
982
|
+
const INDEX_MIN_ENTRIES = 3;
|
|
983
|
+
const INDEX_NAMES = ["README.md", "INDEX.md"];
|
|
984
|
+
|
|
985
|
+
function checkDocsIndex(ctx) {
|
|
986
|
+
const { repoRoot, config, findings } = ctx;
|
|
987
|
+
const receipt = makeReceipt();
|
|
988
|
+
const check = "9 docs-index";
|
|
989
|
+
const { exists, files } = docsAllFiles(ctx);
|
|
990
|
+
if (!exists) {
|
|
991
|
+
receipt.note = `${config.docsDir}/ does not exist — nothing to index`;
|
|
992
|
+
return { receipt };
|
|
993
|
+
}
|
|
994
|
+
const prefix = `${config.docsDir}/`;
|
|
995
|
+
const roots = [...new Set(files.map((f) => f.slice(prefix.length).split("/")[0]))].sort();
|
|
996
|
+
const indexName = INDEX_NAMES.find((n) => roots.includes(n));
|
|
997
|
+
const entries = roots.filter((r) => !INDEX_NAMES.includes(r));
|
|
998
|
+
for (const r of roots) receipt.add(`${prefix}${r}`, ""); // the root listing is what was read
|
|
999
|
+
if (!indexName) {
|
|
1000
|
+
if (entries.length >= INDEX_MIN_ENTRIES) {
|
|
1001
|
+
findings.warn(check, `${config.docsDir}/ has ${entries.length} root entries and no ${config.docsDir}/README.md — add an index, one line per root entry (templates/docs-README.md), with \`${config.docsDir}/README.md merge=union\` in .gitattributes`);
|
|
1002
|
+
}
|
|
1003
|
+
receipt.note = `${entries.length} root entr(y/ies), no index`;
|
|
1004
|
+
return { receipt };
|
|
1005
|
+
}
|
|
1006
|
+
const indexPath = `${prefix}${indexName}`;
|
|
1007
|
+
const text = readFileSafeText(join(repoRoot, indexPath)) ?? "";
|
|
1008
|
+
receipt.add(indexPath, text);
|
|
1009
|
+
const named = new Set();
|
|
1010
|
+
ANY_LINK_TARGET_RE.lastIndex = 0;
|
|
1011
|
+
let m;
|
|
1012
|
+
while ((m = ANY_LINK_TARGET_RE.exec(text))) {
|
|
1013
|
+
const raw = m[1];
|
|
1014
|
+
if (isExternalTarget(raw) || PLACEHOLDER_TARGET_RE.test(raw)) continue;
|
|
1015
|
+
named.add(resolveRepoPath(config.docsDir, raw).slice(prefix.length).split("/")[0]);
|
|
1016
|
+
}
|
|
1017
|
+
for (const t of text.matchAll(/`\.?\/?([^`/\s]+)\/?`/g)) named.add(t[1]);
|
|
1018
|
+
let missing = 0;
|
|
1019
|
+
for (const e of entries) {
|
|
1020
|
+
if (named.has(e)) continue;
|
|
1021
|
+
missing++;
|
|
1022
|
+
findings.warn(check, `${prefix}${e} is a root entry of ${config.docsDir}/ that ${indexPath} never names — add its line to the index`);
|
|
1023
|
+
}
|
|
1024
|
+
receipt.note = `${entries.length} root entr(y/ies) vs ${indexPath}, ${missing} not indexed`;
|
|
1025
|
+
return { receipt };
|
|
1026
|
+
}
|
|
1027
|
+
|
|
1028
|
+
// Check 10 — transient names. Plans, proposals, reports, audits and session
|
|
1029
|
+
// notes are the Issue's, not current truth's. The signal is the word as the
|
|
1030
|
+
// FIRST or LAST word of a name under docs/ (`plan.md`, `q3-report.md`,
|
|
1031
|
+
// `audit-2025.md`, `plans/`), after a leading issue number is dropped — never a
|
|
1032
|
+
// substring (`planning-model.md`, `airplane.md`), and never a middle word, so
|
|
1033
|
+
// an issue-keyed record whose TOPIC is a plan (`536-handoff-missing-plan-
|
|
1034
|
+
// rationale.md`, measured on this handbook's own docs/adr/) stays quiet. A
|
|
1035
|
+
// dated MARKDOWN name is check 5's (left alone, so one file never warns
|
|
1036
|
+
// twice); a dated name on any other file (`2026-03-01-shot.png`) is reported here.
|
|
1037
|
+
const TRANSIENT_WORDS = new Set(["plan", "plans", "proposal", "proposals", "report", "reports", "audit", "audits"]);
|
|
1038
|
+
|
|
1039
|
+
function transientWord(rel) {
|
|
1040
|
+
for (const seg of rel.split("/")) {
|
|
1041
|
+
const words = seg.replace(/\.[^.]*$/, "").toLowerCase().split(/[-_.]+/).filter(Boolean);
|
|
1042
|
+
while (words.length && /^\d+$/.test(words[0])) words.shift();
|
|
1043
|
+
for (const w of [words[0], words[words.length - 1]]) if (w && TRANSIENT_WORDS.has(w)) return w;
|
|
1044
|
+
}
|
|
1045
|
+
return null;
|
|
1046
|
+
}
|
|
1047
|
+
|
|
1048
|
+
function checkTransientNames(ctx) {
|
|
1049
|
+
const { repoRoot, config, findings } = ctx;
|
|
1050
|
+
const receipt = makeReceipt();
|
|
1051
|
+
const check = "10 transient-names";
|
|
1052
|
+
const { files } = docsAllFiles(ctx);
|
|
1053
|
+
const prefix = `${config.docsDir}/`;
|
|
1054
|
+
let flagged = 0;
|
|
1055
|
+
for (const f of files) {
|
|
1056
|
+
receipt.add(f, String(sizeOf(repoRoot, f)));
|
|
1057
|
+
const rel = f.slice(prefix.length);
|
|
1058
|
+
const word = transientWord(rel);
|
|
1059
|
+
if (word) {
|
|
1060
|
+
flagged++;
|
|
1061
|
+
findings.warn(check, `${f} is named as a ${word.replace(/s$/, "")} — plans, proposals, reports, audits and session notes go on the Issue, not in ${config.docsDir}/ (current truth)`);
|
|
1062
|
+
} else if (!/\.md$/i.test(f) && DATED_NAME_RE.test(rel)) {
|
|
1063
|
+
flagged++;
|
|
1064
|
+
findings.warn(check, `${f} has a dated name — the issue number is the only key under ${config.docsDir}/`);
|
|
1065
|
+
}
|
|
1066
|
+
}
|
|
1067
|
+
receipt.note = `${files.length} name(s) checked, ${flagged} transient`;
|
|
1068
|
+
return { receipt };
|
|
1069
|
+
}
|
|
1070
|
+
|
|
1071
|
+
// Check 11 — lower-kebab-case names. Every path segment below docs/ is
|
|
1072
|
+
// lower-case letters, digits and hyphens, with dot-separated extensions
|
|
1073
|
+
// (`gotchas.d`, `x.test.md`). Two exemptions: README.md (any case of the
|
|
1074
|
+
// extension), and ONE leading underscore, which marks a shared support folder
|
|
1075
|
+
// (`design/_assets/`) rather than content.
|
|
1076
|
+
const KEBAB_SEGMENT_RE = /^_?[a-z0-9]+(-[a-z0-9]+)*(\.[a-z0-9]+(-[a-z0-9]+)*)*$/;
|
|
1077
|
+
|
|
1078
|
+
function checkKebabNames(ctx) {
|
|
1079
|
+
const { repoRoot, config, findings } = ctx;
|
|
1080
|
+
const receipt = makeReceipt();
|
|
1081
|
+
const check = "11 kebab-names";
|
|
1082
|
+
const { files } = docsAllFiles(ctx);
|
|
1083
|
+
const prefix = `${config.docsDir}/`;
|
|
1084
|
+
const reported = new Set();
|
|
1085
|
+
for (const f of files) {
|
|
1086
|
+
receipt.add(f, String(sizeOf(repoRoot, f)));
|
|
1087
|
+
const segs = f.slice(prefix.length).split("/");
|
|
1088
|
+
for (let i = 0; i < segs.length; i++) {
|
|
1089
|
+
const seg = segs[i];
|
|
1090
|
+
const last = i === segs.length - 1;
|
|
1091
|
+
if (last && /^readme\.md$/i.test(seg)) continue;
|
|
1092
|
+
if (KEBAB_SEGMENT_RE.test(seg)) continue;
|
|
1093
|
+
const where = `${prefix}${segs.slice(0, i + 1).join("/")}${last ? "" : "/"}`;
|
|
1094
|
+
if (reported.has(where)) break; // one finding per offending directory, not one per file in it
|
|
1095
|
+
reported.add(where);
|
|
1096
|
+
findings.warn(check, `${where} is not lower-kebab-case — names under ${config.docsDir}/ are lower-case words joined by hyphens (README.md excepted)`);
|
|
1097
|
+
break;
|
|
1098
|
+
}
|
|
1099
|
+
}
|
|
1100
|
+
receipt.note = `${files.length} path(s) checked, ${reported.size} non-kebab name(s)`;
|
|
1101
|
+
return { receipt };
|
|
1102
|
+
}
|
|
1103
|
+
|
|
1104
|
+
// Check 12 — design artifacts live in one folder per design issue,
|
|
1105
|
+
// `design/<slug>-<N>/` (spec, mockup, frames/). Flagged: a loose file at the
|
|
1106
|
+
// design root (README.md, the folder's index, excepted) and a first-level
|
|
1107
|
+
// folder that is not `<slug>-<N>` — a bare number (`design/123/`) included —
|
|
1108
|
+
// apart from `_assets/`, the one shared copy of fonts and CSS. What sits
|
|
1109
|
+
// INSIDE a well-named folder is that folder's own business.
|
|
1110
|
+
const DESIGN_FOLDER_RE = /^[a-z0-9]+(-[a-z0-9]+)*-\d+$/;
|
|
1111
|
+
|
|
1112
|
+
function checkDesignLayout(ctx) {
|
|
1113
|
+
const { repoRoot, config, findings } = ctx;
|
|
1114
|
+
const receipt = makeReceipt();
|
|
1115
|
+
const check = "12 design-layout";
|
|
1116
|
+
const designDir = `${config.docsDir}/design`;
|
|
1117
|
+
const inDesign = docsAllFiles(ctx).files.filter((f) => f.startsWith(`${designDir}/`));
|
|
1118
|
+
if (inDesign.length === 0) {
|
|
1119
|
+
receipt.note = `${designDir}/ has no files — nothing to check`;
|
|
1120
|
+
return { receipt };
|
|
1121
|
+
}
|
|
1122
|
+
const badFolders = new Set();
|
|
1123
|
+
let loose = 0;
|
|
1124
|
+
for (const f of inDesign) {
|
|
1125
|
+
receipt.add(f, String(sizeOf(repoRoot, f)));
|
|
1126
|
+
const segs = f.slice(designDir.length + 1).split("/");
|
|
1127
|
+
if (segs.length === 1) {
|
|
1128
|
+
if (/^readme\.md$/i.test(segs[0])) continue;
|
|
1129
|
+
loose++;
|
|
1130
|
+
findings.warn(check, `${f} sits loose in ${designDir}/ — a design artifact belongs in ${designDir}/<slug>-<N>/ (a file already here may stay — lazy migration; new ones go in a folder)`);
|
|
1131
|
+
} else if (segs[0] !== "_assets" && !DESIGN_FOLDER_RE.test(segs[0]) && !badFolders.has(segs[0])) {
|
|
1132
|
+
badFolders.add(segs[0]);
|
|
1133
|
+
findings.warn(check, `${designDir}/${segs[0]}/ is not named <slug>-<N> — one folder per design issue, slug first, issue number last`);
|
|
1134
|
+
}
|
|
1135
|
+
}
|
|
1136
|
+
receipt.note = `${inDesign.length} file(s) under ${designDir}/, ${loose} loose, ${badFolders.size} misnamed folder(s)`;
|
|
1137
|
+
return { receipt };
|
|
1138
|
+
}
|
|
1139
|
+
|
|
1140
|
+
// Check 13 — image weight. An image over IMAGE_MAX_BYTES under docs/ is
|
|
1141
|
+
// weight every clone carries forever; export it smaller, or link it.
|
|
1142
|
+
const IMAGE_EXT_RE = /\.(png|jpe?g|gif|webp|avif|bmp|tiff?|svg|heic)$/i;
|
|
1143
|
+
const IMAGE_MAX_BYTES = 1024 * 1024;
|
|
1144
|
+
|
|
1145
|
+
function checkLargeImages(ctx) {
|
|
1146
|
+
const { repoRoot, config, findings } = ctx;
|
|
1147
|
+
const receipt = makeReceipt();
|
|
1148
|
+
const check = "13 large-images";
|
|
1149
|
+
const images = docsAllFiles(ctx).files.filter((f) => IMAGE_EXT_RE.test(f));
|
|
1150
|
+
let flagged = 0;
|
|
1151
|
+
for (const f of images) {
|
|
1152
|
+
const size = sizeOf(repoRoot, f);
|
|
1153
|
+
receipt.add(f, String(size));
|
|
1154
|
+
if (size > IMAGE_MAX_BYTES) {
|
|
1155
|
+
flagged++;
|
|
1156
|
+
findings.warn(check, `${f} is ${(size / 1024 / 1024).toFixed(1)} MB — over the 1 MB advisory ceiling for an image under ${config.docsDir}/; export it smaller`);
|
|
1157
|
+
}
|
|
1158
|
+
}
|
|
1159
|
+
receipt.note = `${images.length} image(s) checked, ${flagged} over 1 MB`;
|
|
1160
|
+
return { receipt };
|
|
1161
|
+
}
|
|
1162
|
+
|
|
1163
|
+
// Check 14 — fonts in design folders. A design folder links the design-system
|
|
1164
|
+
// package, or the one shared copy in `design/_assets/` — it never carries its
|
|
1165
|
+
// own fonts (measured: 454 font files for 11 unique ones, one repo).
|
|
1166
|
+
const FONT_EXT_RE = /\.(woff2?|ttf|otf|eot)$/i;
|
|
1167
|
+
|
|
1168
|
+
function checkDesignFonts(ctx) {
|
|
1169
|
+
const { repoRoot, config, findings } = ctx;
|
|
1170
|
+
const receipt = makeReceipt();
|
|
1171
|
+
const check = "14 design-fonts";
|
|
1172
|
+
const designDir = `${config.docsDir}/design`;
|
|
1173
|
+
const fonts = docsAllFiles(ctx).files.filter((f) => f.startsWith(`${designDir}/`) && FONT_EXT_RE.test(f));
|
|
1174
|
+
let flagged = 0;
|
|
1175
|
+
for (const f of fonts) {
|
|
1176
|
+
receipt.add(f, String(sizeOf(repoRoot, f)));
|
|
1177
|
+
if (f.startsWith(`${designDir}/_assets/`)) continue;
|
|
1178
|
+
flagged++;
|
|
1179
|
+
findings.warn(check, `${f} is a font copied into a design folder — link the design-system package, or keep one copy in ${designDir}/_assets/`);
|
|
1180
|
+
}
|
|
1181
|
+
receipt.note = `${fonts.length} font file(s) under ${designDir}/, ${flagged} outside _assets/`;
|
|
1182
|
+
return { receipt };
|
|
1183
|
+
}
|
|
1184
|
+
|
|
928
1185
|
// ---------------------------------------------------------------------------
|
|
929
1186
|
// Main
|
|
930
1187
|
// ---------------------------------------------------------------------------
|
|
@@ -938,6 +1195,12 @@ const CHECKS = [
|
|
|
938
1195
|
["6 section-citations", checkGotchaCitations],
|
|
939
1196
|
["7 gotchas-d-registry", checkGotchasDRegistry],
|
|
940
1197
|
["8 two-surface-linkage", checkTwoSurfaceLinkage],
|
|
1198
|
+
["9 docs-index", checkDocsIndex],
|
|
1199
|
+
["10 transient-names", checkTransientNames],
|
|
1200
|
+
["11 kebab-names", checkKebabNames],
|
|
1201
|
+
["12 design-layout", checkDesignLayout],
|
|
1202
|
+
["13 large-images", checkLargeImages],
|
|
1203
|
+
["14 design-fonts", checkDesignFonts],
|
|
941
1204
|
];
|
|
942
1205
|
|
|
943
1206
|
function main() {
|
|
@@ -85,6 +85,18 @@ env:
|
|
|
85
85
|
# is no artifact lying around from the CI run on main. To use this you must add a
|
|
86
86
|
# build job to THIS file that uploads an artifact, and make the release job
|
|
87
87
|
# `needs:` it. Left false because most of our repos build on the deploy target.
|
|
88
|
+
#
|
|
89
|
+
# The files come through the organisation's artifact store, not GitHub's capped
|
|
90
|
+
# artifact allowance (CONVENTIONS.md §7, "CI artifacts", #601): the "Download build
|
|
91
|
+
# artifacts" step calls artifact-store/download, so your build job uploads with
|
|
92
|
+
# artifact-store/upload and the same five secrets — ARTIFACT_STORE_ENDPOINT,
|
|
93
|
+
# ARTIFACT_STORE_BUCKET, ARTIFACT_STORE_ACCESS_KEY, ARTIFACT_STORE_SECRET_KEY and
|
|
94
|
+
# ARTIFACT_STORE_REGION (docs/artifact-store.md in the handbook). Until the bucket
|
|
95
|
+
# secret exists the step runs with `backend: github`, i.e. GitHub's own artifact
|
|
96
|
+
# action, so a fresh copy works before its store does.
|
|
97
|
+
# ⚠ REGION: requests are signed for the region and default to us-east-1. A store
|
|
98
|
+
# configured with any other region answers 400 to every GET signed for the wrong one,
|
|
99
|
+
# so set ARTIFACT_STORE_REGION — on the upload call site too, not just this one.
|
|
88
100
|
ATTACH_ARTIFACTS: "false"
|
|
89
101
|
# Empty means every artifact from this run.
|
|
90
102
|
ARTIFACT_NAME: ""
|
|
@@ -228,13 +240,26 @@ jobs:
|
|
|
228
240
|
# Same summary into the run page, so it is readable without opening Releases.
|
|
229
241
|
cat /tmp/body.md >> "$GITHUB_STEP_SUMMARY"
|
|
230
242
|
|
|
243
|
+
# Through the artifact store (#601): see ATTACH_ARTIFACTS above for the secrets and
|
|
244
|
+
# the region trap. EDIT: `@HANDBOOK_TAG` is the handbook release this copy calls —
|
|
245
|
+
# `colab template` writes the version it stamps; by hand, pin a tag or a commit, never
|
|
246
|
+
# a branch. Copied the action into this repo instead? `uses: ./.github/actions/artifact-store/download`.
|
|
231
247
|
- name: Download build artifacts
|
|
232
248
|
if: env.ATTACH_ARTIFACTS == 'true'
|
|
233
|
-
uses: actions/download
|
|
249
|
+
uses: futurelastic/colab-handbook/.github/actions/artifact-store/download@HANDBOOK_TAG
|
|
234
250
|
with:
|
|
235
|
-
# Empty name = every artifact produced by this run
|
|
251
|
+
# Empty name = every artifact produced by this run, each in release-artifacts/<name>/.
|
|
236
252
|
name: ${{ env.ARTIFACT_NAME }}
|
|
237
253
|
path: release-artifacts
|
|
254
|
+
# No bucket secret yet → GitHub's own artifact action, unchanged. The bucket, not the
|
|
255
|
+
# endpoint, decides: an empty endpoint is a real store (the AWS default), a missing
|
|
256
|
+
# bucket is none.
|
|
257
|
+
backend: ${{ secrets.ARTIFACT_STORE_BUCKET != '' && 's3' || 'github' }}
|
|
258
|
+
endpoint: ${{ secrets.ARTIFACT_STORE_ENDPOINT }}
|
|
259
|
+
bucket: ${{ secrets.ARTIFACT_STORE_BUCKET }}
|
|
260
|
+
access-key: ${{ secrets.ARTIFACT_STORE_ACCESS_KEY }}
|
|
261
|
+
secret-key: ${{ secrets.ARTIFACT_STORE_SECRET_KEY }}
|
|
262
|
+
region: ${{ secrets.ARTIFACT_STORE_REGION }}
|
|
238
263
|
continue-on-error: true
|
|
239
264
|
|
|
240
265
|
- name: List artifacts to attach
|
|
@@ -76,8 +76,10 @@ function substituteTrunk(text, p) {
|
|
|
76
76
|
* a refreshed file stays byte-identical to what `colab template <name> --force` would write.
|
|
77
77
|
*/
|
|
78
78
|
function renderForRepo(name, body, doc, version) {
|
|
79
|
-
|
|
79
|
+
// The pin applies to every template, as `colab template` writes it (#754: release-tag and dist-refs
|
|
80
|
+
// call the artifact-store action at `@HANDBOOK_TAG`); only the trunk refs are CI-template-only.
|
|
80
81
|
const pinned = version ? pinHandbookTag(body, version).text : body;
|
|
82
|
+
if (!/^ci-/.test(String(name || ''))) return pinned;
|
|
81
83
|
const p = protectedRefs(doc);
|
|
82
84
|
return p ? substituteTrunk(pinned, p).text : pinned;
|
|
83
85
|
}
|