@widgetic/dev-tools 0.3.0 → 0.3.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/CHANGELOG.md CHANGED
@@ -3,6 +3,27 @@
3
3
  The format roughly follows [Keep a Changelog](https://keepachangelog.com/); the
4
4
  reasons matter more than the categories.
5
5
 
6
+ ## 0.3.1 — 2026-10-08
7
+
8
+ ### Added
9
+
10
+ - **The `i18n` and `rtl` subpaths of `@widgetic/design-system` in the sibling
11
+ alias table** (`SIBLING_PACKAGES['design-system'].subpaths`). `i18n` is the
12
+ words kit (the translator and `createI18n` that every package reads its
13
+ sentences through, with the test-only `i18n/audit` below it) and `rtl` is the
14
+ right to left kit (the source audit, `rtl/audit`, that the tests of every
15
+ package read their source through). An alias is a prefix match and the first
16
+ one that matches wins, so without an entry of its own the bare
17
+ `@widgetic/design-system` alias turned `@widgetic/design-system/i18n/audit`
18
+ into `<lib>/index.ts/i18n/audit`, which is nothing: a dev server or a test run
19
+ of a package that reads either kit could not resolve it. The layout test pins
20
+ both entries, and its disk-truth gate already fails if either points at a
21
+ directory that is not in the checkout.
22
+ - Consumers that cannot wait for this release (`widget-creator` carries the same
23
+ two entries in its own `vite.config.ts`, in front of the table, and drops them
24
+ on its own once the installed dev-tools has them) lose nothing by taking it
25
+ later.
26
+
6
27
  ## 0.3.0 — 2026-09-22
7
28
 
8
29
  ### Added
@@ -33,16 +54,29 @@ reasons matter more than the categories.
33
54
 
34
55
  ### Changed
35
56
 
36
- - **`check-readme-contracts` reads nine READMEs, not six.** `embed-sdk`,
57
+ - **`check-readme-contracts` now requires a section from all nine READMEs, and
58
+ reads the three hand-linking ones as their own tier.** `embed-sdk`,
37
59
  `recorder` and `ui-sdk` consume a sibling through a hand-made link to its
38
60
  built output rather than the dev-alias workflow, so the canonical
39
- sibling-source sentences would be false in their READMEs and are not
40
- required of them — but the retired-instruction ban is, and their READMEs
41
- were read by nothing at all before this: not the adopters' check, not a
42
- test. `LINKING_PACKAGES` names the tier, the fixture suite drives both of
43
- its directions (a linking README teaching `npm link` fails, plain prose
44
- passes, and the same plain prose still fails as an adopter), and the real
45
- checkout test asserts both tiers are read off the disk so a subject cannot
61
+ sibling-source sentences would be false in their READMEs. They carry a
62
+ canonical **linked-sibling** section instead (`CANONICAL_LINKING_SENTENCES`):
63
+ what the link resolves, why a sibling edit stays invisible until that package
64
+ rebuilds its `dist/`, and that the package's own install script is both the
65
+ setup and the repair path. The ban alone was never documentation: it kept
66
+ wrong instructions out without requiring the right ones, so three READMEs
67
+ that said nothing about the link they depend on passed it silently, having
68
+ been read by nothing at all before it. Requiring the section
69
+ also forced the ban to admit tiers: `npm link`, `volta run`, `llinks` and the
70
+ after-install re-run are *live* in those packages (`recorder`'s `lps` runs
71
+ `volta run npm link`, its `llinks` script reports what
72
+ `node_modules/@widgetic` resolves to), so banning them there would ban the
73
+ truth; `npm run ldt` and the retired `typescript-sdk` name stay banned in both
74
+ tiers because they are dead for everyone. New findings:
75
+ `linked-sibling section missing` and `linked-sibling section drift`. The
76
+ fixture suite drives both tiers (a linking README with no section fails, the
77
+ canonical section passes at any wrap width, a reworded one drifts, a fenced
78
+ command stays exempt, and `npm link` still fails in an adopter's prose), and
79
+ the real checkout test asserts every subject is read off the disk so none can
46
80
  pass vacuously. `collectReadmeDrift`'s option is now `packages`; the old
47
81
  `adopters` name throws rather than silently falling back to the defaults.
48
82
 
package/README.md CHANGED
@@ -174,15 +174,22 @@ tarball, publish, and have every consumer refresh its lockfile in the same
174
174
  commit as its version bump. Run it as `npm run check:readme` here, or
175
175
  `npx check-readme-contracts` anywhere the package is installed.
176
176
 
177
- Three packages consume a sibling without compiling its source: `embed-sdk`,
178
- `recorder` and `ui-sdk` link a sibling checkout by hand to its built output
179
- instead — `lps`, `npm link`, a raw `ln -s`. The canonical sentences would be
180
- false in their READMEs, so they are not required of them; what is required is
181
- the retired-instruction ban, because a `npm link` instruction is as wrong in
182
- their prose as in an adopter's. They are read by the same check for that one
183
- rule (`LINKING_PACKAGES` in `lib/readme-contract.mjs`). They were read by
184
- nothing before it — not the adopters' check, not a test — so drift there
185
- failed nothing at all.
177
+ Three packages consume a sibling the other way round: `embed-sdk`, `recorder`
178
+ and `ui-sdk` link a sibling checkout by hand to its built output instead —
179
+ `lps`, `lapisdk`, a raw `ln -s`. The sibling-source sentences would be false in
180
+ their READMEs, so they carry [their own canonical sentences](lib/readme-contract.mjs)
181
+ — the link, what it resolves, and why a sibling edit needs a rebuild to show up
182
+ — and [Linked siblings](#linked-siblings-consuming-built-output-not-source)
183
+ below is the section they copy. The retired-instruction ban reaches them one
184
+ tier narrower: `npm link`, `volta run`, `llinks` and the after-install re-run
185
+ are those packages' *live* setup — `recorder`'s `lps` runs `volta run npm link`,
186
+ and its `llinks` script reports what `node_modules/@widgetic` resolves to — so
187
+ that half of the ban would be banning the truth about them. What stays banned
188
+ in either tier is the lore that is dead everywhere: the `ldt` step, which these
189
+ packages never adopted, and the retired `typescript-sdk` name. All of it is
190
+ data in `LINKING_PACKAGES` and `STALE_PATTERNS` in
191
+ `lib/readme-contract.mjs`. They were read by nothing before this check — not
192
+ the adopters' check, not a test — so drift there failed nothing at all.
186
193
 
187
194
  Two things keep the link era's failure mode visible, because **nothing
188
195
  fails** when sibling-source development quietly stops working: the dynamic
@@ -200,6 +207,53 @@ hook, and site's `lps` exists for the same purpose for its embedded
200
207
  `file-browser`. Those are per-app choices about which sibling to iterate on;
201
208
  they are not part of dev-tools setup, and no step here depends on them.
202
209
 
210
+ ### Linked siblings: consuming built output, not source
211
+
212
+ `embed-sdk`, `recorder` and `ui-sdk` consume a sibling the other way round:
213
+ they link a sibling checkout into `node_modules` by hand — from a script the
214
+ package owns — and import what that checkout **builds**, so a sibling edit is
215
+ invisible here until that package rebuilds its `dist/`. The mechanism is
216
+ theirs and the scripts differ (`lapisdk`, `lps`, a raw `ln -s`), so the
217
+ canonical sentences stay command-neutral and each README names its own scripts
218
+ around them. These are the four sentences, in this order; the same text is
219
+ data in [`lib/readme-contract.mjs`](lib/readme-contract.mjs), which is what the
220
+ check matches:
221
+
222
+ This package consumes sibling `@widgetic/*` checkouts through a link in
223
+ `node_modules` that resolves the checkout itself — its built output, not its
224
+ source. The link is made by hand rather than through the `@widgetic/dev-tools`
225
+ dev-alias setup the adopting apps use, so a sibling edit stays invisible here
226
+ until that package rebuilds its `dist/`. Setup is the install script this
227
+ package ships: it reinstalls and then links the sibling, so `node_modules`
228
+ keeps resolving the checkout rather than the published package. The dev-alias
229
+ workflow these packages have not adopted, and the reasons the adopting apps use
230
+ it, are described in [the dev-tools README](../dev-tools/README.md).
231
+
232
+ App-specific sentences may sit between the canonical ones — what the package's
233
+ own scripts are called, which sibling it links, what has to be rebuilt first.
234
+ Commands belong in a fenced block, where the check does not read them: say what
235
+ the script does in prose, show what to run in the fence.
236
+
237
+ ```md
238
+ ## Sibling packages
239
+
240
+ <the four canonical sentences, wrapped to this README's width>
241
+
242
+ `npm run i` is the whole setup here: it reinstalls `node_modules` and then
243
+ runs this package's link step.
244
+
245
+ \`\`\`sh
246
+ npm run i # install, then link the sibling checkout
247
+ npm run lapisdk # re-link only, after a fresh node_modules
248
+ \`\`\`
249
+ ```
250
+
251
+ The `../dev-tools/README.md` link is relative to a `Frontend/` app, which is
252
+ where all three packages sit. `check-readme-contracts` reports
253
+ `linked-sibling section missing` when a README never raises the relationship at
254
+ all and `linked-sibling section drift` when it does but the wording has
255
+ forked — the same two shapes the adopter tier reports.
256
+
203
257
  ### The link doctor: checking sibling links, dists, and dead names
204
258
 
205
259
  `check-links` is the automated form of the eyeballing this section used to
@@ -13,9 +13,13 @@
13
13
  *
14
14
  * Three more packages consume a sibling through a hand-made link to its built
15
15
  * output — `embed-sdk`, `recorder`, `ui-sdk` — and were read by nothing at
16
- * all, so a `npm link` instruction copied back into one of their READMEs
17
- * would have failed nothing. They carry no canonical section (they compile no
18
- * sibling source), but they are scanned the same way.
16
+ * all, so drift in one of their READMEs failed nothing. They compile no
17
+ * sibling source, so the sibling-source sentences would be false in them; they
18
+ * carry the canonical linked-sibling sentences instead, which state what the
19
+ * link resolves and what that costs. The retired-instruction ban reaches them
20
+ * one tier narrower: the link-era mechanics it names are those packages' live
21
+ * setup, so only the patterns retired for every package (`npm run ldt`, the
22
+ * retired `typescript-sdk` name) are scanned for in their prose.
19
23
  *
20
24
  * This check reads each package's README and fails when the canonical
21
25
  * sibling-source sentences are missing, rewritten, or reordered, or when
@@ -57,12 +61,13 @@ if (packages.length === 0) {
57
61
  console.log(
58
62
  `[check-readme-contracts] ${packages.length} READMEs under Frontend/` +
59
63
  ` — ${ADOPTER_PACKAGES.length} adopters (canonical section required)` +
60
- ` + ${LINKING_PACKAGES.length} linking packages (retired instructions banned)`
64
+ ` + ${LINKING_PACKAGES.length} linking packages (linked-sibling section required)`
61
65
  );
62
66
  if (findings.length === 0) {
63
67
  console.log(
64
- ' OK — every adopter carries the canonical sibling-source section, in the canonical wording,\n' +
65
- ' and no README teaches the retired link-era instructions.\n'
68
+ ' OK — every adopter carries the canonical sibling-source section and every linking package\n' +
69
+ ' the canonical linked-sibling one, in the canonical wording, and no README teaches the\n' +
70
+ ' instructions retired for its tier.\n'
66
71
  );
67
72
  process.exit(0);
68
73
  }
@@ -72,6 +77,6 @@ for (const { kind, pkg, detail, fix } of findings) {
72
77
  }
73
78
  console.error(
74
79
  `\n ${findings.length} drifted README${findings.length === 1 ? '' : 's'} across ` +
75
- `${new Set(findings.map((f) => f.pkg)).size} adopter(s).\n`
80
+ `${new Set(findings.map((f) => f.pkg)).size} package(s).\n`
76
81
  );
77
82
  process.exit(1);
@@ -67,7 +67,16 @@ export const SIBLING_PACKAGES = {
67
67
  components: 'components',
68
68
  icons: 'icons',
69
69
  stores: 'stores',
70
- fonts: 'fonts'
70
+ fonts: 'fonts',
71
+ // The words kit every package reads its sentences through. The alias
72
+ // is a prefix match, so the test-only `@widgetic/design-system/i18n/audit`
73
+ // resolves through this one entry. Without it the bare-index alias
74
+ // below swallows `@widgetic/design-system/i18n` and turns it into
75
+ // `<lib>/index.ts/i18n`, which is nothing.
76
+ i18n: 'i18n',
77
+ // The right to left kit: the source audit (`rtl/audit`) that the tests of every package read their
78
+ // source through. A prefix match as well, and for the same reason as `i18n` above.
79
+ rtl: 'rtl'
71
80
  }
72
81
  },
73
82
  // `dir` was `props-editor` (see older configs — and dangling symlinks).
@@ -21,11 +21,21 @@ export const ADOPTER_PACKAGES: string[];
21
21
  /** The packages whose READMEs must also carry the publish section. */
22
22
  export const PUBLISH_PACKAGES: string[];
23
23
 
24
+ /**
25
+ * The canonical linked-sibling prose, for the packages in
26
+ * {@link LINKING_PACKAGES}. Same matching rules as the sibling sentences: an
27
+ * ordered-substring match, app-specific sentences allowed between them. The
28
+ * sentences stay command-neutral — the three packages link from different
29
+ * scripts — and each README names its own around them.
30
+ */
31
+ export const CANONICAL_LINKING_SENTENCES: string[];
32
+
24
33
  /**
25
34
  * The packages that consume a sibling through a hand-made link to its built
26
- * output instead of the dev-alias workflow. They are exempt from the canonical
27
- * sibling-source sentences (they compile no sibling source) but their prose is
28
- * still scanned for retired link-era instructions.
35
+ * output instead of the dev-alias workflow. They compile no sibling source, so
36
+ * they carry {@link CANONICAL_LINKING_SENTENCES} rather than the sibling-source
37
+ * sentences, and only the patterns retired for every tier are scanned for in
38
+ * their prose — the link-era mechanics are their live setup.
29
39
  */
30
40
  export const LINKING_PACKAGES: string[];
31
41
 
@@ -38,17 +48,29 @@ export const CHECKED_PACKAGES: string[];
38
48
  */
39
49
  export interface ReadmeFinding {
40
50
  /**
41
- * - `ldt section missing` — the README has no canonical sibling-source
42
- * section at all (or no README).
43
- * - `ldt section drift` — a section exists but its wording diverges from
44
- * the canonical sentences, or link-era instructions are present. A
45
- * linking package's README reports only the second kind.
51
+ * - `ldt section missing` — an adopter's README has no canonical
52
+ * sibling-source section at all (or no README).
53
+ * - `ldt section drift` — an adopter's section exists but its wording
54
+ * diverges from the canonical sentences, or link-era instructions are
55
+ * present in its prose.
56
+ * - `linked-sibling section missing` — a linking package's README never
57
+ * describes the hand-made link to its sibling checkout.
58
+ * - `linked-sibling section drift` — the README raises the link
59
+ * relationship but its wording diverges from
60
+ * {@link CANONICAL_LINKING_SENTENCES}, or instructions retired for every
61
+ * tier are present in its prose.
46
62
  * - `publish section missing` — a publishing package's README has no
47
63
  * canonical publish-preparation section.
48
64
  * - `publish section drift` — the section exists but its wording diverges
49
65
  * from {@link CANONICAL_PUBLISH_SENTENCES}.
50
66
  */
51
- kind: 'ldt section missing' | 'ldt section drift' | 'publish section missing' | 'publish section drift';
67
+ kind:
68
+ | 'ldt section missing'
69
+ | 'ldt section drift'
70
+ | 'linked-sibling section missing'
71
+ | 'linked-sibling section drift'
72
+ | 'publish section missing'
73
+ | 'publish section drift';
52
74
  /** The package directory under `Frontend/` that owns the finding. */
53
75
  pkg: string;
54
76
  /** What is wrong, README-relative. */
@@ -61,14 +83,23 @@ export interface ReadmeFinding {
61
83
  * The stale link-era instructions present in one README's prose (fenced code
62
84
  * blocks excluded), as readable labels. Word-bounded, so `pnpm link` does not
63
85
  * match the `npm link` pattern.
86
+ *
87
+ * The default `'adopter'` tier returns every retired pattern; `'linking'`
88
+ * returns only those retired for every package (`npm run ldt`, the
89
+ * `typescript-sdk` name), because the link-era mechanics describe a linking
90
+ * package's live setup rather than drift.
64
91
  */
65
- export declare function staleInstructionHits(text: string): string[];
92
+ export declare function staleInstructionHits(
93
+ text: string,
94
+ tier?: 'adopter' | 'linking'
95
+ ): string[];
66
96
 
67
97
  /**
68
98
  * Find what one package's README violates, by tier: an adopter must carry the
69
- * canonical sibling-source sentences (and a publisher the publish ones), while
70
- * a linking package must only keep the retired instructions out of its prose.
71
- * For an adopter an empty `raw` (absent file) yields `ldt section missing`.
99
+ * canonical sibling-source sentences (and a publisher the publish ones), a
100
+ * linking package the canonical linked-sibling ones, and every tier keeps the
101
+ * instructions retired for it out of its prose. An absent README yields the
102
+ * missing-section finding for whichever section that package's tier requires.
72
103
  */
73
104
  export declare function readmeFindings(
74
105
  pkg: string,
@@ -89,9 +120,9 @@ export interface CollectReadmeDriftOptions {
89
120
 
90
121
  /**
91
122
  * Collect every README finding under a Frontend checkout: each adopter's
92
- * README must carry the canonical sibling-source sentences, in order, and no
93
- * README — adopter or linking package — may teach the retired link-era
94
- * instructions in prose.
123
+ * README must carry the canonical sibling-source sentences, in order, each
124
+ * linking package's the canonical linked-sibling ones, and no README may teach
125
+ * the instructions retired for its tier in prose.
95
126
  */
96
127
  export declare function collectReadmeDrift(
97
128
  frontendRoot: string,
@@ -10,14 +10,16 @@
10
10
  * carry the canonical sibling-source sentences verbatim. The publish tier
11
11
  * ({@link PUBLISH_PACKAGES}) adds the publish-preparation sentences.
12
12
  * - **Linking packages** ({@link LINKING_PACKAGES}) consume a sibling through
13
- * a hand-made link to its built output instead — `lps`, `npm link`, a raw
14
- * `ln -s`. They do not compile sibling source, so the canonical sentences
15
- * would be false in their READMEs and are not required of them. What does
16
- * apply is the retired-instruction ban: their prose, like an adopter's,
17
- * must not re-teach the hand-linking the dev-alias workflow replaced. This
18
- * tier exists because those three READMEs were read by nothing at all —
19
- * neither the adopters' check nor any test — so a `npm link` instruction
20
- * copied back into one would have failed nothing.
13
+ * a hand-made link to its built output instead — `lps`, `lapisdk`, a raw
14
+ * `ln -s`. They compile no sibling source, so the sibling-source sentences
15
+ * would be false in their READMEs; they carry
16
+ * {@link CANONICAL_LINKING_SENTENCES} instead, which state what the link
17
+ * resolves to and what that costs. The retired-instruction ban reaches them
18
+ * through its global half only: the link-era mechanics are these packages'
19
+ * *live* setup — `recorder`'s `lps` runs `volta run npm link`, its `llinks`
20
+ * script reports what `node_modules/@widgetic` resolves to — so banning
21
+ * `npm link` in their prose would ban the truth about them. The ban's other
22
+ * half is the dev-alias story, and that is an adopter's story.
21
23
  *
22
24
  * The section earned its guard by drifting three different ways. It taught a
23
25
  * hand-linking practice after the practice was retired (site's `lps` and
@@ -83,12 +85,33 @@ export const CANONICAL_PUBLISH_SENTENCES = [
83
85
  /** The packages whose READMEs must carry the publish-preparation section. */
84
86
  export const PUBLISH_PACKAGES = ['chat', 'file-browser'];
85
87
 
88
+ /**
89
+ * The canonical linked-sibling prose, for the packages in
90
+ * {@link LINKING_PACKAGES}. Same matching rules as the sibling sentences:
91
+ * ordered substrings over whitespace-collapsed prose, with app-specific
92
+ * sentences allowed between them.
93
+ *
94
+ * What the three share is the shape, not the command: `embed-sdk` links from
95
+ * its `lapisdk` script, `recorder` from `lps`, `ui-sdk` from a raw `ln -s`.
96
+ * These sentences therefore stay command-neutral — they say what the link
97
+ * resolves, why that is not the dev-alias workflow, and that the package's own
98
+ * install script is the setup and the repair path — and each README names its
99
+ * own scripts around them, in its own words and its own fenced block.
100
+ */
101
+ export const CANONICAL_LINKING_SENTENCES = [
102
+ 'This package consumes sibling `@widgetic/*` checkouts through a link in `node_modules` that resolves the checkout itself — its built output, not its source.',
103
+ 'The link is made by hand rather than through the `@widgetic/dev-tools` dev-alias setup the adopting apps use, so a sibling edit stays invisible here until that package rebuilds its `dist/`.',
104
+ 'Setup is the install script this package ships: it reinstalls and then links the sibling, so `node_modules` keeps resolving the checkout rather than the published package.',
105
+ 'The dev-alias workflow these packages have not adopted, and the reasons the adopting apps use it, are described in [the dev-tools README](../dev-tools/README.md).'
106
+ ];
107
+
86
108
  /**
87
109
  * The packages that consume a sibling checkout through a hand-made link to its
88
110
  * built output rather than the dev-alias workflow — `embed-sdk` and `ui-sdk`
89
- * symlink `@widgetic/api-sdk`, `recorder` links it from its `lps` script.
90
- * They are exempt from the canonical sibling-source sentences (they compile no
91
- * sibling source) but not from the retired-instruction ban.
111
+ * link `@widgetic/api-sdk` from a script, `recorder` links it and
112
+ * `@widgetic/design-system` from `lps`. They are exempt from the canonical
113
+ * sibling-source sentences (they compile no sibling source) and carry
114
+ * {@link CANONICAL_LINKING_SENTENCES} instead.
92
115
  */
93
116
  export const LINKING_PACKAGES = ['embed-sdk', 'recorder', 'ui-sdk'];
94
117
 
@@ -97,17 +120,28 @@ export const CHECKED_PACKAGES = [...ADOPTER_PACKAGES, ...LINKING_PACKAGES];
97
120
 
98
121
  /**
99
122
  * Instructions from the link era that must never come back, word-bounded on
100
- * both sides. `npm link` cannot match inside `pnpm link` (the boundary fails
101
- * before the `npm`), so file-browser's packaging prose — how *other* projects
102
- * consume file-browser — stays out of scope, as it should be.
123
+ * both sides and tagged with the tiers they are retired for. `npm link`
124
+ * cannot match inside `pnpm link` (the boundary fails before the `npm`), so
125
+ * file-browser's packaging prose — how *other* projects consume file-browser —
126
+ * stays out of scope, as it should be.
127
+ *
128
+ * `both` — dead for every package: the `ldt` step belongs to a workflow the
129
+ * linking packages never adopted, and `typescript-sdk` is a package that no
130
+ * longer exists. Neither is ever true, so neither may be taught anywhere.
131
+ *
132
+ * `adopter` — the link-era mechanics the dev-alias workflow replaced. Retired
133
+ * in an adopter's prose, where hand-made links are redundant and the advice to
134
+ * recreate one is the drift this contract was written for. Not retired in a
135
+ * linking package's: there the same words describe the setup that is actually
136
+ * running, so the ban stops at the tier boundary.
103
137
  */
104
138
  const STALE_PATTERNS = [
105
- { pattern: /\bnpm run ldt\b/, label: '`npm run ldt`' },
106
- { pattern: /\bnpm link\b/, label: '`npm link`' },
107
- { pattern: /\bvolta run\b/, label: '`volta run`' },
108
- { pattern: /\bllinks\b/, label: 'the `llinks` verify script' },
109
- { pattern: /\bmust be re-run\b/, label: 'the after-install re-run instruction' },
110
- { pattern: /\btypescript-sdk\b/, label: 'the retired `typescript-sdk` package name' }
139
+ { pattern: /\bnpm run ldt\b/, label: '`npm run ldt`', tiers: 'both' },
140
+ { pattern: /\btypescript-sdk\b/, label: 'the retired `typescript-sdk` package name', tiers: 'both' },
141
+ { pattern: /\bnpm link\b/, label: '`npm link`', tiers: 'adopter' },
142
+ { pattern: /\bvolta run\b/, label: '`volta run`', tiers: 'adopter' },
143
+ { pattern: /\bllinks\b/, label: 'the `llinks` verify script', tiers: 'adopter' },
144
+ { pattern: /\bmust be re-run\b/, label: 'the after-install re-run instruction', tiers: 'adopter' }
111
145
  ];
112
146
 
113
147
  /**
@@ -115,7 +149,7 @@ const STALE_PATTERNS = [
115
149
  * link-doctor's problems, so reporters can treat the two checks alike.
116
150
  *
117
151
  * @typedef {object} ReadmeFinding
118
- * @property {'ldt section missing' | 'ldt section drift' | 'publish section missing' | 'publish section drift'} kind
152
+ * @property {'ldt section missing' | 'ldt section drift' | 'linked-sibling section missing' | 'linked-sibling section drift' | 'publish section missing' | 'publish section drift'} kind
119
153
  * @property {string} pkg The package directory under `Frontend/`.
120
154
  * @property {string} detail What is wrong, README-relative.
121
155
  * @property {string} fix The action that repairs it.
@@ -167,9 +201,21 @@ function firstMissingSentence(text, sentences) {
167
201
  return null;
168
202
  }
169
203
 
170
- /** The stale link-era instructions present in the text, as readable labels. */
171
- export function staleInstructionHits(text) {
172
- return STALE_PATTERNS.filter(({ pattern }) => pattern.test(text)).map(({ label }) => label);
204
+ /**
205
+ * The stale link-era instructions present in the text, as readable labels.
206
+ *
207
+ * The default `'adopter'` tier returns every retired pattern, which is what a
208
+ * caller scanning prose with no tier in hand (the CLI's docs, an audit) wants.
209
+ * `'linking'` narrows it to the patterns retired for everyone.
210
+ *
211
+ * @param {string} text Whitespace-collapsed prose.
212
+ * @param {'adopter' | 'linking'} [tier] Whose prose this is; defaults to `'adopter'`.
213
+ * @returns {string[]}
214
+ */
215
+ export function staleInstructionHits(text, tier = 'adopter') {
216
+ return STALE_PATTERNS.filter(
217
+ ({ pattern, tiers }) => (tiers === 'both' || tier === 'adopter') && pattern.test(text)
218
+ ).map(({ label }) => label);
173
219
  }
174
220
 
175
221
  /**
@@ -181,14 +227,18 @@ export function staleInstructionHits(text) {
181
227
  * @param {string} pkg The package's directory name under `Frontend/`.
182
228
  * @param {string} text Whitespace-collapsed prose.
183
229
  * @param {string} fix The action that repairs the drift.
230
+ * @param {'adopter' | 'linking'} tier Whose prose this is.
184
231
  * @returns {ReadmeFinding[]}
185
232
  */
186
- function staleFindings(pkg, text, fix) {
187
- const stale = staleInstructionHits(text);
233
+ function staleFindings(pkg, text, fix, tier) {
234
+ const stale = staleInstructionHits(text, tier);
188
235
  if (stale.length === 0) return [];
189
236
  return [
190
237
  {
191
- kind: 'ldt section drift',
238
+ // Both tiers report banned prose as drift on the section they require,
239
+ // so the finding names a section the README actually owes: `ldt` is an
240
+ // adopter's section, and a linking package owes the linked-sibling one.
241
+ kind: tier === 'linking' ? 'linked-sibling section drift' : 'ldt section drift',
192
242
  pkg,
193
243
  detail: `link-era instructions present in the README: ${stale.join(', ')}`,
194
244
  fix
@@ -198,10 +248,11 @@ function staleFindings(pkg, text, fix) {
198
248
 
199
249
  /**
200
250
  * Find what one package's README violates, by tier: an adopter must carry the
201
- * canonical sibling-source sentences (and a publisher the publish ones), while
202
- * a linking package must only keep the retired instructions out of its prose.
203
- * `readmePath` exists only for the error message when the file itself is
204
- * absent — for an adopter a missing README is a missing section.
251
+ * canonical sibling-source sentences (and a publisher the publish ones), a
252
+ * linking package the canonical linked-sibling ones, and every tier keeps the
253
+ * instructions retired for it out of its prose. `readmePath` exists only for
254
+ * the error message when the file itself is absent — an absent README is a
255
+ * missing section in whichever tier asked for it.
205
256
  *
206
257
  * @param {string} pkg The package's directory name under `Frontend/`.
207
258
  * @param {string} readmePath Where the README should be.
@@ -212,14 +263,40 @@ export function readmeFindings(pkg, readmePath, raw) {
212
263
  const findings = [];
213
264
  const text = prose(raw);
214
265
 
215
- // A linking package carries no canonical section, so nothing about its
216
- // prose is required to exist — only the retired instructions are banned.
266
+ // A linking package carries its own canonical section: the hand-made link
267
+ // to a sibling's built output *is* its setup, and a README that never says
268
+ // so leaves the reader to infer the mechanism from `node_modules` — the
269
+ // same silence that let a `npm link` line be copied into it unnoticed.
217
270
  if (LINKING_PACKAGES.includes(pkg)) {
218
- return staleFindings(
219
- pkg,
220
- text,
221
- 'retire the hand-linking instructions — this package links a sibling checkout by hand and has not adopted the dev-alias workflow yet (see dev-tools README, "The ldt workflow")'
271
+ const linkingGap = text
272
+ ? firstMissingSentence(text, CANONICAL_LINKING_SENTENCES)
273
+ : CANONICAL_LINKING_SENTENCES[0];
274
+ if (linkingGap !== null) {
275
+ // Prose that already raises the link mechanism has a section that
276
+ // drifted; prose that never raises it has no section to drift — the
277
+ // same distinction the adopter tier draws. The signal is the
278
+ // mechanism itself (the link, the `node_modules` path, the workflow it
279
+ // is not), not the word "sibling", which any sentence can carry while
280
+ // saying nothing about how the sibling arrives.
281
+ const drifted = /\blink|\bnode_modules\b|dev-tools/i.test(text);
282
+ findings.push({
283
+ kind: drifted ? 'linked-sibling section drift' : 'linked-sibling section missing',
284
+ pkg,
285
+ detail: drifted
286
+ ? `the linked-sibling section does not carry the canonical prose — first sentence missing or out of order: "${linkingGap}"`
287
+ : `no linked-sibling section was found in ${readmePath}`,
288
+ fix: 'copy the canonical linked-sibling section from dev-tools/README.md ("Linked siblings"); keep app-specific notes and commands outside its sentences'
289
+ });
290
+ }
291
+ findings.push(
292
+ ...staleFindings(
293
+ pkg,
294
+ text,
295
+ 'retire it: the `ldt` step and the retired `typescript-sdk` name are dead for this package too, whose live hand-made link its own section documents',
296
+ 'linking'
297
+ )
222
298
  );
299
+ return findings;
223
300
  }
224
301
 
225
302
  const canonicalGap = text ? firstMissingSentence(text, CANONICAL_SENTENCES) : CANONICAL_SENTENCES[0];
@@ -252,7 +329,8 @@ export function readmeFindings(pkg, readmePath, raw) {
252
329
  ...staleFindings(
253
330
  pkg,
254
331
  text,
255
- 'retire the link-era instructions; the workflow is an ordinary npm install (see dev-tools README, "The ldt workflow")'
332
+ 'retire the link-era instructions; the workflow is an ordinary npm install (see dev-tools README, "The ldt workflow")',
333
+ 'adopter'
256
334
  )
257
335
  );
258
336
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@widgetic/dev-tools",
3
- "version": "0.3.0",
3
+ "version": "0.3.2",
4
4
  "type": "module",
5
5
  "description": "Build-time checks and dev tooling shared by the published @widgetic packages, released once so the repositories that consume them cannot drift apart. Currently: check-runtime-deps (with the fixture suite that proves it fails), the Vite sibling-$lib remap, the canonical Frontend sibling layout that builds every consumer's dev-alias tables, and check-links — the link-doctor that fails when a sibling symlink dangles, a promised dist/ file is missing, or a dead checkout name lingers, and check-design-system-peers — which fails when the two design-system peers' lockfiles drift apart.",
6
6
  "repository": {
@@ -22,13 +22,19 @@ test('the design-system table expands to every subpath plus the index', () => {
22
22
  '@widgetic/design-system',
23
23
  '@widgetic/design-system/components',
24
24
  '@widgetic/design-system/fonts',
25
+ '@widgetic/design-system/i18n',
25
26
  '@widgetic/design-system/icons',
27
+ '@widgetic/design-system/rtl',
26
28
  '@widgetic/design-system/shad-editor',
27
29
  '@widgetic/design-system/stores',
28
30
  '@widgetic/design-system/styles'
29
31
  ].sort()
30
32
  );
31
33
  assert.equal(aliases['@widgetic/design-system/icons'], `${FRONTEND}/design-system/src/lib/icons`);
34
+ // the words kit: a directory, and the test-only `i18n/audit` resolves under it as a prefix
35
+ assert.equal(aliases['@widgetic/design-system/i18n'], `${FRONTEND}/design-system/src/lib/i18n`);
36
+ // the right to left kit: a directory as well, and the test-only `rtl/audit` resolves under it as a prefix
37
+ assert.equal(aliases['@widgetic/design-system/rtl'], `${FRONTEND}/design-system/src/lib/rtl`);
32
38
  // styles is a file, not a directory — the one entry that ever differed
33
39
  assert.equal(
34
40
  aliases['@widgetic/design-system/styles'],
@@ -43,6 +43,7 @@ import assert from 'node:assert/strict';
43
43
 
44
44
  import {
45
45
  ADOPTER_PACKAGES,
46
+ CANONICAL_LINKING_SENTENCES,
46
47
  CANONICAL_PUBLISH_SENTENCES,
47
48
  CANONICAL_SENTENCES,
48
49
  CHECKED_PACKAGES,
@@ -81,9 +82,9 @@ function findingsFor(root, { kind, pkg } = {}) {
81
82
  );
82
83
  }
83
84
 
84
- /** The canonical section, wrapped for one adopter's line width. */
85
- function section(wrap) {
86
- const words = CANONICAL_SENTENCES.join(' ').split(' ');
85
+ /** One canonical sentence set, joined and wrapped to a line width. */
86
+ function wrapped(sentences, wrap) {
87
+ const words = sentences.join(' ').split(' ');
87
88
  const lines = [];
88
89
  let line = '';
89
90
  for (const word of words) {
@@ -95,24 +96,22 @@ function section(wrap) {
95
96
  }
96
97
  }
97
98
  if (line) lines.push(line);
98
- return `## Sibling packages\n\n${lines.join('\n')}\n`;
99
+ return lines.join('\n');
100
+ }
101
+
102
+ /** The canonical sibling-source section, wrapped for one adopter's width. */
103
+ function section(wrap) {
104
+ return `## Sibling packages\n\n${wrapped(CANONICAL_SENTENCES, wrap)}\n`;
105
+ }
106
+
107
+ /** The canonical linked-sibling section, wrapped the same way. */
108
+ function linkingSection(wrap) {
109
+ return `## Sibling packages\n\n${wrapped(CANONICAL_LINKING_SENTENCES, wrap)}\n`;
99
110
  }
100
111
 
101
112
  /** The canonical publish-preparation prose, wrapped like an adopter's. */
102
113
  function publishSection() {
103
- const words = CANONICAL_PUBLISH_SENTENCES.join(' ').split(' ');
104
- const lines = [];
105
- let line = '';
106
- for (const word of words) {
107
- if (line && `${line} ${word}`.length > 72) {
108
- lines.push(line);
109
- line = word;
110
- } else {
111
- line = line ? `${line} ${word}` : word;
112
- }
113
- }
114
- if (line) lines.push(line);
115
- return `## Publishing\n\n${lines.join('\n')}\n`;
114
+ return `## Publishing\n\n${wrapped(CANONICAL_PUBLISH_SENTENCES, 72)}\n`;
116
115
  }
117
116
 
118
117
  /** A README that names dev-tools but carries none of the canonical prose. */
@@ -224,10 +223,22 @@ describe('stale link-era instructions', () => {
224
223
  );
225
224
  assert.deepEqual(hits, [
226
225
  '`npm run ldt`',
226
+ 'the retired `typescript-sdk` package name',
227
227
  '`npm link`',
228
228
  '`volta run`',
229
229
  'the `llinks` verify script',
230
- 'the after-install re-run instruction',
230
+ 'the after-install re-run instruction'
231
+ ]);
232
+ });
233
+
234
+ it('narrows to the patterns retired for every package when told the tier', () => {
235
+ // The link-era mechanics are a linking package's live setup, so only the
236
+ // lore that is dead everywhere survives the narrowing.
237
+ const mechanics = 'npm link, volta run, llinks, must be re-run';
238
+ assert.deepEqual(staleInstructionHits(mechanics, 'linking'), []);
239
+ assert.equal(staleInstructionHits(mechanics).length, 4);
240
+ assert.deepEqual(staleInstructionHits('npm run ldt and typescript-sdk', 'linking'), [
241
+ '`npm run ldt`',
231
242
  'the retired `typescript-sdk` package name'
232
243
  ]);
233
244
  });
@@ -307,15 +318,16 @@ describe('the publish contract', () => {
307
318
  });
308
319
 
309
320
  describe('the checkout collector', () => {
310
- it('accepts a checkout where every adopter carries its sections', () => {
311
- const root = checkout(
312
- Object.fromEntries(
321
+ it('accepts a checkout where every subject carries its sections', () => {
322
+ const root = checkout({
323
+ ...Object.fromEntries(
313
324
  ADOPTER_PACKAGES.map((p) => [
314
325
  p,
315
326
  PUBLISH_PACKAGES.includes(p) ? `${CLEAN}\n\n${publishSection()}` : CLEAN
316
327
  ])
317
- )
318
- );
328
+ ),
329
+ ...Object.fromEntries(LINKING_PACKAGES.map((p) => [p, linkingSection(72)]))
330
+ });
319
331
  assert.deepEqual(collectReadmeDrift(root), {
320
332
  packages: [...CHECKED_PACKAGES],
321
333
  findings: []
@@ -343,11 +355,23 @@ describe('the checkout collector', () => {
343
355
  it('checks every default subject, including ones with no README', () => {
344
356
  const root = checkout({ site: CLEAN });
345
357
  const f = findingsFor(root);
346
- // Five adopters missing the sibling section, plus the two publishers
347
- // missing the publish section on top of it. The linking packages are
348
- // subjects too, but a README that is not there teaches nothing.
349
- assert.equal(f.length, ADOPTER_PACKAGES.length - 1 + PUBLISH_PACKAGES.length);
350
- assert.ok(f.every((x) => x.kind === 'ldt section missing' || x.kind === 'publish section missing'));
358
+ // Five adopters missing the sibling section, the two publishers missing
359
+ // the publish section on top of it, and the three linking packages
360
+ // missing their own section — an absent README is a missing section in
361
+ // whichever tier asked for it, so no subject can pass vacuously.
362
+ assert.equal(
363
+ f.length,
364
+ ADOPTER_PACKAGES.length - 1 + PUBLISH_PACKAGES.length + LINKING_PACKAGES.length
365
+ );
366
+ assert.ok(
367
+ f.every((x) =>
368
+ [
369
+ 'ldt section missing',
370
+ 'publish section missing',
371
+ 'linked-sibling section missing'
372
+ ].includes(x.kind)
373
+ )
374
+ );
351
375
  });
352
376
 
353
377
  it('honors an explicit package list', () => {
@@ -372,63 +396,123 @@ describe('the linking tier', () => {
372
396
  // the canonical sentences would be false in their READMEs.
373
397
  assert.ok(LINKING_PACKAGES.every((p) => CHECKED_PACKAGES.includes(p)));
374
398
  assert.ok(LINKING_PACKAGES.every((p) => !ADOPTER_PACKAGES.includes(p)));
399
+ // Every linking subject with no section is a finding, not a pass: this is
400
+ // the state all three READMEs were in while the ban was the whole
401
+ // contract — the check was green and nobody reading them learned how the
402
+ // sibling arrives.
375
403
  for (const pkg of LINKING_PACKAGES) {
376
- assert.deepEqual(findingsFor(checkout({ [pkg]: PLAIN }), { pkg }), []);
404
+ assert.deepEqual(
405
+ findingsFor(checkout({ [pkg]: PLAIN }), { pkg }).map((f) => f.kind),
406
+ ['linked-sibling section missing']
407
+ );
408
+ }
409
+ });
410
+
411
+ it('accepts the canonical linked-sibling section wrapped to any line width', () => {
412
+ for (const wrap of [40, 60, 72, 88, 200]) {
413
+ assert.deepEqual(
414
+ readmeFindings('embed-sdk', 'embed-sdk/README.md', linkingSection(wrap)),
415
+ [],
416
+ `wrap ${wrap} should pass`
417
+ );
377
418
  }
378
419
  });
379
420
 
380
- it('fails a linking README that teaches the retired hand-linking', () => {
421
+ it('reports drift, not missing, when the prose raises the link but forks the wording', () => {
422
+ // Reworded on the unwrapped join: at a wrap width the phrase can straddle
423
+ // a line break, and the replacement would silently match nothing.
424
+ const forked = CANONICAL_LINKING_SENTENCES.join(' ').replace(
425
+ 'not its source',
426
+ 'rather than its source'
427
+ );
428
+ const f = readmeFindings('recorder', 'recorder/README.md', forked);
429
+ assert.equal(f.length, 1);
430
+ assert.equal(f[0].kind, 'linked-sibling section drift');
431
+ // The finding names the first canonical sentence that is missing, so the
432
+ // repair knows exactly which words to restore.
433
+ assert.match(f[0].detail, /its built output, not its source/);
434
+ });
435
+
436
+ it('accepts app-specific sentences and commands around the canonical ones', () => {
437
+ const withNotes =
438
+ '## Sibling packages\n\n' +
439
+ `${CANONICAL_LINKING_SENTENCES[0]}\n\n` +
440
+ 'Here that script is `npm run lps`, which links both siblings at once.\n\n' +
441
+ `${CANONICAL_LINKING_SENTENCES.slice(1).join(' ')}\n\n` +
442
+ '```sh\nnpm run i\nnpm run lps\n```\n';
443
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', withNotes), []);
444
+ });
445
+
446
+ it('fails a linking README whose only mention of the sibling is not the section', () => {
381
447
  const root = checkout({
382
448
  'embed-sdk': '# Widgetic Embed SDK\n\nInstall the sibling: `npm link @widgetic/api-sdk`.\n'
383
449
  });
384
450
  const f = findingsFor(root, { pkg: 'embed-sdk' });
385
451
  assert.equal(f.length, 1);
386
- assert.equal(f[0].kind, 'ldt section drift');
387
- assert.match(f[0].detail, /link-era instructions present/);
388
- assert.match(f[0].detail, /`npm link`/);
389
- // The repair names this package's actual state — still hand-linking —
390
- // rather than telling an adopter's story about an ordinary npm install.
391
- assert.match(f[0].fix, /has not adopted the dev-alias workflow/);
452
+ assert.equal(f[0].kind, 'linked-sibling section drift');
453
+ assert.match(f[0].detail, /does not carry the canonical prose/);
454
+ assert.match(f[0].fix, /canonical linked-sibling section/);
392
455
  });
393
456
 
394
- it('flags every retired pattern in a linking README, wherever it appears', () => {
457
+ it('allows the link-era mechanics that are these packages live setup', () => {
458
+ // recorder's lps script is `volta run npm link` and its llinks script
459
+ // reports what node_modules/@widgetic resolves to — prose describing that
460
+ // is the truth about the package, so the ban stops at the tier boundary.
461
+ const raw =
462
+ `${linkingSection(72)}\n\n` +
463
+ '`npm run lps` links both siblings through `volta run` with the pinned\n' +
464
+ 'toolchain, and `npm run llinks` reports what `node_modules/@widgetic`\n' +
465
+ 'resolves to.\n';
466
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', raw), []);
467
+ });
468
+
469
+ it('flags the instructions that are dead for every package, wherever they appear', () => {
395
470
  const root = checkout({
396
471
  'ui-sdk':
397
- '# Widgetic UI SDK\n\nRun `npm run ldt` to link, then `npx llinks` to verify,\n' +
398
- 'and the symlink must be re-run after installs.\n'
472
+ '# Widgetic UI SDK\n\nRun `npm run ldt` to link, and the old `typescript-sdk`\n' +
473
+ 'name is gone.\n' +
474
+ linkingSection(72)
399
475
  });
400
476
  const f = findingsFor(root, { pkg: 'ui-sdk' });
401
477
  assert.equal(f.length, 1);
478
+ assert.equal(f[0].kind, 'linked-sibling section drift');
402
479
  assert.match(f[0].detail, /`npm run ldt`/);
403
- assert.match(f[0].detail, /the `llinks` verify script/);
404
- assert.match(f[0].detail, /the after-install re-run instruction/);
480
+ assert.match(f[0].detail, /the retired `typescript-sdk` package name/);
405
481
  });
406
482
 
407
- it('does not require the canonical sentences — but an adopter carrying that text still must', () => {
408
- // Same prose, two tiers: nothing about it is missing for a linking
409
- // package, while an adopter is missing the whole canonical section.
410
- assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', PLAIN), []);
411
- const adopter = readmeFindings('site', 'site/README.md', PLAIN);
412
- assert.deepEqual(adopter.map((x) => x.kind), ['ldt section missing']);
483
+ it('requires its own sentences — and only its own — from a linking package', () => {
484
+ // Same prose, two tiers: the linked-sibling section completes a linking
485
+ // package, while an adopter carrying that text has drifted from its own.
486
+ assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', linkingSection(72)), []);
487
+ const adopter = readmeFindings('site', 'site/README.md', linkingSection(72));
488
+ assert.deepEqual(adopter.map((x) => x.kind), ['ldt section drift']);
489
+ // The reverse: an adopter's section satisfies a linking package nowhere,
490
+ // because it never states how the sibling arrives.
491
+ const linking = readmeFindings('recorder', 'recorder/README.md', section(72));
492
+ assert.deepEqual(linking.map((x) => x.kind), ['linked-sibling section drift']);
413
493
  });
414
494
 
415
495
  it('does not require the publish sentences from a linking package either', () => {
416
496
  // The publish tier is about the two packages that ship a dist tarball;
417
497
  // a linking package is never asked for those sentences.
418
- assert.deepEqual(readmeFindings('ui-sdk', 'ui-sdk/README.md', `${PLAIN}\nPublishing notes.\n`), []);
498
+ assert.deepEqual(
499
+ readmeFindings('ui-sdk', 'ui-sdk/README.md', `${linkingSection(72)}\nPublishing notes.\n`),
500
+ []
501
+ );
419
502
  });
420
503
 
421
504
  it('exempts fenced examples, exactly as the adopter tier does', () => {
422
- const fenced = `${PLAIN}\n\`\`\`sh\n# historical: npm link @widgetic/api-sdk\n\`\`\`\n`;
505
+ const fenced = `${linkingSection(72)}\n\`\`\`sh\n# historical: npm run ldt after every install\n\`\`\`\n`;
423
506
  assert.deepEqual(readmeFindings('recorder', 'recorder/README.md', fenced), []);
424
507
  });
425
508
 
426
509
  it('flags the same words when prose carries them rather than a fence', () => {
427
- // The counterpart of the fence test: outside a fence, the words fail.
428
- const proseForm = `${PLAIN}\nHistorical note: npm link @widgetic/api-sdk was how it used to work.\n`;
510
+ // The counterpart of the fence test: outside a fence, the words fail —
511
+ // with the globally-dead lore, which is what the fence above quotes.
512
+ const proseForm = `${linkingSection(72)}\nHistorical note: npm run ldt was how it used to work.\n`;
429
513
  const f = readmeFindings('recorder', 'recorder/README.md', proseForm);
430
514
  assert.equal(f.length, 1);
431
- assert.equal(f[0].kind, 'ldt section drift');
515
+ assert.equal(f[0].kind, 'linked-sibling section drift');
432
516
  });
433
517
  });
434
518