Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion docs/contributing/pull-requests.md
Original file line number Diff line number Diff line change
Expand Up @@ -164,7 +164,10 @@ ESLint on the changed files, the changed test files alone, `pnpm check:knowledge
and `pnpm check:changesets`, in minutes. It is not CI-equivalent: it builds
nothing, leaves out dependent packages, the tests the change reaches through an
import, and the guards, and it ends with "run `pnpm preflight` before you flip"
rather than "ready to flip".
rather than "ready to flip". When every typecheck error names a workspace
package's build output (`@astryxdesign/<package>/built` or a `dist` path), the
typecheck reports SKIP ("workspace builds missing; run `pnpm build` first"),
and the run ends "not checked" rather than a pass; any other error fails it.

Preflight is not a required step. It reproduces the pre-review checklist and
CI's checks; it does not reproduce a reviewer's judgment.
Expand Down
84 changes: 76 additions & 8 deletions scripts/preflight.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@
* locally before the change is marked ready.
* @input The committed change (`HEAD` against its merge base with `--base
* <ref>`, default `origin/main`), `--browser`, `--quick` (the
* changed packages, files and tests alone; not CI's scope), and `--wrap
* changed packages, files and tests alone; not CI's scope; a typecheck
* that fails only on missing workspace builds reports SKIP), and `--wrap
* <command>` (or `PREFLIGHT_WRAP`): a command that runs each heavy step as
* `<command> <build|test|knowledge> <step command...>`, such as a machine's
* job limiter. A working tree with uncommitted changes stops the run.
Expand Down Expand Up @@ -59,7 +60,7 @@ export function planChecks({
chromiumScope,
quick = false,
}) {
if (quick) return quickChecks({scope, mergeBase, changed});
if (quick) return quickChecks({scope, mergeBase, changed, tmp});
const at = name => path.join(tmp, name);
const checks = [];
const specOnly = scope.specOnly || scope.timesOnly;
Expand Down Expand Up @@ -387,7 +388,7 @@ function present(files) {
* not CI's scope: no build, no dependent package, no test the change reaches
* through an import, and no guard.
*/
function quickChecks({scope, mergeBase, changed}) {
function quickChecks({scope, mergeBase, changed, tmp}) {
const specOnly = scope.specOnly || scope.timesOnly;
const typechecks = !specOnly && !scope.docsiteOnly && !scope.toolingOnly;
const linted = present(changed.filter(file => LINTED.test(file)));
Expand All @@ -414,6 +415,12 @@ function quickChecks({scope, mergeBase, changed}) {
'run',
'typecheck',
],
// Without a build, a package that reads a workspace package's
// build output fails to typecheck: that is not this change's
// error, so the check reports it as skipped.
stdout: path.join(tmp, 'typecheck.log'),
tee: true,
skipWhen: missingBuilds,
},
],
}
Expand Down Expand Up @@ -465,6 +472,27 @@ function quickChecks({scope, mergeBase, changed}) {
];
}

const MISSING_BUILDS =
'skipped, workspace builds missing; run `pnpm build` first';

/** A missing module that is a workspace package's build output. */
const BUILD_OUTPUT =
/error TS2307: Cannot find module '(?:@astryxdesign\/[^']+\/built(?:\/[^']*)?|[^']*\/dist(?:\/[^']*)?)'/;

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: the …/dist… branch also matches third-party specifiers, for example 'next/dist/shared/lib/image-config', which four docsite tests import, so a missing third-party module reached through a dist subpath would SKIP. The docsite is outside the quick typecheck today; anchoring the branch to relative specifiers (starting ./ or ../) keeps it to workspace builds.


/**
* Why a failed typecheck is skipped, or null: every TypeScript error names a
* workspace package's build output (`@astryxdesign/<pkg>/built` or a `dist`
* path) that a run without `pnpm build` lacks.
* @param {string} text the typecheck's output
* @returns {string | null}
*/
export function missingBuilds(text) {
const errors = text.split('\n').filter(line => /error TS\d+/.test(line));
if (errors.length === 0 || !errors.every(line => BUILD_OUTPUT.test(line)))
Comment on lines +490 to +491

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: only error TS lines are classified, but the exit code covers every package in the recursive run. Built-only TS2307 from one package plus a non-TypeScript failure from another (tsc out of memory, a failing step in a typecheck chain) gives SKIP "workspace builds missing". Skipping only when every failing package in pnpm's [ERROR] <package> summary printed build-output errors would keep "any other error fails it" true.

return null;
return MISSING_BUILDS;
}

function skip(id, why) {
return {id, commands: [], skip: why};
}
Expand Down Expand Up @@ -516,7 +544,27 @@ export function runChecks(checks, {exec, wrap = [], now = Date.now} = {}) {
}
if (command.kind !== 'light' && wrap.length)
argv = [...wrap, command.kind, ...argv];
const code = exec(argv, {env: command.env, stdout: command.stdout});
const code = exec(argv, {
env: command.env,
stdout: command.stdout,
tee: command.tee,
});
const skipped =
code !== 0 && command.skipWhen && command.stdout
? command.skipWhen(
fs.existsSync(command.stdout)
? fs.readFileSync(command.stdout, 'utf8')
: '',
)
: null;
if (skipped)
return {
id: check.id,
result: 'SKIP',
note: skipped,
failed: null,
seconds: Math.round((now() - started) / 1000),
};
if (code !== 0)
return {
id: check.id,
Expand Down Expand Up @@ -553,13 +601,20 @@ export function formatTable(rows, {quick = false} = {}) {
lines.push('', 'Failing commands:');
for (const row of failed) lines.push(` ${row.id}: ${row.failed}`);
}
// A typecheck skipped for missing builds checked nothing, so the verdict
// says so instead of reading as a pass.
const unbuilt = rows.filter(
row => row.result === 'SKIP' && row.note === MISSING_BUILDS,
);
lines.push(
'',
failed.length
? `not ready: ${failed.length}`
: quick
? 'quick checks pass; run `pnpm preflight` before you flip'
: 'ready to flip',
: unbuilt.length
? `not checked: ${unbuilt.map(row => row.id).join(', ')} (workspace builds missing); run \`pnpm build\`, then run again before you flip`
: quick
? 'quick checks pass; run `pnpm preflight` before you flip'
: 'ready to flip',
quick
? 'Quick mode is not CI-equivalent: it skips the build, dependent packages, the tests the change reaches and the guards.'
: NOT_RUN,
Expand Down Expand Up @@ -675,8 +730,21 @@ async function main(argv) {
});
const rows = runChecks(checks, {
wrap,
exec(command, {env, stdout}) {
exec(command, {env, stdout, tee}) {
console.log(`\n== ${command.join(' ')}`);
if (stdout && tee) {
// Shows the output and keeps it for the check to read.
const result = spawnSync(command[0], command.slice(1), {
cwd: ROOT,
env: {...process.env, ...env},
stdio: ['ignore', 'pipe', 'pipe'],
maxBuffer: 256 * 1024 * 1024,
});
const text = `${result.stdout ?? ''}${result.stderr ?? ''}`;
process.stdout.write(text);
fs.writeFileSync(stdout, text);
return result.status ?? 1;
Comment on lines +737 to +746

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Non-blocking: piping through spawnSync buffers the whole typecheck, so nothing prints until it ends and stderr follows stdout. Streaming while keeping the log would need an asynchronous spawn, if live output matters here.

}
const out = stdout ? fs.openSync(stdout, 'w') : 'inherit';
const result = spawnSync(command[0], command.slice(1), {
cwd: ROOT,
Expand Down
67 changes: 67 additions & 0 deletions scripts/preflight.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ import {
chromiumSpecs,
classify,
formatTable,
missingBuilds,
planChecks,
runChecks,
stopReason,
Expand Down Expand Up @@ -272,6 +273,72 @@ describe('runChecks', () => {
});
});

describe('--quick with workspace builds missing', () => {
const missing = [
"assets/templates/pages/a/page.tsx(9,28): error TS2307: Cannot find module '@astryxdesign/theme-neutral/built' or its corresponding type declarations.",
"src/x.ts(1,1): error TS2307: Cannot find module '../../core/dist/index.js' or its corresponding type declarations.",
].join('\n');
const real = `${missing}\nsrc/y.ts(3,5): error TS2322: Type 'string' is not assignable to type 'number'.`;

it('names missing builds only when every error is a missing build output', () => {
expect(missingBuilds(missing)).toBe(
'skipped, workspace builds missing; run `pnpm build` first',
);
expect(missingBuilds(real)).toBeNull();
expect(missingBuilds('no errors here')).toBeNull();
expect(
missingBuilds(
"a.ts(1,1): error TS2307: Cannot find module 'left-pad' or its corresponding type declarations.",
),
).toBeNull();
});

it('plans the quick typecheck to keep its output and judge it', () => {
const typecheck = byId(
plan(['packages/core/src/Button/Button.tsx'], {quick: true}),
'typecheck',
).commands[0];
expect(typecheck.tee).toBe(true);
expect(typecheck.stdout).toMatch(/typecheck\.log$/);
expect(typecheck.skipWhen).toBe(missingBuilds);
});

it('reports a SKIP, not a failure, and the verdict does not count it', () => {
const dir = tmp();
const log = path.join(dir, 'typecheck.log');
const check = text => [
{
id: 'typecheck',
commands: [
{
kind: 'build',
argv: ['tsc'],
stdout: log,
tee: true,
skipWhen: missingBuilds,
},
],
},
];
const exec = text => () => (fs.writeFileSync(log, text), 2);
const [skipped] = runChecks(check(), {exec: exec(missing), now: () => 0});
expect(skipped).toMatchObject({
result: 'SKIP',
note: 'skipped, workspace builds missing; run `pnpm build` first',
failed: null,
});
const verdict = formatTable([skipped], {quick: true});
expect(verdict).not.toContain('not ready');
// A skipped typecheck checked nothing: the verdict says so, never a pass.
expect(verdict).toContain(
'not checked: typecheck (workspace builds missing); run `pnpm build`, then run again before you flip',
);
expect(verdict).not.toContain('quick checks pass');
const [failed] = runChecks(check(), {exec: exec(real), now: () => 0});
expect(failed).toMatchObject({result: 'FAIL', failed: 'tsc'});
});
});

describe('stopReason', () => {
it("stops with exit 2 on uncommitted changes, which CI's listers would not see", () => {
expect(
Expand Down