@widgetic/dev-tools 0.3.6 → 0.3.8

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
@@ -10,6 +10,8 @@ reasons matter more than the categories.
10
10
  - **`publish-package.mjs`** (`bin/publish-package.mjs`): the laptop publish for every package. Each package's `publish-to-npm` script only calls this file. It does nothing when the latest commit already wrote the current version. Otherwise it raises the patch, publishes, commits the version files, tags the commit `v` plus the version, and pushes both. ui-sdk also releases the modules, and the tag is pushed after that release. embed-sdk also uploads its CDN file. dev-tools runs its tests before the version changes.
11
11
  - **`publish-all-to-npm`** (`bin/publish-all-to-npm.mjs`): walks the npm packages and runs each package's `publish-to-npm` script.
12
12
  - The README contract no longer checks `recorder` or `__template__`. The linking tier is `embed-sdk` and `ui-sdk`. The adopter tier is the apps that compile sibling source.
13
+ - **`@widgetic/workflows` is a package of the walk.** `workflows` is in `PUBLISHABLE_PACKAGES` (after `widget-creator`, before `embed-sdk` and `ui-sdk`, which bundle it), in the publisher's `PACKAGE_PACKAGES`, and its module changelog (`modules/src/workflows/CHANGELOG.md`) is one of the files `publish-package.mjs` commits for ui-sdk. It is an adopter of the sibling-source README contract and a publisher of the publish-preparation one (`ADOPTER_PACKAGES`, `PUBLISH_PACKAGES`), and `SIBLING_PACKAGES` carries `workflows` so an app can alias its source in dev.
14
+ - **`npm run test:lists`** (`test/package-lists.test.mjs`): compares the four lists that name a package. A package in the walk but not in the publisher stops the walk part-way, after earlier packages were published; one in the publisher but not in the walk is only ever published by hand; one missing from the sibling layout throws in an app that selects it. The test fails on each, naming the file that needs the name.
13
15
 
14
16
  ### Changed
15
17
 
package/README.md CHANGED
@@ -25,6 +25,14 @@ fixtures:
25
25
  tiny range test that fails closed on shapes it does not parse)
26
26
  (`npm run test:peers`).
27
27
 
28
+ A package that is new to the `Frontend/` checkouts is named in four lists that
29
+ do not know about each other: the publish walk (`lib/publish-to-npm.mjs`), the
30
+ publisher (`bin/publish-package.mjs`), the sibling layout
31
+ (`lib/frontend-layout.mjs`) and the README contract
32
+ (`lib/readme-contract.mjs`). `npm run test:lists` compares them, so a package
33
+ added to one and forgotten in another fails there, naming the file that needs
34
+ it, instead of stopping a walk part-way or being published only by hand.
35
+
28
36
  ## Why this is a published package
29
37
 
30
38
  `check-runtime-deps` used to live twice: once inside `@widgetic/design-system` and
@@ -169,7 +177,7 @@ single place to land. `check-readme-contracts` turns that into a test:
169
177
  every adopter's sibling-source section must carry [the canonical
170
178
  sentences](lib/readme-contract.mjs), in order, with no link-era
171
179
  instructions in prose. The packages that publish to the registry (`chat`,
172
- `file-browser`) must also carry [the canonical
180
+ `file-browser`, `workflows`) must also carry [the canonical
173
181
  publish-preparation sentences](lib/readme-contract.mjs) — package the
174
182
  tarball, publish, and have every consumer refresh its lockfile in the same
175
183
  commit as its version bump. Run it as `npm run check:readme` here, or
@@ -337,7 +345,7 @@ From `dev-tools`, walk every package:
337
345
  npm run publish-all-to-npm
338
346
  ```
339
347
 
340
- The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `embed-sdk` and `ui-sdk`. `site` is not in it.
348
+ The walk is `api-sdk`, `cache-layer`, `design-system`, `dev-tools`, `canvas`, `chat`, `editor`, `file-browser`, `widget-creator`, `workflows`, `embed-sdk` and `ui-sdk`. `site` is not in it. These are the npm packages. The API SDK for Python, Ruby, C#, Java, PHP and Go is published from `api-gateway-service` with `scripts/publish-public-sdks.sh`, not by this walk.
341
349
 
342
350
  ## Releasing
343
351
 
@@ -7,8 +7,10 @@
7
7
  * tests before the version changes. Every other package builds, or packages,
8
8
  * then publishes.
9
9
  *
10
- * The script does nothing when the latest commit is the one that wrote the
11
- * current package.json version. Otherwise it raises the patch, publishes,
10
+ * The script fetches origin first. When that branch has commits this checkout
11
+ * does not, it merges them. A conflict stops the publish. It does nothing when
12
+ * the latest commit is the one that wrote the current package.json version.
13
+ * Otherwise it raises the patch, publishes,
12
14
  * commits the version files, tags that commit v plus the version, and pushes
13
15
  * the commit and the tag.
14
16
  */
@@ -21,7 +23,7 @@ const packageDir = process.cwd();
21
23
  const packageName = basename(packageDir);
22
24
 
23
25
  const BUILD_PACKAGES = new Set(['api-sdk', 'cache-layer', 'design-system']);
24
- const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator']);
26
+ const PACKAGE_PACKAGES = new Set(['canvas', 'chat', 'editor', 'file-browser', 'widget-creator', 'workflows']);
25
27
 
26
28
  /**
27
29
  * Run a command and stop the publish when it fails.
@@ -72,7 +74,12 @@ function versionCommitIsHead(version) {
72
74
  */
73
75
  function commitVersion(paths, detail) {
74
76
  const version = readVersion();
75
- const present = paths.filter((path) => existsSync(join(packageDir, path)));
77
+ // A path the repository ignores (dev-tools keeps no lockfile) cannot be added, and `git add` would stop the publish.
78
+ const present = paths.filter(
79
+ (path) =>
80
+ existsSync(join(packageDir, path)) &&
81
+ spawnSync('git', ['check-ignore', '-q', '--', path], { cwd: packageDir }).status !== 0
82
+ );
76
83
  run('git', ['add', '--', ...present]);
77
84
  run('git', ['commit', '-m', `chore: publish ${version}`, '-m', detail]);
78
85
  }
@@ -95,6 +102,53 @@ function publishToNpm() {
95
102
  run('npm', ['publish', '--ignore-scripts', '--access', access]);
96
103
  }
97
104
 
105
+ /**
106
+ * Bring in commits that landed on the upstream branch before this publish.
107
+ *
108
+ * A clean fast-forward or a merge without conflicts continues. A conflict is
109
+ * left unresolved on purpose: the script cannot tell which side of a content
110
+ * conflict should be the code that gets published, so it aborts the merge and
111
+ * stops.
112
+ */
113
+ function pullRemoteCommits() {
114
+ console.log(`[publish-package] ${packageName}: checking origin for commits this checkout does not have`);
115
+ run('git', ['fetch', 'origin']);
116
+ const upstreamResult = spawnSync('git', ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}'], {
117
+ cwd: packageDir,
118
+ encoding: 'utf8'
119
+ });
120
+ const upstream = (upstreamResult.stdout || '').trim();
121
+ if (upstreamResult.status !== 0 || upstream === '') {
122
+ console.error(`[publish-package] ${packageName}: this branch does not track an upstream. Set it before publishing.`);
123
+ process.exit(1);
124
+ }
125
+ const behind = gitOutput(['rev-list', '--count', `HEAD..${upstream}`]);
126
+ if (behind === '0') return;
127
+
128
+ const dirty = gitOutput(['status', '--porcelain']);
129
+ if (dirty !== '') {
130
+ console.error(`[publish-package] ${packageName}: ${upstream} has ${behind} commit(s) to merge, and this checkout has uncommitted files. Commit or stash them first.`);
131
+ console.error(gitOutput(['log', '--oneline', `HEAD..${upstream}`]));
132
+ process.exit(1);
133
+ }
134
+
135
+ console.log(`[publish-package] ${packageName}: merging ${behind} commit(s) from ${upstream}`);
136
+ console.log(gitOutput(['log', '--oneline', `HEAD..${upstream}`]));
137
+ const merge = spawnSync('git', ['merge', '--no-edit', upstream], {
138
+ cwd: packageDir,
139
+ stdio: 'inherit'
140
+ });
141
+ if (merge.status === 0) return;
142
+
143
+ const conflicts = gitOutput(['diff', '--name-only', '--diff-filter=U']);
144
+ console.error(`[publish-package] ${packageName}: merge stopped on conflicts. The publish does not choose a side.`);
145
+ if (conflicts) console.error(conflicts);
146
+ spawnSync('git', ['merge', '--abort'], { cwd: packageDir, stdio: 'inherit' });
147
+ process.exit(merge.status ?? 1);
148
+ }
149
+
150
+ pullRemoteCommits();
151
+
98
152
  const currentVersion = readVersion();
99
153
  if (versionCommitIsHead(currentVersion)) {
100
154
  console.log(`[publish-package] ${packageName}: no commits since ${currentVersion}. Nothing to publish.`);
@@ -162,7 +216,8 @@ if (BUILD_PACKAGES.has(packageName)) {
162
216
  'modules/package-lock.json',
163
217
  'modules/src/composition-editor/CHANGELOG.md',
164
218
  'modules/src/file-browser/CHANGELOG.md',
165
- 'modules/src/widget-creator/CHANGELOG.md'
219
+ 'modules/src/widget-creator/CHANGELOG.md',
220
+ 'modules/src/workflows/CHANGELOG.md'
166
221
  ],
167
222
  '- Record the package patch and the modules patch that were just published'
168
223
  );
@@ -81,7 +81,8 @@ export const SIBLING_PACKAGES = {
81
81
  },
82
82
  // `dir` was `props-editor` (see older configs — and dangling symlinks).
83
83
  editor: { dir: 'editor', lib: 'src/lib' },
84
- 'file-browser': { dir: 'file-browser', lib: 'src/lib' }
84
+ 'file-browser': { dir: 'file-browser', lib: 'src/lib' },
85
+ workflows: { dir: 'workflows', lib: 'src/lib' }
85
86
  };
86
87
 
87
88
  /**
@@ -19,6 +19,7 @@ export const PUBLISHABLE_PACKAGES = [
19
19
  { dir: 'editor', script: 'publish-to-npm' },
20
20
  { dir: 'file-browser', script: 'publish-to-npm' },
21
21
  { dir: 'widget-creator', script: 'publish-to-npm' },
22
+ { dir: 'workflows', script: 'publish-to-npm' },
22
23
  { dir: 'embed-sdk', script: 'publish-to-npm' },
23
24
  { dir: 'ui-sdk', script: 'publish-to-npm' }
24
25
  ];
@@ -62,7 +62,8 @@ export const ADOPTER_PACKAGES = [
62
62
  'editor',
63
63
  'file-browser',
64
64
  'site',
65
- 'widget-creator'
65
+ 'widget-creator',
66
+ 'workflows'
66
67
  ];
67
68
 
68
69
  /**
@@ -80,8 +81,13 @@ export const CANONICAL_PUBLISH_SENTENCES = [
80
81
  'A consumer that skips the lockfile refresh keeps resolving the old version, so the version bump and the lockfile refresh land as one commit.'
81
82
  ];
82
83
 
83
- /** The packages whose READMEs must carry the publish-preparation section. */
84
- export const PUBLISH_PACKAGES = ['chat', 'file-browser'];
84
+ /**
85
+ * The packages whose READMEs must carry the publish-preparation section.
86
+ * `workflows` joined it from its first commit: its first release is by hand
87
+ * and its consumers (the site, the ui-sdk module) bump it in lockstep, which is
88
+ * the discipline these sentences teach.
89
+ */
90
+ export const PUBLISH_PACKAGES = ['chat', 'file-browser', 'workflows'];
85
91
 
86
92
  /**
87
93
  * The canonical linked-sibling prose, for the packages in
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@widgetic/dev-tools",
3
- "version": "0.3.6",
3
+ "version": "0.3.8",
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": {
@@ -44,7 +44,8 @@
44
44
  "test:readme": "node --test test/readme-contract.test.mjs",
45
45
  "test:peers": "node --test test/lockfile-peers.test.mjs",
46
46
  "test:publish": "node --test test/publish-to-npm.test.mjs",
47
- "test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links && npm run test:readme && npm run test:peers && npm run test:publish",
47
+ "test:lists": "node --test test/package-lists.test.mjs",
48
+ "test": "npm run check:deps && npm run test:deps && npm run test:vite && npm run test:layout && npm run test:links && npm run test:readme && npm run test:peers && npm run test:publish && npm run test:lists",
48
49
  "publish-to-npm": "node bin/publish-package.mjs",
49
50
  "publish-all-to-npm": "node bin/publish-all-to-npm.mjs",
50
51
  "prepublishOnly": "npm test"
@@ -45,12 +45,13 @@ test('the design-system table expands to every subpath plus the index', () => {
45
45
 
46
46
  test('entry packages alias to their entry file, lib packages to their tree', () => {
47
47
  const aliases = buildSiblingAliases(FRONTEND, {
48
- packages: ['api-sdk', 'cache-layer', 'chat', 'file-browser']
48
+ packages: ['api-sdk', 'cache-layer', 'chat', 'file-browser', 'workflows']
49
49
  });
50
50
  assert.equal(aliases['@widgetic/api-sdk'], `${FRONTEND}/api-sdk/src/index.ts`);
51
51
  assert.equal(aliases['@widgetic/cache-layer'], `${FRONTEND}/cache-layer/src/index.ts`);
52
52
  assert.equal(aliases['@widgetic/chat'], `${FRONTEND}/chat/src/lib`);
53
53
  assert.equal(aliases['@widgetic/file-browser'], `${FRONTEND}/file-browser/src/lib`);
54
+ assert.equal(aliases['@widgetic/workflows'], `${FRONTEND}/workflows/src/lib`);
54
55
  });
55
56
 
56
57
  test('a selection without design-system emits no design-system aliases', () => {
@@ -0,0 +1,89 @@
1
+ import { test } from 'node:test';
2
+ import assert from 'node:assert/strict';
3
+ import { readFileSync } from 'node:fs';
4
+ import { resolve } from 'node:path';
5
+ import { fileURLToPath } from 'node:url';
6
+ import { PUBLISHABLE_PACKAGES } from '../lib/publish-to-npm.mjs';
7
+ import { SIBLING_PACKAGES } from '../lib/frontend-layout.mjs';
8
+ import { PUBLISH_PACKAGES } from '../lib/readme-contract.mjs';
9
+
10
+ /**
11
+ * Four lists in dev-tools name packages, and none of them knows about the
12
+ * others: the walk (`lib/publish-to-npm.mjs`), the publisher
13
+ * (`bin/publish-package.mjs`), the sibling layout (`lib/frontend-layout.mjs`)
14
+ * and the README contract (`lib/readme-contract.mjs`). A new package has to be
15
+ * added to each, and forgetting one fails nowhere at the time of the change:
16
+ *
17
+ * - in the walk but not in the publisher: the walk stops with "is not one of
18
+ * the packages this script publishes" after the earlier packages were
19
+ * already published;
20
+ * - in the publisher but not in the walk: the package is only ever published
21
+ * by hand, and nobody notices a release that never happens;
22
+ * - missing from the sibling layout: an app that selects the package for its
23
+ * dev aliases gets a throw from `siblingPackageRoots`.
24
+ *
25
+ * So the lists are compared here, and a gap names the file that needs the name.
26
+ */
27
+
28
+ const DEV_TOOLS = fileURLToPath(new URL('..', import.meta.url));
29
+ const publisherSource = readFileSync(resolve(DEV_TOOLS, 'bin/publish-package.mjs'), 'utf8');
30
+
31
+ /**
32
+ * The names inside one `const NAME = new Set([...])` literal of the publisher.
33
+ * The publisher runs a publish the moment it is imported, so it is read as
34
+ * text rather than imported.
35
+ *
36
+ * @param {string} setName
37
+ * @returns {string[]}
38
+ */
39
+ function namesInPublisherSet(setName) {
40
+ const match = publisherSource.match(new RegExp(`const ${setName} = new Set\\(\\[([^\\]]*)\\]\\)`));
41
+ assert.ok(
42
+ match,
43
+ `bin/publish-package.mjs no longer declares ${setName} as a Set literal of names. Update this test with it.`
44
+ );
45
+ return [...match[1].matchAll(/'([^']+)'/g)].map((found) => found[1]);
46
+ }
47
+
48
+ /** The packages the publisher builds from their own source, then publishes. */
49
+ const builtFromSource = [...namesInPublisherSet('BUILD_PACKAGES'), ...namesInPublisherSet('PACKAGE_PACKAGES')];
50
+
51
+ /** The packages the publisher gives a branch of their own (`packageName === 'ui-sdk'`). */
52
+ const specialCased = [...publisherSource.matchAll(/packageName === '([^']+)'/g)].map((found) => found[1]);
53
+
54
+ const publisherNames = new Set([...builtFromSource, ...specialCased]);
55
+ const walkNames = new Set(PUBLISHABLE_PACKAGES.map((pkg) => pkg.dir));
56
+
57
+ test('the walk and the publisher name the same packages', () => {
58
+ const inWalkOnly = [...walkNames].filter((name) => !publisherNames.has(name));
59
+ const inPublisherOnly = [...publisherNames].filter((name) => !walkNames.has(name));
60
+ assert.deepEqual(
61
+ inWalkOnly,
62
+ [],
63
+ `in lib/publish-to-npm.mjs but not in bin/publish-package.mjs: the walk would stop part-way, after earlier packages were already published. Add ${inWalkOnly.join(', ')} to BUILD_PACKAGES or PACKAGE_PACKAGES.`
64
+ );
65
+ assert.deepEqual(
66
+ inPublisherOnly,
67
+ [],
68
+ `in bin/publish-package.mjs but not in lib/publish-to-npm.mjs: ${inPublisherOnly.join(', ')} would only ever be published by hand. Add it to PUBLISHABLE_PACKAGES, in dependency order.`
69
+ );
70
+ });
71
+
72
+ test('every package the publisher builds from source has a sibling-layout entry for its directory', () => {
73
+ const directoriesInLayout = new Set(Object.values(SIBLING_PACKAGES).map((entry) => entry.dir));
74
+ const missing = builtFromSource.filter((dir) => !directoriesInLayout.has(dir));
75
+ assert.deepEqual(
76
+ missing,
77
+ [],
78
+ `no SIBLING_PACKAGES entry points at ${missing.join(', ')}. Add one to lib/frontend-layout.mjs so an app can alias that package's source in dev.`
79
+ );
80
+ });
81
+
82
+ test('a package held to the README contract publish section is one the walk publishes', () => {
83
+ const notInWalk = PUBLISH_PACKAGES.filter((dir) => !walkNames.has(dir));
84
+ assert.deepEqual(
85
+ notInWalk,
86
+ [],
87
+ `PUBLISH_PACKAGES in lib/readme-contract.mjs names ${notInWalk.join(', ')}, which lib/publish-to-npm.mjs does not publish.`
88
+ );
89
+ });
@@ -20,6 +20,7 @@ test('the walk calls publish-to-npm in each npm package', () => {
20
20
  'editor:publish-to-npm',
21
21
  'file-browser:publish-to-npm',
22
22
  'widget-creator:publish-to-npm',
23
+ 'workflows:publish-to-npm',
23
24
  'embed-sdk:publish-to-npm',
24
25
  'ui-sdk:publish-to-npm'
25
26
  ]
@@ -271,7 +271,7 @@ npm run llinks
271
271
 
272
272
  describe('the publish contract', () => {
273
273
  it('publishes to exactly the packages that ship a dist tarball', { skip: !DISK_OK }, () => {
274
- assert.deepEqual(PUBLISH_PACKAGES, ['chat', 'file-browser']);
274
+ assert.deepEqual(PUBLISH_PACKAGES, ['chat', 'file-browser', 'workflows']);
275
275
  assert.ok(PUBLISH_PACKAGES.every((p) => ADOPTER_PACKAGES.includes(p)));
276
276
  // Every publisher ships `files: ['dist']` — the sentence that calls
277
277
  // dist the tarball's only content must match manifest reality.