@playcraft/build 0.1.86 → 0.1.88

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,44 @@
1
+ import type { Platform } from '../types.js';
2
+ import { type RuntimeLoadOptions } from './runtime-load.js';
3
+ import { type ArtifactQaReport, type BrowserDriver, type PlayableArtifact, type QaStageId, type QaStageReport } from './types.js';
4
+ export declare const ARTIFACT_QA_REPORT_VERSION = "0.2.0";
5
+ /** Bump when an artifact rule, its severity or its matching changes. */
6
+ export declare const ARTIFACT_QA_RULES_VERSION = "2026-11-10.1";
7
+ export interface RunArtifactQaOptions {
8
+ /** Rules to judge by: `playcraft` (default) checks the playable itself; a channel adds its rules. */
9
+ profile?: Platform;
10
+ /** Stages to run, in this order; default all of `QA_STAGES`. */
11
+ stages?: QaStageId[];
12
+ /** Size limit of the profile, e.g. from the channel's platform adapter (`base` stage). */
13
+ sizeLimitBytes?: number;
14
+ /** Project source root (`source-hints` stage). */
15
+ projectRoot?: string;
16
+ sourceGlobs?: string[];
17
+ /** Headless browser (`runtime-load` stage); without it the stage is reported as skipped. */
18
+ driver?: BrowserDriver;
19
+ /** Why no driver was provided, e.g. Chromium is missing; becomes the runtime-load skip reason. */
20
+ driverUnavailableReason?: string;
21
+ runtime?: Pick<RuntimeLoadOptions, 'viewports' | 'settleMs' | 'timeoutMs'>;
22
+ }
23
+ /**
24
+ * Judges a built artifact by running each requested stage independently and collecting their
25
+ * reports. Stages never read each other's results, so any stage can also be called on its own.
26
+ * Results depend only on the artifact and the options, never on how the artifact was built.
27
+ */
28
+ 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>;
@@ -0,0 +1,170 @@
1
+ import fs from 'node:fs/promises';
2
+ import path from 'node:path';
3
+ import { runBaseStage } from './artifact-rules.js';
4
+ import { runRuntimeLoadStage } from './runtime-load.js';
5
+ import { findSourcePatterns, scanSourceForCompliance } from './source-scanner.js';
6
+ import { idleStageReport, ranStageReport, runPlayableValidation, summarize, } from './validation-runner.js';
7
+ import { QA_STAGES, } from './types.js';
8
+ export const ARTIFACT_QA_REPORT_VERSION = '0.2.0';
9
+ /** Bump when an artifact rule, its severity or its matching changes. */
10
+ export const ARTIFACT_QA_RULES_VERSION = '2026-11-10.1';
11
+ const ADSDK_PACKAGE = '@playcraft/adsdk';
12
+ /** Published adsdk methods are `playcraftInit` etc.; the short names appear in skills and templates. */
13
+ const ADSDK_CALLS = {
14
+ init: /\bsdk\s*\.\s*(?:init|playcraftInit)\s*\(/g,
15
+ start: /\bsdk\s*\.\s*(?:start|playcraftStart)\s*\(/g,
16
+ interactive: /\bsdk\s*\.\s*(?:interactive|playcraftInteractive)\s*\(/g,
17
+ finish: /\bsdk\s*\.\s*(?:finish|playcraftFinish)\s*\(/g,
18
+ install: /\bsdk\s*\.\s*(?:install|playcraftInstall)\s*\(/g,
19
+ };
20
+ /**
21
+ * Judges a built artifact by running each requested stage independently and collecting their
22
+ * reports. Stages never read each other's results, so any stage can also be called on its own.
23
+ * Results depend only on the artifact and the options, never on how the artifact was built.
24
+ */
25
+ export async function runArtifactQa(artifact, options = {}) {
26
+ const profile = options.profile ?? 'playcraft';
27
+ const stages = [];
28
+ for (const stage of options.stages ?? QA_STAGES)
29
+ stages.push(await runStage(stage, artifact, { ...options, profile }));
30
+ const counted = stages.filter((stage) => stage.status === 'ran' && !stage.advisory);
31
+ return {
32
+ version: ARTIFACT_QA_REPORT_VERSION,
33
+ rulesVersion: ARTIFACT_QA_RULES_VERSION,
34
+ profile,
35
+ artifact: {
36
+ sourcePath: artifact.sourcePath,
37
+ container: artifact.container,
38
+ layout: artifact.layout,
39
+ entry: artifact.entry,
40
+ digest: artifact.digest,
41
+ totalSize: artifact.totalSize,
42
+ fileCount: artifact.files.length,
43
+ },
44
+ summary: summarize(counted.flatMap((stage) => stage.results), counted.flatMap((stage) => stage.manualChecklist), counted.flatMap((stage) => stage.externalChecklist)),
45
+ incomplete: stages.some((stage) => stage.status === 'skipped' && !stage.advisory),
46
+ stages,
47
+ };
48
+ }
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
+ /**
77
+ * `channel` stage: the channel's existing `html-artifact` / `delivery-package` rules, the same
78
+ * rules export validation uses. Needs only the artifact and a channel profile.
79
+ */
80
+ export async function runChannelStage(artifact, options) {
81
+ if (options.profile === 'playcraft')
82
+ return idleStageReport('channel', 'not-applicable', 'The playcraft profile has no channel rules');
83
+ const startedAt = Date.now();
84
+ const report = await runPlayableValidation({
85
+ projectRoot: path.dirname(artifact.sourcePath),
86
+ channel: options.profile,
87
+ engine: 'unknown',
88
+ buildChain: 'generic',
89
+ ...channelPaths(artifact),
90
+ }, stagesFor(artifact));
91
+ return ranStageReport('channel', startedAt, report.results, {
92
+ manualChecklist: report.manualChecklist,
93
+ 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 });
104
+ }
105
+ /** Same stage choice as the workspace delivery re-check: HTML artifacts, or the delivery package. */
106
+ function stagesFor(artifact) {
107
+ if (artifact.container === 'html')
108
+ return ['html-artifact'];
109
+ if (artifact.container === 'zip')
110
+ return ['delivery-package'];
111
+ return ['html-artifact', 'delivery-package'];
112
+ }
113
+ function channelPaths(artifact) {
114
+ if (artifact.container === 'html')
115
+ return { htmlPath: artifact.sourcePath };
116
+ if (artifact.container === 'zip')
117
+ return { packagePath: artifact.sourcePath };
118
+ return {
119
+ htmlPath: path.join(artifact.sourcePath, artifact.entry),
120
+ packagePath: artifact.sourcePath,
121
+ };
122
+ }
123
+ async function collectSourceHints(projectRoot, profile, sourceGlobs) {
124
+ const root = path.resolve(projectRoot);
125
+ const relative = (file) => file && path.isAbsolute(file) ? path.relative(root, file).replace(/\\/g, '/') : file;
126
+ const hints = (await scanSourceForCompliance({
127
+ projectRoot: root,
128
+ channel: profile,
129
+ engine: 'unknown',
130
+ buildChain: 'generic',
131
+ ...(sourceGlobs ? { sourceGlobs } : {}),
132
+ })).filter((hint) => hint.status !== 'pass');
133
+ hints.push(...(await adsdkHints(root, sourceGlobs)));
134
+ return hints.map((hint) => ({
135
+ ...hint,
136
+ ...(hint.file ? { file: relative(hint.file) } : {}),
137
+ }));
138
+ }
139
+ async function adsdkHints(root, sourceGlobs) {
140
+ const hint = (ruleId, message, recommendation) => ({
141
+ ruleId,
142
+ channel: 'common',
143
+ stage: 'prebuild-source',
144
+ severity: 'warning',
145
+ status: 'warning',
146
+ message,
147
+ recommendation,
148
+ owner: 'playcraft-build',
149
+ confidence: 'medium',
150
+ });
151
+ if (!(await dependsOn(root, ADSDK_PACKAGE)))
152
+ return [
153
+ hint('common.adsdk.dependency.missing', `The project does not depend on ${ADSDK_PACKAGE}.`, `Install ${ADSDK_PACKAGE} and wire sdk.init, start, interactive, finish and install, so CTA and lifecycle signals reach every channel.`),
154
+ ];
155
+ const found = await findSourcePatterns(root, ADSDK_CALLS, sourceGlobs);
156
+ return Object.keys(ADSDK_CALLS)
157
+ .filter((call) => !found.has(call))
158
+ .map((call) => hint(`common.adsdk.${call}.missing`, `No sdk.${call}() call was found in the project source.`, call === 'install'
159
+ ? 'Call sdk.install() from the download / CTA button.'
160
+ : `Call sdk.${call}() at the matching lifecycle point (init → start → interactive → finish → install).`));
161
+ }
162
+ async function dependsOn(root, name) {
163
+ try {
164
+ const manifest = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf-8'));
165
+ return Boolean(manifest.dependencies?.[name] ?? manifest.devDependencies?.[name]);
166
+ }
167
+ catch {
168
+ return false;
169
+ }
170
+ }
@@ -0,0 +1,28 @@
1
+ import type { Platform } from '../types.js';
2
+ import type { PlayableArtifact, QaStageReport } from './types.js';
3
+ /**
4
+ * `base-output` rules: channel-independent checks that read the built artifact only. They do not
5
+ * depend on the engine or the build tool that produced the artifact.
6
+ */
7
+ export declare const BASE_OUTPUT_RULE_IDS: {
8
+ readonly entryParsable: "common.artifact.entry.parsable";
9
+ readonly sizeBudget: "common.artifact.size.budget";
10
+ readonly localReference: "common.artifact.local-reference.resolvable";
11
+ readonly externalResource: "common.artifact.external-resource.forbidden";
12
+ readonly devAddress: "common.artifact.dev-address.forbidden";
13
+ readonly inlineData: "common.artifact.inline-data.valid";
14
+ readonly sizeBreakdown: "common.artifact.size.breakdown";
15
+ readonly debugResidue: "common.artifact.debug-residue.review";
16
+ readonly directRedirect: "common.artifact.redirect.direct.review";
17
+ readonly persistentStorage: "common.artifact.storage.persistent.review";
18
+ readonly viewportMeta: "common.artifact.viewport-meta.present";
19
+ };
20
+ export type BaseOutputRuleId = (typeof BASE_OUTPUT_RULE_IDS)[keyof typeof BASE_OUTPUT_RULE_IDS];
21
+ export interface BaseStageOptions {
22
+ /** Profile whose external-resource allowlist applies; default `playcraft`. */
23
+ profile?: Platform;
24
+ /** Size limit of the profile; default 5 MB, the cap most channels use. */
25
+ sizeLimitBytes?: number;
26
+ }
27
+ /** `base` stage: static checks of the artifact files. Needs only the artifact. */
28
+ export declare function runBaseStage(artifact: PlayableArtifact, options?: BaseStageOptions): Promise<QaStageReport>;