@widgetic/dev-tools 0.2.0 → 0.3.1
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 +90 -18
- package/README.md +114 -35
- package/bin/check-design-system-peers.mjs +53 -0
- package/bin/check-layout-fixtures.mjs +0 -0
- package/bin/check-links-fixtures.mjs +0 -0
- package/bin/check-links.mjs +0 -0
- package/bin/check-readme-contracts-fixtures.mjs +27 -0
- package/bin/check-readme-contracts.mjs +82 -0
- package/lib/frontend-layout.mjs +10 -1
- package/lib/lockfile-peers.mjs +193 -0
- package/lib/readme-contract.d.mts +130 -0
- package/lib/readme-contract.mjs +385 -0
- package/lib/semver-lite.mjs +71 -0
- package/package.json +11 -4
- package/test/frontend-layout.test.mjs +6 -0
- package/test/lockfile-peers.test.mjs +208 -0
- package/test/readme-contract.test.mjs +543 -0
|
@@ -0,0 +1,193 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The lockfile-peers rule, as data — the CLI in `bin/check-design-system-peers.mjs`
|
|
3
|
+
* formats and exits, this module decides what is broken.
|
|
4
|
+
*
|
|
5
|
+
* `@widgetic/design-system` has exactly two sibling-app consumers that resolve
|
|
6
|
+
* it from the registry — `canvas` and `file-browser` — and a range alone cannot
|
|
7
|
+
* keep them coordinated: both declare `^0.5.12`, nothing forces the two
|
|
8
|
+
* lockfiles to move together, and when 0.5.14 published, canvas's lockfile
|
|
9
|
+
* refreshed to it while file-browser's kept promising 0.5.12. Nothing failed —
|
|
10
|
+
* both resolutions satisfy the same range — but the two consumers now pin
|
|
11
|
+
* different component trees, so a shared screen renders with two different
|
|
12
|
+
* designs depending on which app hosts it, and nobody would ever connect the
|
|
13
|
+
* symptom to the split. The fix is the same discipline the README contract
|
|
14
|
+
* enforces for publish prose: the bump lands as one coordinated change, and a
|
|
15
|
+
* machine check fails when it does not.
|
|
16
|
+
*
|
|
17
|
+
* Two rules:
|
|
18
|
+
*
|
|
19
|
+
* version-divergence the peers' lockfiles must resolve the *same*
|
|
20
|
+
* design-system version. "Both satisfy the range" is not
|
|
21
|
+
* the bar; the bar is the same bar.
|
|
22
|
+
*
|
|
23
|
+
* stale-manifest each peer's manifest range must admit the version the
|
|
24
|
+
* design-system checkout carries. This fires when a
|
|
25
|
+
* release leaves the declared range (a 0.6.0 across a
|
|
26
|
+
* `^0.5.12`); npm's caret semantics silently admit
|
|
27
|
+
* every minor, so the range alone can never force the
|
|
28
|
+
* bump.
|
|
29
|
+
*
|
|
30
|
+
* checkout-sync the peers' lockfiles must resolve the version the
|
|
31
|
+
* design-system checkout carries. This is the rule
|
|
32
|
+
* that fires at *every* publish — a version bump in the
|
|
33
|
+
* checkout goes red in both peers until the coordinated
|
|
34
|
+
* lockfile refresh lands, because a caret range would
|
|
35
|
+
* otherwise admit the new version and nothing would
|
|
36
|
+
* force anyone to move.
|
|
37
|
+
*
|
|
38
|
+
* Zero dependencies, plain ESM, injectable-root pure: every function takes the
|
|
39
|
+
* `Frontend/` checkout root, so the fixture suite builds a throwaway checkout,
|
|
40
|
+
* breaks it on purpose, and asserts on the result without touching the real
|
|
41
|
+
* one.
|
|
42
|
+
*/
|
|
43
|
+
|
|
44
|
+
/** The package whose coordination is guarded, unscoped and scoped. */
|
|
45
|
+
export const PACKAGE = 'design-system';
|
|
46
|
+
export const SCOPED = `@widgetic/${PACKAGE}`;
|
|
47
|
+
|
|
48
|
+
/** The sibling apps that resolve the package from the registry, as lockfile pairs. */
|
|
49
|
+
export const PEERS = ['canvas', 'file-browser'];
|
|
50
|
+
|
|
51
|
+
/** The checkout whose version the peers' ranges must admit. */
|
|
52
|
+
export const SOURCE_PACKAGE = 'design-system';
|
|
53
|
+
|
|
54
|
+
import { satisfies } from './semver-lite.mjs';
|
|
55
|
+
|
|
56
|
+
/** Minimal JSON reader that returns `null` instead of throwing. */
|
|
57
|
+
export function readJson(path) {
|
|
58
|
+
try {
|
|
59
|
+
return JSON.parse(readFile(path));
|
|
60
|
+
} catch {
|
|
61
|
+
return null;
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
import { readFileSync as readFile } from 'node:fs';
|
|
66
|
+
|
|
67
|
+
/**
|
|
68
|
+
* The design-system version one peer's lockfile resolves, or `undefined`.
|
|
69
|
+
*
|
|
70
|
+
* @param {string} root The Frontend checkout root.
|
|
71
|
+
* @param {string} pkg The peer's directory name.
|
|
72
|
+
* @returns {string | undefined}
|
|
73
|
+
*/
|
|
74
|
+
export function lockResolved(root, pkg) {
|
|
75
|
+
const lock = readJson(`${root}/${pkg}/package-lock.json`);
|
|
76
|
+
return lock?.packages?.[`node_modules/${SCOPED}`]?.version;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* The design-system range one peer's manifest admits, or `undefined` when the
|
|
81
|
+
* manifest does not declare the dependency at all.
|
|
82
|
+
*
|
|
83
|
+
* @param {string} root The Frontend checkout root.
|
|
84
|
+
* @param {string} pkg The peer's directory name.
|
|
85
|
+
* @returns {string | undefined}
|
|
86
|
+
*/
|
|
87
|
+
export function admittedRange(root, pkg) {
|
|
88
|
+
const manifest = readJson(`${root}/${pkg}/package.json`);
|
|
89
|
+
const deps = manifest?.dependencies ?? {};
|
|
90
|
+
return deps[SCOPED];
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
/**
|
|
94
|
+
* The version the design-system checkout itself carries.
|
|
95
|
+
*
|
|
96
|
+
* @param {string} root The Frontend checkout root.
|
|
97
|
+
* @returns {string | undefined}
|
|
98
|
+
*/
|
|
99
|
+
export function checkoutVersion(root) {
|
|
100
|
+
return readJson(`${root}/${SOURCE_PACKAGE}/package.json`)?.version;
|
|
101
|
+
}
|
|
102
|
+
|
|
103
|
+
/**
|
|
104
|
+
* Find every lockfile-peers violation under `root`.
|
|
105
|
+
*
|
|
106
|
+
* @param {string} root The Frontend checkout root.
|
|
107
|
+
* @returns {{ kind: 'unreadable' | 'unresolved' | 'version-divergence' | 'stale-manifest' | 'checkout-sync', pkg: string, detail: string, fix: string }[]}
|
|
108
|
+
*/
|
|
109
|
+
export function collectPeersProblems(root) {
|
|
110
|
+
const problems = [];
|
|
111
|
+
const resolved = new Map();
|
|
112
|
+
|
|
113
|
+
for (const pkg of PEERS) {
|
|
114
|
+
const lock = readJson(`${root}/${pkg}/package-lock.json`);
|
|
115
|
+
if (!lock) {
|
|
116
|
+
problems.push({
|
|
117
|
+
kind: 'unreadable',
|
|
118
|
+
pkg,
|
|
119
|
+
detail: 'no readable package-lock.json',
|
|
120
|
+
fix: `run npm install in ${pkg}/ so the lockfile exists`
|
|
121
|
+
});
|
|
122
|
+
continue;
|
|
123
|
+
}
|
|
124
|
+
const version = lockResolved(root, pkg);
|
|
125
|
+
if (!version) {
|
|
126
|
+
problems.push({
|
|
127
|
+
kind: 'unresolved',
|
|
128
|
+
pkg,
|
|
129
|
+
detail: `the lockfile has no node_modules/${SCOPED} entry`,
|
|
130
|
+
fix: `run npm install in ${pkg}/ so ${SCOPED} resolves into the lockfile`
|
|
131
|
+
});
|
|
132
|
+
continue;
|
|
133
|
+
}
|
|
134
|
+
resolved.set(pkg, version);
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
// Divergence needs at least two healthy resolutions to compare.
|
|
138
|
+
const versions = [...new Set(resolved.values())];
|
|
139
|
+
if (versions.length > 1) {
|
|
140
|
+
const detail = PEERS.filter((p) => resolved.has(p))
|
|
141
|
+
.map((p) => `${p} ${resolved.get(p)}`)
|
|
142
|
+
.join(', ');
|
|
143
|
+
problems.push({
|
|
144
|
+
kind: 'version-divergence',
|
|
145
|
+
pkg: PEERS.join(' + '),
|
|
146
|
+
detail: `the peers' lockfiles resolve different ${SCOPED} versions: ${detail}`,
|
|
147
|
+
fix: `bump/refresh both lockfiles as one coordinated change — run npm update ${SCOPED} in each peer, land them as one commit pair`
|
|
148
|
+
});
|
|
149
|
+
}
|
|
150
|
+
|
|
151
|
+
const checkout = checkoutVersion(root);
|
|
152
|
+
if (checkout) {
|
|
153
|
+
for (const pkg of PEERS) {
|
|
154
|
+
const version = resolved.get(pkg);
|
|
155
|
+
if (version && version !== checkout) {
|
|
156
|
+
problems.push({
|
|
157
|
+
kind: 'checkout-sync',
|
|
158
|
+
pkg,
|
|
159
|
+
detail: `the design-system checkout carries ${checkout} but ${pkg}'s lockfile resolves ${version}`,
|
|
160
|
+
fix: `run npm update ${SCOPED} in ${pkg}/ and land both peers' lockfiles as one coordinated commit with the design-system release`
|
|
161
|
+
});
|
|
162
|
+
}
|
|
163
|
+
const range = admittedRange(root, pkg);
|
|
164
|
+
if (range === undefined) continue;
|
|
165
|
+
if (!satisfies(checkout, range)) {
|
|
166
|
+
problems.push({
|
|
167
|
+
kind: 'stale-manifest',
|
|
168
|
+
pkg,
|
|
169
|
+
detail: `the manifest range ${range} does not admit the design-system checkout version ${checkout}`,
|
|
170
|
+
fix: `bump ${SCOPED} in ${pkg}/package.json to admit ${checkout} and refresh its lockfile — together with the other peer`
|
|
171
|
+
});
|
|
172
|
+
}
|
|
173
|
+
}
|
|
174
|
+
}
|
|
175
|
+
|
|
176
|
+
return problems;
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
/**
|
|
180
|
+
* Render problems the way the other dev-tools checks do: one indented
|
|
181
|
+
* finding with its fix, ready to paste into a terminal.
|
|
182
|
+
*
|
|
183
|
+
* @param {ReturnType<typeof collectPeersProblems>} problems
|
|
184
|
+
* @returns {string}
|
|
185
|
+
*/
|
|
186
|
+
export function formatPeersProblems(problems) {
|
|
187
|
+
return problems
|
|
188
|
+
.map(
|
|
189
|
+
({ kind, pkg, detail, fix }) =>
|
|
190
|
+
` ${pkg}: ${kind}\n ${detail}\n → ${fix}`
|
|
191
|
+
)
|
|
192
|
+
.join('\n');
|
|
193
|
+
}
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Types for the README contract (`readme-contract.mjs`). Hand-written,
|
|
3
|
+
* dependency-free — same rules as `check-links.d.mts` beside it.
|
|
4
|
+
*/
|
|
5
|
+
|
|
6
|
+
/**
|
|
7
|
+
* The canonical sibling-source prose, sentence by sentence. An adopter must
|
|
8
|
+
* carry every sentence verbatim, in order; see {@link readmeFindings}.
|
|
9
|
+
*/
|
|
10
|
+
export const CANONICAL_SENTENCES: string[];
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* The canonical publish-preparation prose, for the packages in
|
|
14
|
+
* {@link PUBLISH_PACKAGES}. Same matching rules as the sibling sentences.
|
|
15
|
+
*/
|
|
16
|
+
export const CANONICAL_PUBLISH_SENTENCES: string[];
|
|
17
|
+
|
|
18
|
+
/** The packages whose READMEs must carry the canonical section. */
|
|
19
|
+
export const ADOPTER_PACKAGES: string[];
|
|
20
|
+
|
|
21
|
+
/** The packages whose READMEs must also carry the publish section. */
|
|
22
|
+
export const PUBLISH_PACKAGES: string[];
|
|
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
|
+
|
|
33
|
+
/**
|
|
34
|
+
* The packages that consume a sibling through a hand-made link to its built
|
|
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.
|
|
39
|
+
*/
|
|
40
|
+
export const LINKING_PACKAGES: string[];
|
|
41
|
+
|
|
42
|
+
/** Every package the check reads, in tier order. */
|
|
43
|
+
export const CHECKED_PACKAGES: string[];
|
|
44
|
+
|
|
45
|
+
/**
|
|
46
|
+
* One problem the README contract found in a Frontend checkout. Same fields
|
|
47
|
+
* as the link-doctor's problems, so reporters can treat the two checks alike.
|
|
48
|
+
*/
|
|
49
|
+
export interface ReadmeFinding {
|
|
50
|
+
/**
|
|
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.
|
|
62
|
+
* - `publish section missing` — a publishing package's README has no
|
|
63
|
+
* canonical publish-preparation section.
|
|
64
|
+
* - `publish section drift` — the section exists but its wording diverges
|
|
65
|
+
* from {@link CANONICAL_PUBLISH_SENTENCES}.
|
|
66
|
+
*/
|
|
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';
|
|
74
|
+
/** The package directory under `Frontend/` that owns the finding. */
|
|
75
|
+
pkg: string;
|
|
76
|
+
/** What is wrong, README-relative. */
|
|
77
|
+
detail: string;
|
|
78
|
+
/** The action that repairs it. */
|
|
79
|
+
fix: string;
|
|
80
|
+
}
|
|
81
|
+
|
|
82
|
+
/**
|
|
83
|
+
* The stale link-era instructions present in one README's prose (fenced code
|
|
84
|
+
* blocks excluded), as readable labels. Word-bounded, so `pnpm link` does not
|
|
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.
|
|
91
|
+
*/
|
|
92
|
+
export declare function staleInstructionHits(
|
|
93
|
+
text: string,
|
|
94
|
+
tier?: 'adopter' | 'linking'
|
|
95
|
+
): string[];
|
|
96
|
+
|
|
97
|
+
/**
|
|
98
|
+
* Find what one package's README violates, by tier: an adopter must carry the
|
|
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.
|
|
103
|
+
*/
|
|
104
|
+
export declare function readmeFindings(
|
|
105
|
+
pkg: string,
|
|
106
|
+
readmePath: string,
|
|
107
|
+
raw: string
|
|
108
|
+
): ReadmeFinding[];
|
|
109
|
+
|
|
110
|
+
/** Options for {@link collectReadmeDrift}. */
|
|
111
|
+
export interface CollectReadmeDriftOptions {
|
|
112
|
+
/**
|
|
113
|
+
* Package directories to check; defaults to {@link CHECKED_PACKAGES}. The
|
|
114
|
+
* fixture suite overrides this to prove the list is honored. Replaces the
|
|
115
|
+
* former `adopters` option, which set a value on throws rather than
|
|
116
|
+
* silently checking the defaults instead.
|
|
117
|
+
*/
|
|
118
|
+
packages?: string[];
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
/**
|
|
122
|
+
* Collect every README finding under a Frontend checkout: each adopter's
|
|
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.
|
|
126
|
+
*/
|
|
127
|
+
export declare function collectReadmeDrift(
|
|
128
|
+
frontendRoot: string,
|
|
129
|
+
options?: CollectReadmeDriftOptions
|
|
130
|
+
): { packages: string[]; findings: ReadmeFinding[] };
|