@futurelastic/colab-handbook 1.22.1-rc.1 → 1.22.1-rc.2
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/docs-README.md +39 -0
- package/templates/docs-lint.mjs +263 -0
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. |
|
|
@@ -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() {
|