Skip to content

Commit 87bd93d

Browse files
committed
tooling(cutover): check:undeclared-dep-imports ledgers the objectui Console's bundled src (objectstack#25803)
Bill item 20: @object-ui/console imports @objectstack/spec and @objectstack/client from src/** with both declared as devDependencies, by design: it publishes a prebuilt SPA (files = dist + plugin.* + README). A new ledger kind, bundled-not-shipped, covers a package's whole src directory and re-reads its manifest every run: the row goes stale the day files ships src or disappears. Two rows, five synthetic cases. Co-Authored-By: Claude <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01CUXv64KLMfYv3ia2sWi6te
1 parent 8b3a99f commit 87bd93d

1 file changed

Lines changed: 76 additions & 4 deletions

File tree

‎scripts/check-undeclared-dep-imports.mjs‎

Lines changed: 76 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -323,9 +323,49 @@ const LEDGER = [
323323
+ 'the same seam for exactly that reason — so declaring it would reverse a stance the tree '
324324
+ 'states, not repair an omission.',
325325
},
326+
// The objectui Console (imported as ui/ at the cutover, #25752 bill item 20). Two rows,
327+
// one per dependency, each covering the package's whole `src/` directory: the evidence
328+
// is the manifest, so it is per package, not per call site.
329+
{
330+
pkg: '@object-ui/console',
331+
dep: '@objectstack/spec',
332+
file: 'ui/apps/console/src',
333+
kind: 'bundled-not-shipped',
334+
why:
335+
'@object-ui/console publishes a prebuilt SPA: `files` is dist + plugin.{ts,js,d.ts} + README, '
336+
+ 'and `exports` resolves to plugin.js, so src/** is bundled by vite into dist and never reaches '
337+
+ 'an installing consumer. Its only runtime dependency is @object-ui/sdui-parser; @objectstack/spec '
338+
+ 'is a build input, which is what devDependencies records.',
339+
},
340+
{
341+
pkg: '@object-ui/console',
342+
dep: '@objectstack/client',
343+
file: 'ui/apps/console/src',
344+
kind: 'bundled-not-shipped',
345+
why:
346+
'Same package, same evidence: the Console src imports @objectstack/client types for its own '
347+
+ 'pages, vite bundles src/** into dist, and the published files (dist + plugin.* + README) carry '
348+
+ 'no src for a consumer to resolve the import from.',
349+
},
326350
];
327351

328-
const LEDGER_KINDS = new Set(['optional-runtime-probe', 'type-only']);
352+
/**
353+
* The ledger kinds. `bundled-not-shipped` is the one keyed by DIRECTORY: its row
354+
* names a package's whole `src/` (never a file), and its evidence is that package's
355+
* manifest, re-read on every run -- `files` must exist and ship nothing under `src/`.
356+
* The day `files` starts shipping source, or is deleted (everything ships), the row
357+
* is stale and the imports are a consumer's problem again.
358+
*/
359+
const LEDGER_KINDS = new Set(['optional-runtime-probe', 'type-only', 'bundled-not-shipped']);
360+
361+
/** Does a manifest's `files` keep `src/**` out of the published tarball? */
362+
export function shipsNoSource(manifest) {
363+
if (!Array.isArray(manifest?.files)) return false;
364+
return manifest.files.every((entry) => {
365+
const e = String(entry).replace(/^\.\//, '');
366+
return e !== 'src' && !e.startsWith('src/') && !e.includes('*');
367+
});
368+
}
329369

330370
// ---------------------------------------------------------------------------
331371
// Workspace discovery
@@ -539,13 +579,15 @@ export function sweep(root) {
539579
// ---------------------------------------------------------------------------
540580
// Ledger reconciliation
541581

542-
export function reconcile(findings, ledger) {
582+
export function reconcile(findings, ledger, manifests = new Map()) {
543583
const unledgered = [];
544584
const staleRows = [];
545585
const matched = new Set();
586+
const covers = (r, f) => r.pkg === f.pkg && r.dep === f.dep
587+
&& (r.kind === 'bundled-not-shipped' ? f.file.startsWith(`${r.file}/`) : r.file === f.file);
546588

547589
for (const finding of findings) {
548-
const row = ledger.find((r) => r.pkg === finding.pkg && r.dep === finding.dep && r.file === finding.file);
590+
const row = ledger.find((r) => covers(r, finding));
549591
if (row === undefined) { unledgered.push(finding); continue; }
550592
matched.add(row);
551593
if (row.kind === 'optional-runtime-probe' && finding.form !== 'dynamic') {
@@ -568,6 +610,15 @@ export function reconcile(findings, ledger) {
568610
}
569611
}
570612
for (const row of ledger) {
613+
if (row.kind === 'bundled-not-shipped' && matched.has(row) && !shipsNoSource(manifests.get(row.pkg))) {
614+
staleRows.push({
615+
row,
616+
why: `${row.pkg}'s manifest no longer keeps src/** out of the tarball (\`files\` is `
617+
+ `${JSON.stringify(manifests.get(row.pkg)?.files ?? null)}). A \`bundled-not-shipped\` row certifies `
618+
+ 'that no consumer ever resolves these imports; a published src makes every one of them real. '
619+
+ 'Declare the dependencies, or restore a `files` list that ships the bundle only.',
620+
});
621+
}
571622
if (matched.has(row)) continue;
572623
staleRows.push({
573624
row,
@@ -585,6 +636,9 @@ function ledgerShapeProblems(ledger) {
585636
if (!LEDGER_KINDS.has(row.kind)) problems.push(`${at}: unknown kind \`${row.kind}\``);
586637
if (typeof row.why !== 'string' || row.why.length < 40) problems.push(`${at}: \`why\` must state the reason`);
587638
if (typeof row.file !== 'string' || !row.file.includes('/')) problems.push(`${at}: \`file\` must be a repo-relative path`);
639+
if (row.kind === 'bundled-not-shipped' && !/\/src$/.test(String(row.file))) {
640+
problems.push(`${at}: a \`bundled-not-shipped\` row names the package's whole \`src\` directory, never a file`);
641+
}
588642
}
589643
return problems;
590644
}
@@ -656,7 +710,8 @@ function main() {
656710
const floor = floorProblems(result);
657711
if (floor !== null) refuse(floor);
658712

659-
const { unledgered, staleRows } = reconcile(result.findings, LEDGER);
713+
const manifests = new Map(result.packages.map((p) => [p.manifest.name, p.manifest]));
714+
const { unledgered, staleRows } = reconcile(result.findings, LEDGER, manifests);
660715

661716
if (staleRows.length > 0) {
662717
console.error(`✗ check:undeclared-dep-imports: ${staleRows.length} stale ledger row(s)\n`);
@@ -1038,6 +1093,23 @@ function selfTest() {
10381093
ledgerShapeProblems([{ ...row, kind: 'made-up' }]).length === 1
10391094
&& ledgerShapeProblems([{ ...row, why: 'short' }]).length === 1
10401095
&& ledgerShapeProblems([row]).length === 0);
1096+
const spaRow = { pkg: '@objectstack/p', dep: '@objectstack/d', file: 'packages/p/src', kind: 'bundled-not-shipped', why: 'z'.repeat(50) };
1097+
const spaManifests = new Map([['@objectstack/p', { files: ['dist', 'plugin.js', 'README.md'] }]]);
1098+
t('LEDGER — a `bundled-not-shipped` row covers every form under its src directory',
1099+
reconcile([{ ...dyn, form: 'static' }, { ...typeFinding, file: 'packages/p/src/deep/b.ts' }], [spaRow], spaManifests)
1100+
.unledgered.length === 0
1101+
&& reconcile([{ ...dyn, form: 'static' }], [spaRow], spaManifests).staleRows.length === 0);
1102+
t('LEDGER — a `bundled-not-shipped` row does not cover another package\'s src',
1103+
reconcile([{ ...dyn, pkg: '@objectstack/q', file: 'packages/q/src/a.ts' }], [spaRow], spaManifests)
1104+
.unledgered.length === 1);
1105+
t('LEDGER — a manifest that starts shipping src reds the `bundled-not-shipped` row',
1106+
reconcile([dyn], [spaRow], new Map([['@objectstack/p', { files: ['dist', 'src'] }]])).staleRows.length === 1
1107+
&& reconcile([dyn], [spaRow], new Map([['@objectstack/p', { files: ['dist', 'src/**/*.ts'] }]])).staleRows.length === 1);
1108+
t('LEDGER — a manifest with no `files` (everything ships) reds the `bundled-not-shipped` row',
1109+
reconcile([dyn], [spaRow], new Map([['@objectstack/p', {}]])).staleRows.length === 1);
1110+
t('LEDGER — a `bundled-not-shipped` row naming a file instead of the src directory is refused',
1111+
ledgerShapeProblems([{ ...spaRow, file: 'packages/p/src/a.ts' }]).length === 1
1112+
&& ledgerShapeProblems([spaRow]).length === 0);
10411113
t('LEDGER — the shipped ledger is well formed', ledgerShapeProblems(LEDGER).length === 0);
10421114

10431115
// ── the declared watch hints stay equal to the real population ────────

0 commit comments

Comments
 (0)