@playcraft/build 0.1.94-test-a → 0.1.96-test-a
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/dist/delivery/command-isolation.d.ts +1 -0
- package/dist/delivery/command-isolation.js +7 -4
- package/dist/delivery/isolated-source.js +6 -1
- package/dist/validation/artifact-qa.d.ts +20 -28
- package/dist/validation/artifact-qa.js +157 -66
- package/dist/validation/artifact-rules.d.ts +16 -5
- package/dist/validation/artifact-rules.js +18 -7
- package/dist/validation/runtime-load.d.ts +8 -3
- package/dist/validation/runtime-load.js +7 -8
- package/dist/validation/types.d.ts +42 -19
- package/dist/validation/types.js +1 -1
- package/dist/validation/validation-runner.d.ts +3 -3
- package/dist/validation/validation-runner.js +5 -9
- package/package.json +2 -2
|
@@ -234,6 +234,9 @@ export async function wrapDeliveryCommand(argv, options) {
|
|
|
234
234
|
const isolated = await allowedPath(options.isolatedRoot);
|
|
235
235
|
if (!project?.directory || !isolated?.directory || inside(isolated.path, project.path))
|
|
236
236
|
failure('The snapshot must be a separate directory from its source');
|
|
237
|
+
const temporary = options.temporaryRoot === undefined ? isolated : await allowedPath(options.temporaryRoot);
|
|
238
|
+
if (!temporary?.directory || !inside(isolated.path, temporary.path))
|
|
239
|
+
failure('The temporary directory must be inside the snapshot');
|
|
237
240
|
const dependencies = [];
|
|
238
241
|
for (const candidate of options.dependencyRoots ?? []) {
|
|
239
242
|
if (path.basename(path.resolve(candidate)) !== 'node_modules')
|
|
@@ -299,9 +302,9 @@ export async function wrapDeliveryCommand(argv, options) {
|
|
|
299
302
|
'-p',
|
|
300
303
|
profile,
|
|
301
304
|
'/usr/bin/env',
|
|
302
|
-
`TMPDIR=${
|
|
303
|
-
`TMP=${
|
|
304
|
-
`TEMP=${
|
|
305
|
+
`TMPDIR=${temporary.path}`,
|
|
306
|
+
`TMP=${temporary.path}`,
|
|
307
|
+
`TEMP=${temporary.path}`,
|
|
305
308
|
...argv,
|
|
306
309
|
];
|
|
307
310
|
}
|
|
@@ -316,7 +319,7 @@ export async function wrapDeliveryCommand(argv, options) {
|
|
|
316
319
|
JSON.stringify({
|
|
317
320
|
read,
|
|
318
321
|
write,
|
|
319
|
-
temporary:
|
|
322
|
+
temporary: temporary.path,
|
|
320
323
|
bwrap: bubblewrapArguments(read, isolated.path, links),
|
|
321
324
|
}),
|
|
322
325
|
...argv,
|
|
@@ -67,7 +67,12 @@ export async function buildIsolatedDelivery(root, snapshot, recipe, options, bui
|
|
|
67
67
|
throw new ProjectDeliveryError('delivery_dependency_path_unsafe', 'Installed dependencies must be a directory');
|
|
68
68
|
await symlink(path.join(root, 'node_modules'), path.join(scratch, 'node_modules'), 'dir');
|
|
69
69
|
}
|
|
70
|
-
|
|
70
|
+
// Tool temporaries (for example Node's 0600 compile cache) must not land in the
|
|
71
|
+
// rescanned production source; .playcraft-temp is a process path excluded from it.
|
|
72
|
+
const toolTemporary = path.join(scratch, '.playcraft-temp');
|
|
73
|
+
await mkdir(toolTemporary);
|
|
74
|
+
await shared(toolTemporary, true);
|
|
75
|
+
await build(scratch, { projectRoot: root, isolatedRoot: scratch, temporaryRoot: toolTemporary,
|
|
71
76
|
dependencyRoots: modules ? [path.join(root, 'node_modules')] : [] });
|
|
72
77
|
const current = await readProductionSourceSnapshot(root, { excludedDirectories: recipe.generatedDirectories,
|
|
73
78
|
excludedPath: name => name === context.outputDirectory || name.startsWith(`${context.outputDirectory}/`) });
|
|
@@ -1,44 +1,36 @@
|
|
|
1
1
|
import type { Platform } from '../types.js';
|
|
2
2
|
import { type RuntimeLoadOptions } from './runtime-load.js';
|
|
3
|
-
import { type ArtifactQaReport, type BrowserDriver, type PlayableArtifact, type
|
|
4
|
-
export declare const ARTIFACT_QA_REPORT_VERSION = "0.
|
|
5
|
-
/** Bump when an artifact rule, its severity or its
|
|
6
|
-
export declare const ARTIFACT_QA_RULES_VERSION = "2026-11-
|
|
3
|
+
import { type ArtifactQaReport, type BrowserDriver, type PlayableArtifact, type QaProgressEvent, type QaStageId } from './types.js';
|
|
4
|
+
export declare const ARTIFACT_QA_REPORT_VERSION = "0.3.0";
|
|
5
|
+
/** Bump when an artifact rule, its severity, its matching or its step changes. */
|
|
6
|
+
export declare const ARTIFACT_QA_RULES_VERSION = "2026-11-11.1";
|
|
7
7
|
export interface RunArtifactQaOptions {
|
|
8
8
|
/** Rules to judge by: `playcraft` (default) checks the playable itself; a channel adds its rules. */
|
|
9
9
|
profile?: Platform;
|
|
10
|
-
/**
|
|
10
|
+
/** Steps to run, always in the order of `QA_STAGES`; default all of them. */
|
|
11
11
|
stages?: QaStageId[];
|
|
12
|
-
/**
|
|
12
|
+
/**
|
|
13
|
+
* Size limit of a channel profile, e.g. from the channel's platform adapter (`size` step); a
|
|
14
|
+
* channel enforces it. The `playcraft` profile has no hard limit and only analyses size.
|
|
15
|
+
*/
|
|
13
16
|
sizeLimitBytes?: number;
|
|
14
|
-
/** Project source root
|
|
17
|
+
/** Project source root, scanned for hints that help locate each step's problems. */
|
|
15
18
|
projectRoot?: string;
|
|
16
19
|
sourceGlobs?: string[];
|
|
17
|
-
/** Headless browser
|
|
20
|
+
/** Headless browser for the `resources`, `launch` and `cta` checks; without it they are skipped. */
|
|
18
21
|
driver?: BrowserDriver;
|
|
19
|
-
/** Why no driver was provided, e.g. Chromium is missing;
|
|
22
|
+
/** Why no driver was provided, e.g. Chromium is missing; shown as the skip reason. */
|
|
20
23
|
driverUnavailableReason?: string;
|
|
21
24
|
runtime?: Pick<RuntimeLoadOptions, 'viewports' | 'settleMs' | 'timeoutMs'>;
|
|
25
|
+
/** Called when each step starts and ends, so callers can show QA progress step by step. */
|
|
26
|
+
onProgress?: (event: QaProgressEvent) => void | Promise<void>;
|
|
22
27
|
}
|
|
28
|
+
/** Step a rule belongs to; channel package and entry rules not matched otherwise are `code`. */
|
|
29
|
+
export declare function qaStageOfRule(ruleId: string): QaStageId;
|
|
23
30
|
/**
|
|
24
|
-
* Judges a built artifact by
|
|
25
|
-
*
|
|
26
|
-
*
|
|
31
|
+
* Judges a built artifact step by step, in the order of `QA_STAGES`. Static checks, channel rules
|
|
32
|
+
* and the headless browser each run once; every result is reported under the step its rule belongs
|
|
33
|
+
* to. The browser opens in the first step that needs it. Results depend only on the artifact and
|
|
34
|
+
* the options, never on how the artifact was built.
|
|
27
35
|
*/
|
|
28
36
|
export declare function runArtifactQa(artifact: PlayableArtifact, options?: RunArtifactQaOptions): Promise<ArtifactQaReport>;
|
|
29
|
-
/**
|
|
30
|
-
* `channel` stage: the channel's existing `html-artifact` / `delivery-package` rules, the same
|
|
31
|
-
* rules export validation uses. Needs only the artifact and a channel profile.
|
|
32
|
-
*/
|
|
33
|
-
export declare function runChannelStage(artifact: PlayableArtifact, options: {
|
|
34
|
-
profile: Platform;
|
|
35
|
-
}): Promise<QaStageReport>;
|
|
36
|
-
/**
|
|
37
|
-
* `source-hints` stage: scans project source to help locate problems. Advisory: it never affects
|
|
38
|
-
* the overall result. Needs only the project root.
|
|
39
|
-
*/
|
|
40
|
-
export declare function runSourceHintsStage(options: {
|
|
41
|
-
projectRoot: string;
|
|
42
|
-
profile?: Platform;
|
|
43
|
-
sourceGlobs?: string[];
|
|
44
|
-
}): Promise<QaStageReport>;
|
|
@@ -1,33 +1,146 @@
|
|
|
1
1
|
import fs from 'node:fs/promises';
|
|
2
2
|
import path from 'node:path';
|
|
3
|
-
import {
|
|
4
|
-
import {
|
|
3
|
+
import { BASE_OUTPUT_RULE_IDS, runStaticArtifactChecks, } from './artifact-rules.js';
|
|
4
|
+
import { RUNTIME_LOAD_RULE_IDS, runRuntimeLoadChecks, runtimeViewportNames, } from './runtime-load.js';
|
|
5
5
|
import { findSourcePatterns, scanSourceForCompliance } from './source-scanner.js';
|
|
6
6
|
import { idleStageReport, ranStageReport, runPlayableValidation, summarize, } from './validation-runner.js';
|
|
7
7
|
import { QA_STAGES, } from './types.js';
|
|
8
|
-
export const ARTIFACT_QA_REPORT_VERSION = '0.
|
|
9
|
-
/** Bump when an artifact rule, its severity or its
|
|
10
|
-
export const ARTIFACT_QA_RULES_VERSION = '2026-11-
|
|
11
|
-
const
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
8
|
+
export const ARTIFACT_QA_REPORT_VERSION = '0.3.0';
|
|
9
|
+
/** Bump when an artifact rule, its severity, its matching or its step changes. */
|
|
10
|
+
export const ARTIFACT_QA_RULES_VERSION = '2026-11-11.1';
|
|
11
|
+
const B = BASE_OUTPUT_RULE_IDS;
|
|
12
|
+
const R = RUNTIME_LOAD_RULE_IDS;
|
|
13
|
+
/** The step of every channel-independent rule. */
|
|
14
|
+
const COMMON_RULE_STEPS = {
|
|
15
|
+
[B.entryParsable]: 'code',
|
|
16
|
+
[B.viewportMeta]: 'code',
|
|
17
|
+
[B.debugResidue]: 'code',
|
|
18
|
+
[B.devAddress]: 'code',
|
|
19
|
+
[B.persistentStorage]: 'code',
|
|
20
|
+
[B.localReference]: 'resources',
|
|
21
|
+
[B.inlineData]: 'resources',
|
|
22
|
+
[B.externalResource]: 'resources',
|
|
23
|
+
[R.requests]: 'resources',
|
|
24
|
+
[R.csp]: 'resources',
|
|
25
|
+
[R.pageLoads]: 'launch',
|
|
26
|
+
[R.errors]: 'launch',
|
|
27
|
+
[R.firstFrame]: 'launch',
|
|
28
|
+
[R.viewportErrors]: 'launch',
|
|
29
|
+
[R.viewportContent]: 'launch',
|
|
30
|
+
[R.viewportCanvasFit]: 'launch',
|
|
31
|
+
[R.viewportOverflow]: 'launch',
|
|
32
|
+
[B.sizeBudget]: 'size',
|
|
33
|
+
[B.sizeBreakdown]: 'size',
|
|
34
|
+
[B.directRedirect]: 'cta',
|
|
35
|
+
[R.noAutoRedirect]: 'cta',
|
|
36
|
+
[R.ctaEntry]: 'cta',
|
|
37
|
+
[R.ctaRouted]: 'cta',
|
|
38
|
+
[R.ctaStoreUrl]: 'cta',
|
|
39
|
+
[R.startSignal]: 'cta',
|
|
19
40
|
};
|
|
41
|
+
/** Rule id segments (after the channel) that place channel rules and source hints in a step. */
|
|
42
|
+
const STEP_SEGMENTS = [
|
|
43
|
+
['size', ['size']],
|
|
44
|
+
['cta', ['cta', 'lifecycle', 'mraid', 'sdk', 'redirect', 'click-pixel-url', 'adsdk', 'start-signal']],
|
|
45
|
+
['resources', ['external-resource', 'network', 'local-reference', 'inline-data', 'requests', 'csp']],
|
|
46
|
+
['launch', ['page', 'errors', 'first-frame', 'viewport', 'audio', 'layout']],
|
|
47
|
+
];
|
|
48
|
+
/** Step a rule belongs to; channel package and entry rules not matched otherwise are `code`. */
|
|
49
|
+
export function qaStageOfRule(ruleId) {
|
|
50
|
+
const common = COMMON_RULE_STEPS[ruleId];
|
|
51
|
+
if (common)
|
|
52
|
+
return common;
|
|
53
|
+
const segments = new Set(ruleId.split('.').slice(1));
|
|
54
|
+
return STEP_SEGMENTS.find(([, names]) => names.some((name) => segments.has(name)))?.[0] ?? 'code';
|
|
55
|
+
}
|
|
56
|
+
/** Steps that open the artifact in the headless browser. */
|
|
57
|
+
const BROWSER_STEPS = new Set(['resources', 'launch', 'cta']);
|
|
58
|
+
const ENTRY_UNPARSABLE = 'The entry HTML could not be read as HTML; fix the code step first';
|
|
59
|
+
const PAGE_DID_NOT_LOAD = 'The browser checks of this step did not run because the artifact did not load; see the launch step';
|
|
20
60
|
/**
|
|
21
|
-
* Judges a built artifact by
|
|
22
|
-
*
|
|
23
|
-
*
|
|
61
|
+
* Judges a built artifact step by step, in the order of `QA_STAGES`. Static checks, channel rules
|
|
62
|
+
* and the headless browser each run once; every result is reported under the step its rule belongs
|
|
63
|
+
* to. The browser opens in the first step that needs it. Results depend only on the artifact and
|
|
64
|
+
* the options, never on how the artifact was built.
|
|
24
65
|
*/
|
|
25
66
|
export async function runArtifactQa(artifact, options = {}) {
|
|
26
67
|
const profile = options.profile ?? 'playcraft';
|
|
68
|
+
const requested = new Set(options.stages ?? QA_STAGES);
|
|
69
|
+
const steps = QA_STAGES.filter((step) => requested.has(step));
|
|
70
|
+
const statics = await runStaticArtifactChecks(artifact, {
|
|
71
|
+
profile,
|
|
72
|
+
...(options.sizeLimitBytes !== undefined ? { sizeLimitBytes: options.sizeLimitBytes } : {}),
|
|
73
|
+
});
|
|
74
|
+
const channel = await runChannelRules(artifact, profile);
|
|
75
|
+
const hints = options.projectRoot
|
|
76
|
+
? await collectSourceHints(options.projectRoot, profile, options.sourceGlobs)
|
|
77
|
+
: undefined;
|
|
78
|
+
let runtime;
|
|
79
|
+
const runtimeOutcome = () => (runtime ?? (runtime = options.driver
|
|
80
|
+
? runRuntimeLoadChecks(artifact, {
|
|
81
|
+
driver: options.driver,
|
|
82
|
+
profile,
|
|
83
|
+
...options.runtime,
|
|
84
|
+
}).then((results) => ({
|
|
85
|
+
results,
|
|
86
|
+
loaded: results.find((item) => item.ruleId === R.pageLoads)?.status === 'pass',
|
|
87
|
+
}))
|
|
88
|
+
: Promise.resolve({
|
|
89
|
+
unavailable: options.driverUnavailableReason ?? 'No headless browser driver was provided',
|
|
90
|
+
})));
|
|
27
91
|
const stages = [];
|
|
28
|
-
for (const
|
|
29
|
-
|
|
30
|
-
|
|
92
|
+
for (const [index, step] of steps.entries()) {
|
|
93
|
+
const position = { stage: step, index: index + 1, total: steps.length };
|
|
94
|
+
await options.onProgress?.({ type: 'step-start', ...position });
|
|
95
|
+
const startedAt = Date.now();
|
|
96
|
+
const stepHints = (hints ?? []).filter((hint) => qaStageOfRule(hint.ruleId) === step);
|
|
97
|
+
// Without a channel, size is analysis only: the playcraft preview has no hard limit.
|
|
98
|
+
const advisory = step === 'size' && !statics.sizeLimitStrict;
|
|
99
|
+
let report;
|
|
100
|
+
if (!statics.entryParsable && step !== 'code' && step !== 'size') {
|
|
101
|
+
report = { ...idleStageReport(step, 'skipped', ENTRY_UNPARSABLE, advisory), hints: stepHints };
|
|
102
|
+
}
|
|
103
|
+
else {
|
|
104
|
+
const inStep = (item) => qaStageOfRule(item.ruleId) === step;
|
|
105
|
+
const results = [...statics.results, ...channel.results].filter(inStep);
|
|
106
|
+
let status = 'ran';
|
|
107
|
+
let reason;
|
|
108
|
+
const details = {};
|
|
109
|
+
if (step === 'size') {
|
|
110
|
+
details.sizeLimitBytes = statics.sizeLimitBytes;
|
|
111
|
+
details.sizeLimitStrict = statics.sizeLimitStrict;
|
|
112
|
+
}
|
|
113
|
+
if (BROWSER_STEPS.has(step)) {
|
|
114
|
+
const outcome = await runtimeOutcome();
|
|
115
|
+
if ('unavailable' in outcome) {
|
|
116
|
+
status = 'partial';
|
|
117
|
+
reason = `Browser checks did not run: ${outcome.unavailable}`;
|
|
118
|
+
}
|
|
119
|
+
else {
|
|
120
|
+
results.push(...outcome.results.filter(inStep));
|
|
121
|
+
if (step === 'launch')
|
|
122
|
+
details.viewports = runtimeViewportNames(options.runtime?.viewports);
|
|
123
|
+
else if (!outcome.loaded) {
|
|
124
|
+
status = 'partial';
|
|
125
|
+
reason = PAGE_DID_NOT_LOAD;
|
|
126
|
+
}
|
|
127
|
+
}
|
|
128
|
+
}
|
|
129
|
+
report =
|
|
130
|
+
results.length === 0 && status === 'partial'
|
|
131
|
+
? { ...idleStageReport(step, 'skipped', reason ?? '', advisory), hints: stepHints }
|
|
132
|
+
: ranStageReport(step, startedAt, results, {
|
|
133
|
+
status,
|
|
134
|
+
...(reason ? { reason } : {}),
|
|
135
|
+
advisory,
|
|
136
|
+
hints: stepHints,
|
|
137
|
+
...(Object.keys(details).length > 0 ? { details } : {}),
|
|
138
|
+
});
|
|
139
|
+
}
|
|
140
|
+
stages.push(report);
|
|
141
|
+
await options.onProgress?.({ type: 'step-end', ...position, report });
|
|
142
|
+
}
|
|
143
|
+
const counted = stages.filter((stage) => !stage.advisory);
|
|
31
144
|
return {
|
|
32
145
|
version: ARTIFACT_QA_REPORT_VERSION,
|
|
33
146
|
rulesVersion: ARTIFACT_QA_RULES_VERSION,
|
|
@@ -41,67 +154,45 @@ export async function runArtifactQa(artifact, options = {}) {
|
|
|
41
154
|
totalSize: artifact.totalSize,
|
|
42
155
|
fileCount: artifact.files.length,
|
|
43
156
|
},
|
|
44
|
-
summary: summarize(counted.flatMap((stage) => stage.results),
|
|
45
|
-
incomplete:
|
|
157
|
+
summary: summarize(counted.flatMap((stage) => stage.results), channel.manualChecklist, channel.externalChecklist),
|
|
158
|
+
incomplete: counted.some((stage) => stage.status === 'skipped' || stage.status === 'partial'),
|
|
46
159
|
stages,
|
|
160
|
+
sourceHints: hints
|
|
161
|
+
? { status: 'ran' }
|
|
162
|
+
: { status: 'skipped', reason: 'No project root was provided' },
|
|
163
|
+
manualChecklist: channel.manualChecklist,
|
|
164
|
+
externalChecklist: channel.externalChecklist,
|
|
47
165
|
};
|
|
48
166
|
}
|
|
49
|
-
function runStage(stage, artifact, options) {
|
|
50
|
-
switch (stage) {
|
|
51
|
-
case 'base':
|
|
52
|
-
return runBaseStage(artifact, {
|
|
53
|
-
profile: options.profile,
|
|
54
|
-
...(options.sizeLimitBytes !== undefined ? { sizeLimitBytes: options.sizeLimitBytes } : {}),
|
|
55
|
-
});
|
|
56
|
-
case 'channel':
|
|
57
|
-
return runChannelStage(artifact, { profile: options.profile });
|
|
58
|
-
case 'runtime-load':
|
|
59
|
-
return options.driver
|
|
60
|
-
? runRuntimeLoadStage(artifact, {
|
|
61
|
-
driver: options.driver,
|
|
62
|
-
profile: options.profile,
|
|
63
|
-
...options.runtime,
|
|
64
|
-
})
|
|
65
|
-
: Promise.resolve(idleStageReport('runtime-load', 'skipped', options.driverUnavailableReason ?? 'No headless browser driver was provided'));
|
|
66
|
-
case 'source-hints':
|
|
67
|
-
return options.projectRoot
|
|
68
|
-
? runSourceHintsStage({
|
|
69
|
-
projectRoot: options.projectRoot,
|
|
70
|
-
profile: options.profile,
|
|
71
|
-
...(options.sourceGlobs ? { sourceGlobs: options.sourceGlobs } : {}),
|
|
72
|
-
})
|
|
73
|
-
: Promise.resolve(idleStageReport('source-hints', 'skipped', 'No project root was provided', true));
|
|
74
|
-
}
|
|
75
|
-
}
|
|
76
167
|
/**
|
|
77
|
-
*
|
|
78
|
-
*
|
|
168
|
+
* The channel's existing `html-artifact` / `delivery-package` rules, the same rules export
|
|
169
|
+
* validation uses. The `playcraft` profile has none.
|
|
79
170
|
*/
|
|
80
|
-
|
|
81
|
-
if (
|
|
82
|
-
return
|
|
83
|
-
const startedAt = Date.now();
|
|
171
|
+
async function runChannelRules(artifact, profile) {
|
|
172
|
+
if (profile === 'playcraft')
|
|
173
|
+
return { results: [], manualChecklist: [], externalChecklist: [] };
|
|
84
174
|
const report = await runPlayableValidation({
|
|
85
175
|
projectRoot: path.dirname(artifact.sourcePath),
|
|
86
|
-
channel:
|
|
176
|
+
channel: profile,
|
|
87
177
|
engine: 'unknown',
|
|
88
178
|
buildChain: 'generic',
|
|
89
179
|
...channelPaths(artifact),
|
|
90
180
|
}, stagesFor(artifact));
|
|
91
|
-
return
|
|
181
|
+
return {
|
|
182
|
+
results: report.results,
|
|
92
183
|
manualChecklist: report.manualChecklist,
|
|
93
184
|
externalChecklist: report.externalChecklist,
|
|
94
|
-
}
|
|
95
|
-
}
|
|
96
|
-
/**
|
|
97
|
-
* `source-hints` stage: scans project source to help locate problems. Advisory: it never affects
|
|
98
|
-
* the overall result. Needs only the project root.
|
|
99
|
-
*/
|
|
100
|
-
export async function runSourceHintsStage(options) {
|
|
101
|
-
const startedAt = Date.now();
|
|
102
|
-
const results = await collectSourceHints(options.projectRoot, options.profile ?? 'playcraft', options.sourceGlobs);
|
|
103
|
-
return ranStageReport('source-hints', startedAt, results, { advisory: true });
|
|
185
|
+
};
|
|
104
186
|
}
|
|
187
|
+
const ADSDK_PACKAGE = '@playcraft/adsdk';
|
|
188
|
+
/** Published adsdk methods are `playcraftInit` etc.; the short names appear in skills and templates. */
|
|
189
|
+
const ADSDK_CALLS = {
|
|
190
|
+
init: /\bsdk\s*\.\s*(?:init|playcraftInit)\s*\(/g,
|
|
191
|
+
start: /\bsdk\s*\.\s*(?:start|playcraftStart)\s*\(/g,
|
|
192
|
+
interactive: /\bsdk\s*\.\s*(?:interactive|playcraftInteractive)\s*\(/g,
|
|
193
|
+
finish: /\bsdk\s*\.\s*(?:finish|playcraftFinish)\s*\(/g,
|
|
194
|
+
install: /\bsdk\s*\.\s*(?:install|playcraftInstall)\s*\(/g,
|
|
195
|
+
};
|
|
105
196
|
/** Same stage choice as the workspace delivery re-check: HTML artifacts, or the delivery package. */
|
|
106
197
|
function stagesFor(artifact) {
|
|
107
198
|
if (artifact.container === 'html')
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { Platform } from '../types.js';
|
|
2
|
-
import type { PlayableArtifact,
|
|
2
|
+
import type { PlayableArtifact, ValidationResult } from './types.js';
|
|
3
3
|
/**
|
|
4
4
|
* `base-output` rules: channel-independent checks that read the built artifact only. They do not
|
|
5
5
|
* depend on the engine or the build tool that produced the artifact.
|
|
@@ -18,11 +18,22 @@ export declare const BASE_OUTPUT_RULE_IDS: {
|
|
|
18
18
|
readonly viewportMeta: "common.artifact.viewport-meta.present";
|
|
19
19
|
};
|
|
20
20
|
export type BaseOutputRuleId = (typeof BASE_OUTPUT_RULE_IDS)[keyof typeof BASE_OUTPUT_RULE_IDS];
|
|
21
|
-
export interface
|
|
21
|
+
export interface StaticArtifactCheckOptions {
|
|
22
22
|
/** Profile whose external-resource allowlist applies; default `playcraft`. */
|
|
23
23
|
profile?: Platform;
|
|
24
|
-
/**
|
|
24
|
+
/**
|
|
25
|
+
* Size limit of a channel profile, e.g. from the channel's platform adapter; default 5 MB, the
|
|
26
|
+
* cap every channel uses. The `playcraft` profile has no hard limit and uses it as a reference.
|
|
27
|
+
*/
|
|
25
28
|
sizeLimitBytes?: number;
|
|
26
29
|
}
|
|
27
|
-
|
|
28
|
-
|
|
30
|
+
export interface StaticArtifactChecks {
|
|
31
|
+
results: ValidationResult[];
|
|
32
|
+
/** False when the entry HTML cannot be read as HTML; only the entry result is returned then. */
|
|
33
|
+
entryParsable: boolean;
|
|
34
|
+
sizeLimitBytes: number;
|
|
35
|
+
/** A channel's limit is enforced; the `playcraft` profile only warns above the reference. */
|
|
36
|
+
sizeLimitStrict: boolean;
|
|
37
|
+
}
|
|
38
|
+
/** Every static check of the artifact files, run once; QA steps pick their rules from it. */
|
|
39
|
+
export declare function runStaticArtifactChecks(artifact: PlayableArtifact, options?: StaticArtifactCheckOptions): Promise<StaticArtifactChecks>;
|
|
@@ -2,7 +2,6 @@ import path from 'node:path';
|
|
|
2
2
|
import { formatBytes } from '../utils.js';
|
|
3
3
|
import { collectExternalResources, collectLocalResourceReferences, isAllowedExternalResource, } from './html-validator.js';
|
|
4
4
|
import { getChannelRuleProfile } from './profiles.js';
|
|
5
|
-
import { ranStageReport } from './validation-runner.js';
|
|
6
5
|
/**
|
|
7
6
|
* `base-output` rules: channel-independent checks that read the built artifact only. They do not
|
|
8
7
|
* depend on the engine or the build tool that produced the artifact.
|
|
@@ -20,21 +19,23 @@ export const BASE_OUTPUT_RULE_IDS = {
|
|
|
20
19
|
persistentStorage: 'common.artifact.storage.persistent.review',
|
|
21
20
|
viewportMeta: 'common.artifact.viewport-meta.present',
|
|
22
21
|
};
|
|
23
|
-
/**
|
|
22
|
+
/** Channel size cap; the reference for the `playcraft` profile, which has no hard limit. */
|
|
24
23
|
const DEFAULT_SIZE_LIMIT = 5 * 1024 * 1024;
|
|
25
|
-
/**
|
|
26
|
-
export async function
|
|
27
|
-
const startedAt = Date.now();
|
|
24
|
+
/** Every static check of the artifact files, run once; QA steps pick their rules from it. */
|
|
25
|
+
export async function runStaticArtifactChecks(artifact, options = {}) {
|
|
28
26
|
const sizeLimitBytes = options.sizeLimitBytes !== undefined && Number.isFinite(options.sizeLimitBytes)
|
|
29
27
|
? options.sizeLimitBytes
|
|
30
28
|
: DEFAULT_SIZE_LIMIT;
|
|
31
29
|
const externalCheck = getChannelRuleProfile(options.profile ?? 'playcraft').rules.find((rule) => rule.stage === 'html-artifact' && rule.check?.kind === 'external-resources')?.check;
|
|
32
30
|
const allowedExternalPatterns = externalCheck?.kind === 'external-resources' ? externalCheck.allowedPatterns : undefined;
|
|
31
|
+
const sizeLimitStrict = (options.profile ?? 'playcraft') !== 'playcraft';
|
|
33
32
|
const results = await runBaseOutputChecks(artifact, {
|
|
34
33
|
sizeLimitBytes,
|
|
34
|
+
sizeLimitStrict,
|
|
35
35
|
...(allowedExternalPatterns ? { allowedExternalPatterns } : {}),
|
|
36
36
|
});
|
|
37
|
-
|
|
37
|
+
const entryParsable = results.find((item) => item.ruleId === BASE_OUTPUT_RULE_IDS.entryParsable)?.status === 'pass';
|
|
38
|
+
return { results, entryParsable, sizeLimitBytes, sizeLimitStrict };
|
|
38
39
|
}
|
|
39
40
|
const RULES = {
|
|
40
41
|
[BASE_OUTPUT_RULE_IDS.entryParsable]: {
|
|
@@ -46,7 +47,7 @@ const RULES = {
|
|
|
46
47
|
[BASE_OUTPUT_RULE_IDS.sizeBudget]: {
|
|
47
48
|
title: 'Artifact stays within the size limit',
|
|
48
49
|
severity: 'error',
|
|
49
|
-
recommendation: 'Compress images and audio, remove unused assets, or enable image compression when exporting.
|
|
50
|
+
recommendation: 'Compress images and audio, remove unused assets, or enable image compression when exporting; start with the largest categories in the size breakdown. A channel package must stay within the channel limit.',
|
|
50
51
|
confidence: 'medium',
|
|
51
52
|
},
|
|
52
53
|
[BASE_OUTPUT_RULE_IDS.localReference]: {
|
|
@@ -206,6 +207,16 @@ function checkSizeBudget(artifact, options) {
|
|
|
206
207
|
const limit = options.sizeLimitBytes;
|
|
207
208
|
const size = artifact.totalSize;
|
|
208
209
|
const margin = limit - size;
|
|
210
|
+
if (!options.sizeLimitStrict) {
|
|
211
|
+
// The playcraft preview has no hard limit; above the channel cap, warn that export may exceed it.
|
|
212
|
+
const evidence = `size=${formatBytes(size)}; no hard limit for the playcraft profile, channel packages are limited to ${formatBytes(limit)}`;
|
|
213
|
+
return size > limit
|
|
214
|
+
? result(BASE_OUTPUT_RULE_IDS.sizeBudget, false, {
|
|
215
|
+
evidence: `${evidence}; exporting to a channel will likely exceed it`,
|
|
216
|
+
status: 'warning',
|
|
217
|
+
})
|
|
218
|
+
: result(BASE_OUTPUT_RULE_IDS.sizeBudget, true, { evidence });
|
|
219
|
+
}
|
|
209
220
|
const evidence = `size=${formatBytes(size)}, limit=${formatBytes(limit)}, margin=${margin >= 0 ? formatBytes(margin) : `-${formatBytes(-margin)}`}`;
|
|
210
221
|
if (size > limit)
|
|
211
222
|
return result(BASE_OUTPUT_RULE_IDS.sizeBudget, false, { evidence });
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import type { Platform } from '../types.js';
|
|
2
|
-
import type { BrowserDriver, PlayableArtifact,
|
|
2
|
+
import type { BrowserDriver, PlayableArtifact, RuntimeViewport, ValidationResult } from './types.js';
|
|
3
3
|
/**
|
|
4
4
|
* `runtime-load` rules: open the artifact in a headless browser without playing it. All network
|
|
5
5
|
* access outside the artifact is blocked, store-opening calls are recorded instead of followed,
|
|
@@ -23,6 +23,7 @@ export declare const RUNTIME_LOAD_RULE_IDS: {
|
|
|
23
23
|
readonly viewportErrors: "common.runtime.viewport.errors";
|
|
24
24
|
readonly viewportContent: "common.runtime.viewport.content";
|
|
25
25
|
};
|
|
26
|
+
export type RuntimeLoadRuleId = (typeof RUNTIME_LOAD_RULE_IDS)[keyof typeof RUNTIME_LOAD_RULE_IDS];
|
|
26
27
|
export interface RuntimeViewportPreset {
|
|
27
28
|
/** Shown in evidence, e.g. `iphone16 portrait`. */
|
|
28
29
|
name: string;
|
|
@@ -45,8 +46,12 @@ export declare const RUNTIME_ORIGIN = "http://artifact.playcraft-qa.test";
|
|
|
45
46
|
/** Same-origin artifact files and inline data only; no network, workers or frames. */
|
|
46
47
|
export declare const RUNTIME_CSP: string;
|
|
47
48
|
export declare function channelGlobalsFor(profile: Platform): string[];
|
|
48
|
-
/**
|
|
49
|
-
export declare function
|
|
49
|
+
/** Names of the viewports `runRuntimeLoadChecks` opens, for reports. */
|
|
50
|
+
export declare function runtimeViewportNames(viewports?: RuntimeViewportPreset[]): string[];
|
|
51
|
+
/**
|
|
52
|
+
* Opens the artifact in a headless browser and returns every `runtime-load` result. When the page
|
|
53
|
+
* does not load, only the page-load result is returned.
|
|
54
|
+
*/
|
|
50
55
|
export declare function runRuntimeLoadChecks(artifact: PlayableArtifact, options: RuntimeLoadOptions): Promise<ValidationResult[]>;
|
|
51
56
|
/**
|
|
52
57
|
* Script injected before any page script during runtime QA. It records, without side effects:
|
|
@@ -1,5 +1,4 @@
|
|
|
1
1
|
import path from 'node:path';
|
|
2
|
-
import { ranStageReport } from './validation-runner.js';
|
|
3
2
|
/**
|
|
4
3
|
* `runtime-load` rules: open the artifact in a headless browser without playing it. All network
|
|
5
4
|
* access outside the artifact is blocked, store-opening calls are recorded instead of followed,
|
|
@@ -188,14 +187,14 @@ const RULES = {
|
|
|
188
187
|
confidence: 'medium',
|
|
189
188
|
},
|
|
190
189
|
};
|
|
191
|
-
/**
|
|
192
|
-
export
|
|
193
|
-
|
|
194
|
-
const results = await runRuntimeLoadChecks(artifact, options);
|
|
195
|
-
return ranStageReport('runtime-load', startedAt, results, {
|
|
196
|
-
details: { viewports: (options.viewports ?? [DEFAULT_VIEWPORT]).map((item) => item.name) },
|
|
197
|
-
});
|
|
190
|
+
/** Names of the viewports `runRuntimeLoadChecks` opens, for reports. */
|
|
191
|
+
export function runtimeViewportNames(viewports) {
|
|
192
|
+
return (viewports?.length ? viewports : [DEFAULT_VIEWPORT]).map((item) => item.name);
|
|
198
193
|
}
|
|
194
|
+
/**
|
|
195
|
+
* Opens the artifact in a headless browser and returns every `runtime-load` result. When the page
|
|
196
|
+
* does not load, only the page-load result is returned.
|
|
197
|
+
*/
|
|
199
198
|
export async function runRuntimeLoadChecks(artifact, options) {
|
|
200
199
|
const [main = DEFAULT_VIEWPORT, ...others] = options.viewports?.length
|
|
201
200
|
? options.viewports
|
|
@@ -145,39 +145,54 @@ export interface PlayableArtifact {
|
|
|
145
145
|
}
|
|
146
146
|
export type ArtifactReadErrorCode = 'artifact_not_found' | 'artifact_unsupported' | 'artifact_zip_invalid' | 'artifact_entry_missing' | 'artifact_entry_ambiguous' | 'artifact_entry_invalid';
|
|
147
147
|
/**
|
|
148
|
-
* Artifact QA
|
|
149
|
-
*
|
|
150
|
-
* - `
|
|
151
|
-
* - `
|
|
152
|
-
* - `
|
|
153
|
-
* - `
|
|
148
|
+
* Artifact QA steps, in the order they run and are shown to users. Each step answers one question
|
|
149
|
+
* a user would ask about the playable; every rule belongs to exactly one step.
|
|
150
|
+
* - `code`: is the code in the artifact sound, with no development or debugging leftovers.
|
|
151
|
+
* - `resources`: are all resources inside the artifact, with nothing fetched from the network.
|
|
152
|
+
* - `launch`: does the game open without errors and display correctly on every screen.
|
|
153
|
+
* - `size`: how big the artifact is and what takes the space. A channel profile enforces the
|
|
154
|
+
* channel's limit; the `playcraft` profile has no hard limit, so the step is advisory there.
|
|
155
|
+
* - `cta`: does the CTA reach the channel's store API, with no redirect the user did not tap.
|
|
154
156
|
*/
|
|
155
|
-
export type QaStageId = '
|
|
157
|
+
export type QaStageId = 'code' | 'resources' | 'launch' | 'size' | 'cta';
|
|
156
158
|
export declare const QA_STAGES: readonly QaStageId[];
|
|
157
159
|
/**
|
|
158
|
-
* - `ran`: the
|
|
159
|
-
* - `
|
|
160
|
-
* - `
|
|
160
|
+
* - `ran`: every check of the step ran; see its results.
|
|
161
|
+
* - `partial`: some checks ran, others could not (e.g. no browser); the QA is incomplete.
|
|
162
|
+
* - `skipped`: the step could not run at all; the QA is incomplete.
|
|
163
|
+
* - `not-applicable`: the step does not apply to this artifact.
|
|
161
164
|
*/
|
|
162
|
-
export type QaStageStatus = 'ran' | 'skipped' | 'not-applicable';
|
|
165
|
+
export type QaStageStatus = 'ran' | 'partial' | 'skipped' | 'not-applicable';
|
|
163
166
|
export interface QaStageReport {
|
|
164
167
|
stage: QaStageId;
|
|
165
168
|
status: QaStageStatus;
|
|
166
|
-
/** Why the
|
|
169
|
+
/** Why the step did not run, or which of its checks did not run. */
|
|
167
170
|
reason?: string;
|
|
168
|
-
/** Advisory
|
|
171
|
+
/** Advisory steps never affect the overall summary or exit code. */
|
|
169
172
|
advisory: boolean;
|
|
170
173
|
durationMs: number;
|
|
171
174
|
summary: ValidationSummary;
|
|
172
175
|
results: ValidationResult[];
|
|
173
|
-
|
|
174
|
-
|
|
175
|
-
/**
|
|
176
|
+
/** Project source findings that help locate this step's problems; never affect any result. */
|
|
177
|
+
hints: ValidationResult[];
|
|
178
|
+
/** Step-specific facts, e.g. the size limit used by `size`. */
|
|
176
179
|
details?: Record<string, unknown>;
|
|
177
180
|
}
|
|
181
|
+
export type QaProgressEvent = {
|
|
182
|
+
type: 'step-start';
|
|
183
|
+
stage: QaStageId;
|
|
184
|
+
index: number;
|
|
185
|
+
total: number;
|
|
186
|
+
} | {
|
|
187
|
+
type: 'step-end';
|
|
188
|
+
stage: QaStageId;
|
|
189
|
+
index: number;
|
|
190
|
+
total: number;
|
|
191
|
+
report: QaStageReport;
|
|
192
|
+
};
|
|
178
193
|
/**
|
|
179
|
-
* Report of `runArtifactQa`: one report per
|
|
180
|
-
*
|
|
194
|
+
* Report of `runArtifactQa`: one report per step, and an overall summary of the non-advisory
|
|
195
|
+
* steps that ran. Kept apart from `ValidationReport` so the existing delivery validation output,
|
|
181
196
|
* which is checked against strict schemas, stays unchanged.
|
|
182
197
|
*/
|
|
183
198
|
export interface ArtifactQaReport {
|
|
@@ -194,9 +209,17 @@ export interface ArtifactQaReport {
|
|
|
194
209
|
fileCount: number;
|
|
195
210
|
};
|
|
196
211
|
summary: ValidationSummary;
|
|
197
|
-
/** A requested
|
|
212
|
+
/** A requested step was skipped or only partly run, so passing does not cover it. */
|
|
198
213
|
incomplete: boolean;
|
|
199
214
|
stages: QaStageReport[];
|
|
215
|
+
/** Whether project source was scanned for the steps' hints. */
|
|
216
|
+
sourceHints: {
|
|
217
|
+
status: 'ran' | 'skipped';
|
|
218
|
+
reason?: string;
|
|
219
|
+
};
|
|
220
|
+
/** Checks of the channel profile that need a person or the channel's own validator. */
|
|
221
|
+
manualChecklist: ManualChecklistItem[];
|
|
222
|
+
externalChecklist: ExternalChecklistItem[];
|
|
200
223
|
}
|
|
201
224
|
export interface ReadArtifactOptions {
|
|
202
225
|
/** Entry HTML path inside a ZIP or directory; defaults to `index.html`, then the only HTML file. */
|
package/dist/validation/types.js
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export const QA_STAGES = ['
|
|
1
|
+
export const QA_STAGES = ['code', 'resources', 'launch', 'size', 'cta'];
|
|
@@ -16,10 +16,10 @@ export declare function runPlayableSourceValidationForChannels(context: Omit<Val
|
|
|
16
16
|
export declare function summarize(results: ValidationResult[], manualChecklist: ManualChecklistItem[], externalChecklist: ExternalChecklistItem[]): ValidationSummary;
|
|
17
17
|
/** Builds the report of a QA stage that ran. */
|
|
18
18
|
export declare function ranStageReport(stage: QaStageId, startedAt: number, results: ValidationResult[], extra?: {
|
|
19
|
+
status?: 'ran' | 'partial';
|
|
20
|
+
reason?: string;
|
|
19
21
|
advisory?: boolean;
|
|
20
|
-
|
|
21
|
-
externalChecklist?: ExternalChecklistItem[];
|
|
22
|
+
hints?: ValidationResult[];
|
|
22
23
|
details?: Record<string, unknown>;
|
|
23
24
|
}): QaStageReport;
|
|
24
|
-
/** Builds the report of a QA stage that did not run. */
|
|
25
25
|
export declare function idleStageReport(stage: QaStageId, status: 'skipped' | 'not-applicable', reason: string, advisory?: boolean): QaStageReport;
|
|
@@ -131,21 +131,18 @@ export function summarize(results, manualChecklist, externalChecklist) {
|
|
|
131
131
|
}
|
|
132
132
|
/** Builds the report of a QA stage that ran. */
|
|
133
133
|
export function ranStageReport(stage, startedAt, results, extra = {}) {
|
|
134
|
-
const manualChecklist = extra.manualChecklist ?? [];
|
|
135
|
-
const externalChecklist = extra.externalChecklist ?? [];
|
|
136
134
|
return {
|
|
137
135
|
stage,
|
|
138
|
-
status: 'ran',
|
|
136
|
+
status: extra.status ?? 'ran',
|
|
137
|
+
...(extra.reason ? { reason: extra.reason } : {}),
|
|
139
138
|
advisory: extra.advisory ?? false,
|
|
140
139
|
durationMs: Date.now() - startedAt,
|
|
141
|
-
summary: summarize(results,
|
|
140
|
+
summary: summarize(results, [], []),
|
|
142
141
|
results,
|
|
143
|
-
|
|
144
|
-
externalChecklist,
|
|
142
|
+
hints: extra.hints ?? [],
|
|
145
143
|
...(extra.details ? { details: extra.details } : {}),
|
|
146
144
|
};
|
|
147
145
|
}
|
|
148
|
-
/** Builds the report of a QA stage that did not run. */
|
|
149
146
|
export function idleStageReport(stage, status, reason, advisory = false) {
|
|
150
147
|
return {
|
|
151
148
|
stage,
|
|
@@ -155,7 +152,6 @@ export function idleStageReport(stage, status, reason, advisory = false) {
|
|
|
155
152
|
durationMs: 0,
|
|
156
153
|
summary: summarize([], [], []),
|
|
157
154
|
results: [],
|
|
158
|
-
|
|
159
|
-
externalChecklist: [],
|
|
155
|
+
hints: [],
|
|
160
156
|
};
|
|
161
157
|
}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@playcraft/build",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.96-test-a",
|
|
4
4
|
"private": false,
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -58,7 +58,7 @@
|
|
|
58
58
|
"typescript": "^5.9.3",
|
|
59
59
|
"vite": "^8.0.3",
|
|
60
60
|
"vite-plugin-singlefile": "^2.3.2",
|
|
61
|
-
"@playcraft/common": "0.1.
|
|
61
|
+
"@playcraft/common": "0.1.96-test-a"
|
|
62
62
|
},
|
|
63
63
|
"devDependencies": {
|
|
64
64
|
"@playcraft/ads-tracking": "^1.0.0",
|