@playcraft/build 0.0.45 → 0.0.46

package/dist/validation/profiles.js

@@ -0,0 +1,222 @@
+const FIVE_MB = 5 * 1024 * 1024;
+const SOURCE_SPEC = 'temp-file/md/各渠道试玩广告规格-gemini.md';
+function sizeRule(channel) {
+    return {
+        id: `${channel}.artifact.size.max-5mb`,
+        title: 'Playable artifact must be smaller than 5 MB',
+        channel,
+        stage: 'html-artifact',
+        severity: 'error',
+        owner: 'playcraft-build',
+        detectable: true,
+        confidence: 'high',
+        description: 'Most playable ad channels cap the final creative artifact at 5 MB.',
+        recommendation: 'Compress or inline assets more aggressively, or remove unused media.',
+        evidenceType: 'file',
+        source: SOURCE_SPEC,
+        check: { kind: 'max-size', maxBytes: FIVE_MB },
+    };
+}
+function externalResourceRule(channel, allowedPatterns) {
+    return {
+        id: `${channel}.html.external-resource.forbidden`,
+        title: 'External runtime resources should not be loaded',
+        channel,
+        stage: 'html-artifact',
+        severity: 'error',
+        owner: 'playcraft-build',
+        detectable: true,
+        confidence: 'high',
+        description: 'Playable ads should not depend on external scripts, styles, images, media, or frames unless the channel explicitly provides that SDK.',
+        recommendation: 'Inline resources into the HTML artifact, or add a channel-specific allowlist when the SDK is officially required.',
+        evidenceType: 'pattern',
+        source: SOURCE_SPEC,
+        check: { kind: 'external-resources', allowedPatterns },
+    };
+}
+function forbiddenPatternRule(channel, idSuffix, title, pattern, recommendation, severity = 'error') {
+    return {
+        id: `${channel}.${idSuffix}`,
+        title,
+        channel,
+        stage: 'html-artifact',
+        severity,
+        owner: 'playcraft-build',
+        detectable: true,
+        confidence: 'high',
+        description: title,
+        recommendation,
+        evidenceType: 'pattern',
+        source: SOURCE_SPEC,
+        check: { kind: 'forbidden-pattern', pattern, flags: 'i' },
+    };
+}
+function requiredPatternRule(channel, idSuffix, title, pattern, recommendation, severity = 'error') {
+    return {
+        id: `${channel}.${idSuffix}`,
+        title,
+        channel,
+        stage: 'html-artifact',
+        severity,
+        owner: 'playcraft-build',
+        detectable: true,
+        confidence: 'high',
+        description: title,
+        recommendation,
+        evidenceType: 'pattern',
+        source: SOURCE_SPEC,
+        check: { kind: 'required-pattern', pattern, flags: 'i' },
+    };
+}
+function sourcePresenceRule(channel, idSuffix, title, recommendation) {
+    return {
+        id: `${channel}.${idSuffix}`,
+        title,
+        channel,
+        stage: 'prebuild-source',
+        severity: 'error',
+        owner: 'playcraft-build',
+        detectable: true,
+        confidence: 'high',
+        description: title,
+        recommendation,
+        evidenceType: 'pattern',
+        source: SOURCE_SPEC,
+    };
+}
+function manualRule(channel, idSuffix, title, recommendation) {
+    return {
+        id: `${channel}.${idSuffix}`,
+        title,
+        channel,
+        stage: 'runtime-manual',
+        severity: 'info',
+        owner: 'manual',
+        detectable: false,
+        confidence: 'medium',
+        description: title,
+        recommendation,
+        evidenceType: 'runtime',
+        source: SOURCE_SPEC,
+    };
+}
+function externalValidatorRule(channel, title, recommendation) {
+    return {
+        id: `${channel}.external-validator.review.required`,
+        title,
+        channel,
+        stage: 'external-validator',
+        severity: 'info',
+        owner: 'external',
+        detectable: false,
+        confidence: 'medium',
+        description: title,
+        recommendation,
+        evidenceType: 'external',
+        source: SOURCE_SPEC,
+    };
+}
+function profile(channel, displayName, deliveryMode, rules, options) {
+    return {
+        channel,
+        displayName,
+        defaultStages: ['prebuild-source', 'html-artifact'],
+        optionalStages: options?.optionalStages ?? [],
+        deliveryMode,
+        internalBuildFormat: options?.internalBuildFormat ?? 'html',
+        deliveryPackageFormat: options?.deliveryPackageFormat,
+        devkitOwned: options?.devkitOwned,
+        rules: [sizeRule(channel), ...rules],
+    };
+}
+export const CHANNEL_RULE_PROFILES = {
+    playcraft: {
+        channel: 'playcraft',
+        displayName: 'PlayCraft',
+        defaultStages: ['prebuild-source', 'html-artifact'],
+        optionalStages: [],
+        deliveryMode: 'mixed',
+        internalBuildFormat: 'html',
+        deliveryPackageFormat: 'mixed',
+        rules: [],
+    },
+    applovin: profile('applovin', 'AppLovin', 'single-html', [
+        externalResourceRule('applovin'),
+        requiredPatternRule('applovin', 'cta.mraid-open.required', 'CTA should use mraid.open()', '\\bmraid\\.open\\s*\\(', 'Route store jumps through mraid.open().'),
+        manualRule('applovin', 'runtime.orientation-and-cta.manual', 'Landscape, portrait, and CTA visibility need runtime review.', 'Verify both orientations and that CTA stays visible throughout the playable.'),
+        externalValidatorRule('applovin', 'AppLovin preview should be used before delivery.', 'Upload the final creative to AppLovin Preview or Preview Tool.'),
+    ], { optionalStages: ['runtime-manual', 'external-validator'] }),
+    google: profile('google', 'Google', 'html-backed-zip', [
+        externalResourceRule('google'),
+        forbiddenPatternRule('google', 'network.fetch.forbidden', 'Google creatives should not make runtime network requests.', '\\b(fetch|XMLHttpRequest|WebSocket|EventSource)\\b', 'Remove runtime network calls or mark approved analytics separately.'),
+        manualRule('google', 'runtime.audio-and-gesture.manual', 'Audio before interaction and download button animation need runtime review.', 'Confirm the creative is silent before interaction and CTA gestures do not scale improperly.'),
+        externalValidatorRule('google', 'Google H5 Validator should be used before delivery.', 'Validate the delivery package with Google H5 Validator.'),
+    ], { optionalStages: ['delivery-package', 'runtime-manual', 'external-validator'], deliveryPackageFormat: 'zip' }),
+    facebook: profile('facebook', 'Facebook / Meta', 'mixed', [
+        externalResourceRule('facebook'),
+        forbiddenPatternRule('facebook', 'sdk.mraid-js.forbidden', 'Facebook creatives should not include mraid.js.', 'mraid\\.js', 'Remove mraid.js and use Facebook playable APIs.'),
+        requiredPatternRule('facebook', 'cta.fb-on-click.recommended', 'CTA should call FbPlayableAd.onCTAClick().', 'FbPlayableAd\\.onCTAClick\\s*\\(', 'Route CTA clicks through FbPlayableAd.onCTAClick().', 'warning'),
+        manualRule('facebook', 'runtime.portrait-and-cta.manual', 'Portrait display and CTA clickability need runtime review.', 'Verify portrait layout and CTA behavior in Meta preview.'),
+    ], { optionalStages: ['delivery-package', 'runtime-manual'], deliveryPackageFormat: 'mixed' }),
+    tiktok: profile('tiktok', 'TikTok / Pangle', 'zip', [
+        forbiddenPatternRule('tiktok', 'sdk.mraid-js.forbidden', 'TikTok/Pangle creatives should not include mraid.js.', 'mraid\\.js', 'Remove mraid.js; Pangle integration belongs to the channel SDK.'),
+        forbiddenPatternRule('tiktok', 'redirect.javascript.forbidden', 'TikTok/Pangle creatives should not contain JavaScript redirects.', '\\blocation\\.(href|assign|replace)\\b|window\\.open\\s*\\(', 'Remove automatic redirects and delegate store jumps to Pangle.'),
+    ], { optionalStages: ['delivery-package'], deliveryPackageFormat: 'zip', devkitOwned: true, internalBuildFormat: 'delegated' }),
+    unity: profile('unity', 'Unity Ads', 'single-html', [
+        sourcePresenceRule('unity', 'mraid.viewable-change.required', 'Unity requires MRAID viewableChange before gameplay starts.', 'Add a viewableChange listener before starting playable content.'),
+        externalResourceRule('unity'),
+        requiredPatternRule('unity', 'cta.mraid-open.required', 'Unity CTA should use mraid.open().', '\\bmraid\\.open\\s*\\(', 'Route the CTA directly to the store through mraid.open().'),
+        requiredPatternRule('unity', 'mraid.viewable-change.required', 'Unity playable should wait for MRAID viewableChange.', 'viewableChange', 'Wait for the MRAID viewableChange event before starting gameplay.'),
+        manualRule('unity', 'runtime.orientation-and-start.manual', 'Orientation support and gameplay start timing need runtime review.', 'Verify portrait/landscape support and that gameplay waits for viewability.'),
+    ], { optionalStages: ['runtime-manual'] }),
+    ironsource: profile('ironsource', 'ironSource', 'mixed', [
+        forbiddenPatternRule('ironsource', 'redirect.auto.forbidden', 'ironSource creatives should not auto-redirect to the store.', '\\blocation\\.(href|assign|replace)\\b', 'Keep store jumps behind a user CTA.'),
+        manualRule('ironsource', 'runtime.loading-audio-controls.manual', 'Loading time, mute, close, and info buttons need runtime review.', 'Verify load time, audio behavior, mute button, close button, and info button.'),
+    ], { optionalStages: ['runtime-manual'], deliveryPackageFormat: 'mixed' }),
+    liftoff: profile('liftoff', 'Liftoff', 'zip', [
+        manualRule('liftoff', 'package.entry.manual', 'ZIP entry and folder structure need delivery review.', 'Confirm the ZIP has a single entry folder and a reachable root entry file.'),
+        externalValidatorRule('liftoff', 'Liftoff validator should be used before delivery.', 'Validate with Liftoff Interactive Ad Validator or Creative Verifier.'),
+    ], { optionalStages: ['delivery-package', 'external-validator'], deliveryPackageFormat: 'zip' }),
+    moloco: profile('moloco', 'Moloco', 'single-html', [
+        externalResourceRule('moloco'),
+        forbiddenPatternRule('moloco', 'sdk.mraid-js.forbidden', 'Moloco creatives should not include mraid.js.', 'mraid\\.js', 'Remove mraid.js and use Facebook-compatible CTA handling.'),
+        requiredPatternRule('moloco', 'cta.fb-on-click.required', 'Moloco CTA should use FbPlayableAd.onCTAClick().', 'FbPlayableAd\\.onCTAClick\\s*\\(', 'Route CTA clicks through FbPlayableAd.onCTAClick().'),
+        manualRule('moloco', 'runtime.portrait-responsive.manual', 'Portrait responsive behavior needs runtime review.', 'Verify portrait layout and CTA visibility.'),
+    ], { optionalStages: ['runtime-manual'] }),
+    bigo: profile('bigo', 'BIGO', 'zip', [
+        sourcePresenceRule('bigo', 'lifecycle.game-end.required', 'BIGO requires window.BGY_MRAID.gameEnd() when gameplay ends.', 'Call window.BGY_MRAID.gameEnd() when gameplay ends.'),
+        externalResourceRule('bigo', ['static-web.likeevideo.com']),
+        requiredPatternRule('bigo', 'cta.bgy-open.required', 'BIGO CTA should use window.BGY_MRAID.open().', 'window\\.BGY_MRAID\\.open\\s*\\(', 'Route CTA clicks through window.BGY_MRAID.open().'),
+        requiredPatternRule('bigo', 'lifecycle.game-end.required', 'BIGO creatives should call window.BGY_MRAID.gameEnd().', 'window\\.BGY_MRAID\\.gameEnd\\s*\\(', 'Call gameEnd() when gameplay ends.'),
+    ], { optionalStages: ['delivery-package'], deliveryPackageFormat: 'zip', devkitOwned: true, internalBuildFormat: 'delegated' }),
+    inmobi: profile('inmobi', 'InMobi', 'mixed', [
+        requiredPatternRule('inmobi', 'sdk.mraid-js.required', 'InMobi creatives should include mraid.js or MRAID support.', 'mraid', 'Include the channel-required MRAID integration.'),
+        requiredPatternRule('inmobi', 'cta.mraid-open.required', 'InMobi redirects should use mraid.open(url).', '\\bmraid\\.open\\s*\\(', 'Route store redirects through mraid.open(url).'),
+    ], { optionalStages: ['delivery-package', 'runtime-manual'], deliveryPackageFormat: 'mixed' }),
+    adikteev: profile('adikteev', 'Adikteev', 'fragment-assets', [
+        requiredPatternRule('adikteev', 'cta.mraid-open.required', 'Adikteev CTA should use mraid.open().', '\\bmraid\\.open\\s*\\(', 'Route CTA clicks through mraid.open().'),
+        requiredPatternRule('adikteev', 'click-pixel-url.required', 'Adikteev requires AK_CLICK_PIXEL_URL exposure.', 'AK_CLICK_PIXEL_URL|AK CLICK PIXEL URL', 'Expose the Adikteev click pixel URL variable.'),
+        manualRule('adikteev', 'runtime.cdn-responsive.manual', 'CDN resource loading and responsive layout need runtime review.', 'Verify separated assets load from Adikteev CDN and remain responsive.'),
+    ], { optionalStages: ['delivery-package', 'runtime-manual'], deliveryPackageFormat: 'fragment-assets' }),
+    remerge: profile('remerge', 'Remerge', 'single-html', [
+        externalResourceRule('remerge'),
+        forbiddenPatternRule('remerge', 'redirect.auto.forbidden', 'Remerge creatives should not auto-redirect to the store.', '\\blocation\\.(href|assign|replace)\\b', 'Keep store jumps behind a user CTA.'),
+    ]),
+    mintegral: profile('mintegral', 'Mintegral', 'mixed', [
+        sourcePresenceRule('mintegral', 'lifecycle.sdk-finish.required', 'Mintegral requires sdk.finish() after gameplay ends.', 'Call sdk.finish() when gameplay reaches win or end state.'),
+        requiredPatternRule('mintegral', 'lifecycle.sdk-finish.required', 'Mintegral creatives should call sdk.finish() after win or end.', '\\bsdk\\.finish\\s*\\(', 'Call sdk.finish() at the end of gameplay.'),
+        forbiddenPatternRule('mintegral', 'redirect.auto.forbidden', 'Mintegral creatives should not auto-redirect to the store.', '\\blocation\\.(href|assign|replace)\\b', 'Keep store jumps behind a user CTA.'),
+        externalValidatorRule('mintegral', 'Mindworks testing should be used before delivery.', 'Validate through the Mintegral/Mindworks testing entry.'),
+    ], { optionalStages: ['external-validator'], deliveryPackageFormat: 'mixed' }),
+    snapchat: profile('snapchat', 'Snapchat', 'zip', [
+        forbiddenPatternRule('snapchat', 'sdk.mraid-js.forbidden', 'Snapchat creatives should not include mraid.js.', 'mraid\\.js', 'Remove mraid.js and use Snapchat playable APIs.'),
+        requiredPatternRule('snapchat', 'cta.sc-on-click.required', 'Snapchat CTA should call ScPlayableAd.onCTAClick().', 'ScPlayableAd\\.onCTAClick\\s*\\(', 'Route CTA clicks through ScPlayableAd.onCTAClick().'),
+        manualRule('snapchat', 'runtime.portrait-and-cta.manual', 'Portrait display and CTA availability need runtime review.', 'Verify portrait layout and CTA behavior.'),
+    ], { optionalStages: ['delivery-package', 'runtime-manual'], deliveryPackageFormat: 'zip' }),
+};
+export function getChannelRuleProfile(channel) {
+    return CHANNEL_RULE_PROFILES[channel];
+}
+export function getRulesForStage(channel, stage) {
+    return getChannelRuleProfile(channel).rules.filter((rule) => rule.stage === stage);
+}

package/dist/validation/reporter.d.ts

@@ -0,0 +1,4 @@
+import type { ValidationReport } from './types.js';
+export declare function saveValidationReport(report: ValidationReport, reportPath: string): Promise<void>;
+export declare function formatValidationSummary(report: ValidationReport): string;
+export declare function hasBlockingValidationErrors(report: ValidationReport): boolean;

package/dist/validation/reporter.js

@@ -0,0 +1,30 @@
+import fs from 'fs/promises';
+import path from 'path';
+export async function saveValidationReport(report, reportPath) {
+    await fs.mkdir(path.dirname(reportPath), { recursive: true });
+    await fs.writeFile(reportPath, JSON.stringify(report, null, 2), 'utf-8');
+}
+export function formatValidationSummary(report) {
+    const lines = [
+        `[Validation] channel=${report.channel}, chain=${report.buildChain}, status=${report.summary.status}`,
+        `[Validation] errors=${report.summary.errorCount}, warnings=${report.summary.warningCount}, manual=${report.summary.manualCount}, external=${report.summary.externalCount}`,
+    ];
+    const failed = report.results.filter((result) => result.status === 'fail');
+    const warnings = report.results.filter((result) => result.status === 'warning');
+    for (const result of [...failed, ...warnings].slice(0, 10)) {
+        lines.push(`  - ${result.status.toUpperCase()} ${result.ruleId}: ${result.message}`);
+        if (result.file) {
+            lines.push(`    file=${result.file}${result.line ? `:${result.line}` : ''}`);
+        }
+        if (result.evidence) {
+            lines.push(`    evidence=${result.evidence}`);
+        }
+    }
+    if (failed.length + warnings.length > 10) {
+        lines.push(`  ... ${failed.length + warnings.length - 10} more validation results`);
+    }
+    return lines.join('\n');
+}
+export function hasBlockingValidationErrors(report) {
+    return report.results.some((result) => result.status === 'fail' && result.severity === 'error');
+}

package/dist/validation/source-scanner.d.ts

@@ -0,0 +1,4 @@
+import type { Platform } from '../types.js';
+import type { ValidationContext, ValidationResult } from './types.js';
+export declare function scanSourceForCompliance(context: ValidationContext): Promise<ValidationResult[]>;
+export declare function scanSourceForChannels(context: Omit<ValidationContext, 'channel'>, channels: Platform[]): Promise<ValidationResult[]>;

package/dist/validation/source-scanner.js

@@ -0,0 +1,271 @@
+import fs from 'fs/promises';
+import path from 'path';
+import { getRulesForStage } from './profiles.js';
+const SOURCE_EXTENSIONS = new Set(['.js', '.jsx', '.ts', '.tsx', '.html', '.css']);
+const IGNORED_DIRS = new Set([
+    '.git',
+    '.playcraft-temp',
+    'coverage',
+    'dist',
+    'build',
+    'node_modules',
+    'out',
+]);
+const COMMON_SOURCE_PATTERNS = [
+    {
+        ruleId: 'common.redirect.location.forbidden',
+        pattern: /\blocation\.(?:href|assign|replace)\b/g,
+        message: 'Source contains a direct location redirect.',
+        recommendation: 'Move store jumps behind the channel CTA API and an explicit user action.',
+        severity: 'warning',
+        confidence: 'medium',
+    },
+    {
+        ruleId: 'common.redirect.window-open.review',
+        pattern: /\bwindow\.open\s*\(/g,
+        message: 'Source contains window.open().',
+        recommendation: 'Confirm the call is only triggered by an explicit CTA click.',
+        severity: 'warning',
+        confidence: 'medium',
+    },
+    {
+        ruleId: 'common.network.fetch.review',
+        pattern: /\b(?:fetch|XMLHttpRequest|WebSocket|EventSource)\b/g,
+        message: 'Source contains a runtime network API.',
+        recommendation: 'Remove runtime network dependency unless the channel allows analytics-only calls.',
+        severity: 'warning',
+        confidence: 'medium',
+    },
+    {
+        ruleId: 'common.audio.autoplay.review',
+        pattern: /<audio\b[^>]*\bautoplay\b|new\s+Audio\s*\([^)]*\)\.play\s*\(|AudioContext\s*\([^)]*\).*?resume\s*\(/gs,
+        message: 'Source contains a possible audio autoplay pattern.',
+        recommendation: 'Start audio only after user interaction and stop it when the ad is not viewable.',
+        severity: 'warning',
+        confidence: 'low',
+    },
+    {
+        ruleId: 'common.layout.fixed-size.review',
+        pattern: /\b(?:canvas|body|#?app|#?root)[^{]{0,80}\{[^}]*\b(?:width|height)\s*:\s*\d{3,4}px/gs,
+        message: 'Source contains a possible fixed-size layout.',
+        recommendation: 'Use responsive sizing so the playable can adapt to mobile viewports.',
+        severity: 'warning',
+        confidence: 'low',
+    },
+];
+const CHANNEL_SOURCE_PATTERNS = {
+    unity: [
+        {
+            ruleId: 'unity.mraid.viewable-change.required',
+            pattern: /viewableChange/g,
+            message: 'Unity requires waiting for MRAID viewableChange before starting playable content.',
+            recommendation: 'Add a viewableChange listener and start gameplay only after the ad is viewable.',
+            severity: 'error',
+            confidence: 'high',
+        },
+    ],
+    mintegral: [
+        {
+            ruleId: 'mintegral.lifecycle.sdk-finish.required',
+            pattern: /\bsdk\.finish\s*\(/g,
+            message: 'Mintegral requires sdk.finish() after gameplay ends.',
+            recommendation: 'Call sdk.finish() when the win or end state is reached.',
+            severity: 'error',
+            confidence: 'high',
+        },
+    ],
+    bigo: [
+        {
+            ruleId: 'bigo.lifecycle.game-end.required',
+            pattern: /window\.BGY_MRAID\.gameEnd\s*\(/g,
+            message: 'BIGO requires window.BGY_MRAID.gameEnd() when gameplay ends.',
+            recommendation: 'Call window.BGY_MRAID.gameEnd() at the end of gameplay.',
+            severity: 'error',
+            confidence: 'high',
+        },
+    ],
+};
+export async function scanSourceForCompliance(context) {
+    const sourceFiles = await collectSourceFiles(context.projectRoot, context.sourceGlobs);
+    return scanSourceFilesForChannel(context, sourceFiles, true);
+}
+export async function scanSourceForChannels(context, channels) {
+    const sourceFiles = await collectSourceFiles(context.projectRoot, context.sourceGlobs);
+    const results = [];
+    for (const filePath of sourceFiles) {
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        for (const pattern of COMMON_SOURCE_PATTERNS) {
+            results.push(...evaluateSourcePatternForChannel(context, 'common', filePath, content, pattern));
+        }
+    }
+    for (const channel of unique(channels)) {
+        results.push(...await scanSourceFilesForChannel({ ...context, channel }, sourceFiles, false));
+    }
+    return results;
+}
+async function scanSourceFilesForChannel(context, sourceFiles, includeCommonPatterns) {
+    const results = [];
+    const requiredPatterns = CHANNEL_SOURCE_PATTERNS[context.channel] ?? [];
+    const matchedRequiredRuleIds = new Set();
+    for (const filePath of sourceFiles) {
+        let content;
+        try {
+            content = await fs.readFile(filePath, 'utf-8');
+        }
+        catch {
+            continue;
+        }
+        if (includeCommonPatterns) {
+            for (const pattern of COMMON_SOURCE_PATTERNS) {
+                results.push(...evaluateSourcePattern(context, filePath, content, pattern, false));
+            }
+        }
+        for (const pattern of requiredPatterns) {
+            if (matchedRequiredRuleIds.has(pattern.ruleId)) {
+                continue;
+            }
+            const match = content.match(pattern.pattern);
+            if (match) {
+                matchedRequiredRuleIds.add(pattern.ruleId);
+                results.push({
+                    ruleId: pattern.ruleId,
+                    channel: context.channel,
+                    stage: 'prebuild-source',
+                    severity: pattern.severity,
+                    status: 'pass',
+                    message: `${pattern.message}: passed`,
+                    recommendation: pattern.recommendation,
+                    file: filePath,
+                    line: lineOfIndex(content, content.search(pattern.pattern)),
+                    evidence: trimEvidence(match[0]),
+                    owner: ownerForContext(context),
+                    confidence: pattern.confidence,
+                });
+            }
+        }
+    }
+    results.push(...missingRequiredPatternResults(context, matchedRequiredRuleIds));
+    return results;
+}
+function evaluateSourcePatternForChannel(context, channel, filePath, content, sourcePattern) {
+    const matches = Array.from(content.matchAll(sourcePattern.pattern));
+    return matches.slice(0, 10).map((match) => ({
+        ruleId: sourcePattern.ruleId,
+        channel,
+        stage: 'prebuild-source',
+        severity: sourcePattern.severity,
+        status: sourcePattern.severity === 'error' ? 'fail' : 'warning',
+        message: sourcePattern.message,
+        recommendation: sourcePattern.recommendation,
+        file: filePath,
+        line: lineOfIndex(content, match.index ?? 0),
+        evidence: trimEvidence(match[0]),
+        owner: ownerForContext(context),
+        confidence: sourcePattern.confidence,
+    }));
+}
+async function collectSourceFiles(projectRoot, explicitGlobs) {
+    if (explicitGlobs && explicitGlobs.length > 0) {
+        const files = [];
+        for (const item of explicitGlobs) {
+            const fullPath = path.isAbsolute(item) ? item : path.join(projectRoot, item);
+            try {
+                const stat = await fs.stat(fullPath);
+                if (stat.isFile() && SOURCE_EXTENSIONS.has(path.extname(fullPath).toLowerCase())) {
+                    files.push(fullPath);
+                }
+                else if (stat.isDirectory()) {
+                    files.push(...await walkSourceFiles(fullPath));
+                }
+            }
+            catch {
+                // Ignore missing explicit entries; the report stays focused on detected evidence.
+            }
+        }
+        return unique(files);
+    }
+    return walkSourceFiles(projectRoot);
+}
+async function walkSourceFiles(dir) {
+    const files = [];
+    let entries;
+    try {
+        entries = await fs.readdir(dir, { withFileTypes: true });
+    }
+    catch {
+        return files;
+    }
+    for (const entry of entries) {
+        const fullPath = path.join(dir, entry.name);
+        if (entry.isDirectory()) {
+            if (!IGNORED_DIRS.has(entry.name)) {
+                files.push(...await walkSourceFiles(fullPath));
+            }
+            continue;
+        }
+        if (entry.isFile() && SOURCE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+            files.push(fullPath);
+        }
+    }
+    return files;
+}
+function evaluateSourcePattern(context, filePath, content, sourcePattern, requiredPresence) {
+    const matches = Array.from(content.matchAll(sourcePattern.pattern));
+    if (requiredPresence) {
+        return [];
+    }
+    return matches.slice(0, 10).map((match) => ({
+        ruleId: sourcePattern.ruleId,
+        channel: context.channel,
+        stage: 'prebuild-source',
+        severity: sourcePattern.severity,
+        status: sourcePattern.severity === 'error' ? 'fail' : 'warning',
+        message: sourcePattern.message,
+        recommendation: sourcePattern.recommendation,
+        file: filePath,
+        line: lineOfIndex(content, match.index ?? 0),
+        evidence: trimEvidence(match[0]),
+        owner: ownerForContext(context),
+        confidence: sourcePattern.confidence,
+    }));
+}
+function missingRequiredPatternResults(context, matchedRequiredRuleIds) {
+    const channelPatterns = CHANNEL_SOURCE_PATTERNS[context.channel] ?? [];
+    const results = [];
+    const sourceRuleIds = new Set(getRulesForStage(context.channel, 'prebuild-source').map((rule) => rule.id));
+    for (const pattern of channelPatterns) {
+        if (matchedRequiredRuleIds.has(pattern.ruleId) || !sourceRuleIds.has(pattern.ruleId)) {
+            continue;
+        }
+        results.push({
+            ruleId: pattern.ruleId,
+            channel: context.channel,
+            stage: 'prebuild-source',
+            severity: pattern.severity,
+            status: pattern.severity === 'error' ? 'fail' : 'warning',
+            message: pattern.message,
+            recommendation: pattern.recommendation,
+            owner: ownerForContext(context),
+            confidence: pattern.confidence,
+        });
+    }
+    return results;
+}
+function ownerForContext(context) {
+    return context.buildChain === 'devkit' ? 'devkit' : 'playcraft-build';
+}
+function lineOfIndex(content, index) {
+    return content.slice(0, index).split(/\r?\n/).length;
+}
+function trimEvidence(value) {
+    return value.replace(/\s+/g, ' ').trim().slice(0, 200);
+}
+function unique(items) {
+    return Array.from(new Set(items));
+}

package/dist/validation/types.d.ts

@@ -0,0 +1,112 @@
+import type { BuildTool, EngineType, OutputFormat, Platform } from '../types.js';
+export type ValidationStage = 'prebuild-source' | 'base-output' | 'html-artifact' | 'delivery-package' | 'runtime-manual' | 'external-validator';
+export type RuleSeverity = 'error' | 'warning' | 'info';
+export type RuleStatus = 'pass' | 'fail' | 'warning' | 'manual' | 'external' | 'not-applicable';
+export type RuleConfidence = 'high' | 'medium' | 'low';
+export type RuleOwner = 'playcraft-build' | 'playcraft-delivery' | 'devkit' | 'manual' | 'external';
+export type DeliveryMode = 'single-html' | 'zip' | 'html-backed-zip' | 'fragment-assets' | 'mixed';
+export type BuildChain = 'generic' | 'devkit' | 'playcanvas-native';
+export type EvidenceType = 'file' | 'pattern' | 'package' | 'runtime' | 'external';
+export type AutoCheck = {
+    kind: 'max-size';
+    maxBytes: number;
+} | {
+    kind: 'external-resources';
+    allowedPatterns?: string[];
+} | {
+    kind: 'required-pattern';
+    pattern: string;
+    flags?: string;
+    evidence?: string;
+} | {
+    kind: 'forbidden-pattern';
+    pattern: string;
+    flags?: string;
+    evidence?: string;
+} | {
+    kind: 'single-html';
+};
+export interface ValidationRule {
+    id: string;
+    title: string;
+    channel: Platform | 'common';
+    stage: ValidationStage;
+    severity: RuleSeverity;
+    owner: RuleOwner;
+    detectable: boolean;
+    confidence: RuleConfidence;
+    description: string;
+    recommendation: string;
+    evidenceType: EvidenceType;
+    source: string;
+    check?: AutoCheck;
+}
+export interface ChannelRuleProfile {
+    channel: Platform;
+    displayName: string;
+    defaultStages: ValidationStage[];
+    optionalStages: ValidationStage[];
+    deliveryMode: DeliveryMode;
+    internalBuildFormat: OutputFormat | 'delegated';
+    deliveryPackageFormat?: OutputFormat | 'fragment-assets' | 'mixed';
+    devkitOwned?: boolean;
+    rules: ValidationRule[];
+}
+export interface ValidationContext {
+    projectRoot: string;
+    channel: Platform;
+    engine: EngineType | 'unknown';
+    buildTool?: BuildTool;
+    buildChain: BuildChain;
+    htmlPath?: string;
+    packagePath?: string;
+    outputDir?: string;
+    sourceGlobs?: string[];
+    metadata?: Record<string, unknown>;
+}
+export interface ManualChecklistItem {
+    ruleId: string;
+    channel: Platform | 'common';
+    stage: ValidationStage;
+    message: string;
+    recommendation: string;
+    owner: RuleOwner;
+}
+export interface ExternalChecklistItem {
+    ruleId: string;
+    channel: Platform | 'common';
+    stage: ValidationStage;
+    message: string;
+    recommendation: string;
+    owner: RuleOwner;
+}
+export interface ValidationResult {
+    ruleId: string;
+    channel: Platform | 'common';
+    stage: ValidationStage;
+    severity: RuleSeverity;
+    status: RuleStatus;
+    message: string;
+    recommendation: string;
+    file?: string;
+    line?: number;
+    evidence?: string;
+    owner: RuleOwner;
+    confidence: RuleConfidence;
+}
+export interface ValidationSummary {
+    status: 'pass' | 'failed' | 'warning' | 'manual-required';
+    errorCount: number;
+    warningCount: number;
+    manualCount: number;
+    externalCount: number;
+}
+export interface ValidationReport {
+    version: string;
+    channel: Platform;
+    buildChain: BuildChain;
+    summary: ValidationSummary;
+    results: ValidationResult[];
+    manualChecklist: ManualChecklistItem[];
+    externalChecklist: ExternalChecklistItem[];
+}

package/dist/validation/types.js

@@ -0,0 +1 @@
+export {};

package/dist/validation/validation-runner.d.ts

@@ -0,0 +1,5 @@
+import type { Platform } from '../types.js';
+import type { ValidationContext, ValidationReport, ValidationStage } from './types.js';
+export declare const VALIDATION_REPORT_VERSION = "0.1.0";
+export declare function runPlayableValidation(context: ValidationContext, stages?: ValidationStage[]): Promise<ValidationReport>;
+export declare function runPlayableSourceValidationForChannels(context: Omit<ValidationContext, 'channel'>, channels: Platform[]): Promise<ValidationReport>;