@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.
@@ -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[] };