@gradial/aci 0.1.30 → 0.1.33

package/dist/testing/conformance/checks.js

@@ -0,0 +1,483 @@
+/**
+ * Framework-agnostic conformance checks for ACI site projects.
+ *
+ * Each check function receives a ConformanceContext and returns an array of
+ * ConformanceCheckResult items. Checks are designed to be deterministic,
+ * file-system-only inspections (no network, no process spawning for the
+ * fast checks; build/compile checks shell out).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+import { execSync } from 'node:child_process';
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function ok(name, label, detail) {
+    return { name, label, ok: true, detail };
+}
+function fail(name, label, detail) {
+    return { name, label, ok: false, detail };
+}
+function readTextFile(path) {
+    try {
+        return readFileSync(path, 'utf-8');
+    }
+    catch {
+        return null;
+    }
+}
+function readJSON(path) {
+    const text = readTextFile(path);
+    if (text === null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+function findFirstExisting(root, candidates) {
+    for (const rel of candidates) {
+        const full = join(root, rel);
+        const content = readTextFile(full);
+        if (content !== null) {
+            return { path: full, content };
+        }
+    }
+    return null;
+}
+/**
+ * Walk a directory recursively and return all file paths matching a predicate.
+ * Skips node_modules, .next, .aci, dist, and hidden directories.
+ */
+function walkFiles(dir, predicate) {
+    const results = [];
+    const skipDirs = new Set(['node_modules', '.next', '.aci', 'dist', '.git', '.svn']);
+    function walk(current) {
+        let names;
+        try {
+            names = readdirSync(current);
+        }
+        catch {
+            return;
+        }
+        for (const name of names) {
+            const full = join(current, name);
+            let stat = null;
+            try {
+                stat = statSync(full);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                if (!skipDirs.has(name) && !name.startsWith('.')) {
+                    walk(full);
+                }
+            }
+            else if (predicate(full)) {
+                results.push(full);
+            }
+        }
+    }
+    walk(dir);
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: config — withAci present in framework config
+// ---------------------------------------------------------------------------
+export function checkConfig(ctx) {
+    const results = [];
+    if (ctx.framework === 'next') {
+        const configFile = findFirstExisting(ctx.rootDir, [
+            'next.config.ts',
+            'next.config.mts',
+            'next.config.js',
+            'next.config.mjs',
+            'next.config.cjs',
+        ]);
+        if (!configFile) {
+            results.push(fail('config', 'next config file exists'));
+            return results;
+        }
+        results.push(ok('config', 'next config file exists', relative(ctx.rootDir, configFile.path)));
+        const hasWithAci = configFile.content.includes('withAci');
+        results.push(hasWithAci
+            ? ok('config', 'next config uses withAci', relative(ctx.rootDir, configFile.path))
+            : fail('config', 'next config uses withAci', 'withAci() wrapper not found in ' + relative(ctx.rootDir, configFile.path)));
+        const hasStaticExport = /output\s*:\s*['"]export['"]/.test(configFile.content.replace(/\/\/.*/g, ''));
+        results.push(!hasStaticExport
+            ? ok('config', 'next config does not use static export')
+            : fail('config', 'next config does not use static export', 'output: "export" found'));
+    }
+    if (ctx.framework === 'astro') {
+        const configFile = findFirstExisting(ctx.rootDir, [
+            'astro.config.ts',
+            'astro.config.mts',
+            'astro.config.js',
+            'astro.config.mjs',
+        ]);
+        if (!configFile) {
+            results.push(fail('config', 'astro config file exists'));
+            return results;
+        }
+        results.push(ok('config', 'astro config file exists', relative(ctx.rootDir, configFile.path)));
+        const hasWithAci = configFile.content.includes('withAci');
+        results.push(hasWithAci
+            ? ok('config', 'astro config uses withAci', relative(ctx.rootDir, configFile.path))
+            : fail('config', 'astro config uses withAci', 'withAci() not found in ' + relative(ctx.rootDir, configFile.path)));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: registry — createRegistry used with typed contracts
+// ---------------------------------------------------------------------------
+export function checkRegistry(ctx) {
+    const results = [];
+    // Find registry file(s) — look for files that import createRegistry
+    const sourceFiles = walkFiles(ctx.rootDir, (p) => /\.(ts|tsx|js|jsx)$/.test(p));
+    const registryFiles = sourceFiles.filter((f) => {
+        const content = readTextFile(f);
+        return content !== null && content.includes('createRegistry');
+    });
+    if (registryFiles.length === 0) {
+        results.push(fail('registry', 'createRegistry usage found', 'no file imports createRegistry from @gradial/aci'));
+        return results;
+    }
+    for (const file of registryFiles) {
+        const content = readTextFile(file);
+        const rel = relative(ctx.rootDir, file);
+        results.push(ok('registry', 'createRegistry usage found', rel));
+        // Check that the registry imports from @gradial/aci (not a local copy)
+        const importsFromSDK = content.includes("from '@gradial/aci'") ||
+            content.includes('from "@gradial/aci"') ||
+            content.includes("from '@gradial/aci/") ||
+            content.includes('from "@gradial/aci/');
+        results.push(importsFromSDK
+            ? ok('registry', 'registry imports from @gradial/aci', rel)
+            : fail('registry', 'registry imports from @gradial/aci', rel + ' should import createRegistry from @gradial/aci'));
+        // Check that contracts are used (tuple pattern [contract, Component])
+        const hasTuplePattern = /createRegistry\s*\(\s*\[/.test(content);
+        results.push(hasTuplePattern
+            ? ok('registry', 'registry uses typed contract tuples', rel)
+            : fail('registry', 'registry uses typed contract tuples', rel + ' should pass [contract, Component] tuples to createRegistry'));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: pageEntry — catch-all page correctness
+// ---------------------------------------------------------------------------
+export function checkPageEntry(ctx) {
+    const results = [];
+    if (ctx.framework !== 'next') {
+        // Astro pages have a different pattern; skip for now
+        return results;
+    }
+    // Find the app root (src/app or app)
+    const appRoot = existsSync(join(ctx.rootDir, 'src', 'app'))
+        ? join(ctx.rootDir, 'src', 'app')
+        : join(ctx.rootDir, 'app');
+    const pageFile = findFirstExisting(appRoot, [
+        '[[...slug]]/page.tsx',
+        '[[...slug]]/page.ts',
+        '[[...slug]]/page.jsx',
+        '[[...slug]]/page.js',
+        '[...slug]/page.tsx',
+        '[...slug]/page.ts',
+        '[...slug]/page.jsx',
+        '[...slug]/page.js',
+    ]);
+    if (!pageFile) {
+        results.push(fail('pageEntry', 'next CMS catch-all page exists', 'expected [[...slug]]/page.tsx or [...slug]/page.tsx'));
+        return results;
+    }
+    const rel = relative(ctx.rootDir, pageFile.path);
+    results.push(ok('pageEntry', 'next CMS catch-all page exists', rel));
+    const usesSDK = pageFile.content.includes("@gradial/aci/next/server") ||
+        pageFile.content.includes("@gradial/aci/next'") ||
+        pageFile.content.includes('@gradial/aci/next"');
+    results.push(usesSDK
+        ? ok('pageEntry', 'page uses @gradial/aci SDK', rel)
+        : fail('pageEntry', 'page uses @gradial/aci SDK', rel + ' should import from @gradial/aci/next'));
+    const usesCreatePage = pageFile.content.includes('createPage') ||
+        pageFile.content.includes('routeFromNextParams');
+    results.push(usesCreatePage
+        ? ok('pageEntry', 'page uses createPage or routeFromNextParams', rel)
+        : fail('pageEntry', 'page uses createPage or routeFromNextParams', rel));
+    const normalized = pageFile.content.replace(/\s+/g, ' ');
+    const hasForceDynamic = normalized.includes("dynamic = 'force-dynamic'") ||
+        normalized.includes('dynamic = "force-dynamic"');
+    results.push(hasForceDynamic
+        ? ok('pageEntry', 'page exports force-dynamic', rel)
+        : fail('pageEntry', 'page exports force-dynamic', rel + ' should export const dynamic = "force-dynamic"'));
+    const hasGenerateStaticParams = pageFile.content.includes('generateStaticParams');
+    results.push(!hasGenerateStaticParams
+        ? ok('pageEntry', 'page does not use generateStaticParams', rel)
+        : fail('pageEntry', 'page does not use generateStaticParams', rel + ' should not export generateStaticParams'));
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: middleware — presence and siteId (Next)
+// ---------------------------------------------------------------------------
+export function checkMiddleware(ctx) {
+    const results = [];
+    if (ctx.framework !== 'next') {
+        return results;
+    }
+    const middlewareFile = findFirstExisting(ctx.rootDir, [
+        'src/middleware.ts',
+        'src/middleware.js',
+        'middleware.ts',
+        'middleware.js',
+    ]);
+    if (!middlewareFile) {
+        results.push(fail('middleware', 'next middleware.ts exists', 'expected src/middleware.ts or middleware.ts'));
+        return results;
+    }
+    const rel = relative(ctx.rootDir, middlewareFile.path);
+    results.push(ok('middleware', 'next middleware.ts exists', rel));
+    const usesSDKMiddleware = middlewareFile.content.includes('createGradialMiddleware') ||
+        middlewareFile.content.includes('@gradial/aci/next/middleware');
+    results.push(usesSDKMiddleware
+        ? ok('middleware', 'middleware uses createGradialMiddleware', rel)
+        : fail('middleware', 'middleware uses createGradialMiddleware', rel + ' should use createGradialMiddleware from @gradial/aci/next/middleware'));
+    // Check if siteId is configured as a literal (no env var indirection)
+    if (ctx.siteId) {
+        const hasSiteIdLiteral = middlewareFile.content.includes(`siteId`) &&
+            !middlewareFile.content.includes('process.env');
+        results.push(hasSiteIdLiteral
+            ? ok('middleware', 'middleware configures siteId (literal)', rel)
+            : fail('middleware', 'middleware configures siteId (literal)', rel + ' should pass a literal siteId string to createGradialMiddleware (no env var indirection)'));
+    }
+    // Check that the middleware matcher is inlined (not imported) and matches
+    // the SDK's canonical value. Next.js requires config.matcher to be
+    // statically analyzable, so importing the matcher from the SDK breaks the
+    // build. Instead the template inlines the value and this check detects drift.
+    const canonicalMatcher = "['/((?!_next(?:/|$)|api(?:/|$)|favicon\\\\.ico$|\\\\.gradial-dam(?:/|$)).*)']";
+    // Check for actual import/usage of aciMiddlewareMatcher (not just a mention
+    // in a comment). Look for `matcher: aciMiddlewareMatcher` or
+    // `import { ... aciMiddlewareMatcher ... }`.
+    const hasImportedMatcher = /matcher\s*:\s*aciMiddlewareMatcher/.test(middlewareFile.content) ||
+        /import\s+.*aciMiddlewareMatcher.*from/.test(middlewareFile.content);
+    if (hasImportedMatcher) {
+        results.push(fail('middleware', 'middleware matcher is inlined (not imported)', rel + ' should inline the matcher value for Next.js static analysis; see @gradial/aci/next/middleware for the canonical value'));
+    }
+    else {
+        // Verify the inlined value matches the SDK canonical
+        const matcherMatch = middlewareFile.content.match(/matcher\s*:\s*(\[.*?\])/s);
+        if (matcherMatch) {
+            const normalizedInlined = matcherMatch[1].replace(/\s+/g, '');
+            const normalizedCanonical = canonicalMatcher.replace(/\s+/g, '');
+            results.push(normalizedInlined === normalizedCanonical
+                ? ok('middleware', 'middleware matcher matches SDK canonical', rel)
+                : fail('middleware', 'middleware matcher matches SDK canonical', `${rel}: inlined matcher does not match SDK's aciMiddlewareMatcher; expected ${canonicalMatcher}`));
+        }
+        else {
+            results.push(fail('middleware', 'middleware matcher is defined', rel + ' should define config.matcher'));
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: noFileContentProvider — no direct FileContentProvider imports in app code
+// ---------------------------------------------------------------------------
+export function checkNoFileContentProvider(ctx) {
+    const results = [];
+    // Scan source files for FileContentProvider imports (which should only be
+    // used internally by the SDK, not by customer app code)
+    const sourceFiles = walkFiles(ctx.rootDir, (p) => /\.(ts|tsx|js|jsx)$/.test(p));
+    const violations = [];
+    for (const file of sourceFiles) {
+        const content = readTextFile(file);
+        if (content === null)
+            continue;
+        // Skip SDK source itself and test files
+        if (file.includes('node_modules'))
+            continue;
+        if (file.endsWith('.test.ts') || file.endsWith('.test.tsx'))
+            continue;
+        if (file.endsWith('.test.js') || file.endsWith('.test.jsx'))
+            continue;
+        if (content.includes('FileContentProvider')) {
+            violations.push(relative(ctx.rootDir, file));
+        }
+    }
+    if (violations.length === 0) {
+        results.push(ok('noFileContentProvider', 'no FileContentProvider imports in app code'));
+    }
+    else {
+        results.push(fail('noFileContentProvider', 'no FileContentProvider imports in app code', 'found in: ' + violations.join(', ')));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: noCustomContent — no custom content.ts that bypasses SDK
+// ---------------------------------------------------------------------------
+export function checkNoCustomContent(ctx) {
+    const results = [];
+    // Check for a content.ts file in the source root that manually constructs
+    // a content provider instead of relying on the SDK's built-in wiring.
+    const srcRoot = existsSync(join(ctx.rootDir, 'src'))
+        ? join(ctx.rootDir, 'src')
+        : ctx.rootDir;
+    const customContentFile = findFirstExisting(srcRoot, [
+        'content.ts',
+        'content.js',
+        'lib/content.ts',
+        'lib/content.js',
+        'utils/content.ts',
+        'utils/content.js',
+    ]);
+    if (!customContentFile) {
+        results.push(ok('noCustomContent', 'no custom content.ts bypassing SDK'));
+        return results;
+    }
+    // If the file exists, check if it manually constructs providers
+    const hasProviderConstruction = customContentFile.content.includes('FileContentProvider') ||
+        customContentFile.content.includes('S3ContentProvider') ||
+        customContentFile.content.includes('new ') && customContentFile.content.includes('Provider');
+    if (hasProviderConstruction) {
+        results.push(fail('noCustomContent', 'no custom content.ts bypassing SDK', 'found manual provider construction in ' + relative(ctx.rootDir, customContentFile.path)));
+    }
+    else {
+        results.push(ok('noCustomContent', 'no custom content.ts bypassing SDK'));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: noLegacyAssetRoute — no legacy asset route pattern
+// ---------------------------------------------------------------------------
+export function checkNoLegacyAssetRoute(ctx) {
+    const results = [];
+    if (ctx.framework !== 'next') {
+        return results;
+    }
+    const appRoot = existsSync(join(ctx.rootDir, 'src', 'app'))
+        ? join(ctx.rootDir, 'src', 'app')
+        : join(ctx.rootDir, 'app');
+    // The legacy pattern uses [releaseId] segment; the canonical pattern uses just [...path]
+    const legacyRoute = findFirstExisting(appRoot, [
+        'gradial/assets/[releaseId]/[...path]/route.ts',
+        'gradial/assets/[releaseId]/[...path]/route.tsx',
+        'gradial/assets/[releaseId]/[...path]/route.js',
+        'gradial/assets/[releaseId]/[...path]/route.jsx',
+    ]);
+    if (legacyRoute) {
+        results.push(fail('noLegacyAssetRoute', 'no legacy asset route with [releaseId] segment', 'found legacy route at ' + relative(ctx.rootDir, legacyRoute.path) + '; use gradial/assets/[...path]/route.ts instead'));
+    }
+    else {
+        results.push(ok('noLegacyAssetRoute', 'no legacy asset route with [releaseId] segment'));
+    }
+    // Verify the canonical asset route exists
+    const canonicalRoute = findFirstExisting(appRoot, [
+        'gradial/assets/[...path]/route.ts',
+        'gradial/assets/[...path]/route.tsx',
+        'gradial/assets/[...path]/route.js',
+        'gradial/assets/[...path]/route.jsx',
+    ]);
+    if (canonicalRoute) {
+        results.push(ok('noLegacyAssetRoute', 'canonical asset route exists', relative(ctx.rootDir, canonicalRoute.path)));
+        const usesSDKHandler = canonicalRoute.content.includes('@gradial/aci/next/asset-route');
+        results.push(usesSDKHandler
+            ? ok('noLegacyAssetRoute', 'asset route uses SDK handler', relative(ctx.rootDir, canonicalRoute.path))
+            : fail('noLegacyAssetRoute', 'asset route uses SDK handler', relative(ctx.rootDir, canonicalRoute.path) + ' should import from @gradial/aci/next/asset-route'));
+    }
+    else {
+        results.push(fail('noLegacyAssetRoute', 'canonical asset route exists', 'expected gradial/assets/[...path]/route.ts'));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: buildSucceeds — npm build exits cleanly
+// ---------------------------------------------------------------------------
+export function checkBuildSucceeds(ctx) {
+    const results = [];
+    try {
+        execSync('npm run build', {
+            cwd: ctx.rootDir,
+            stdio: 'pipe',
+            timeout: 300_000, // 5 min
+            env: { ...process.env, NODE_ENV: 'production' },
+        });
+        results.push(ok('buildSucceeds', 'npm run build succeeds'));
+    }
+    catch (err) {
+        const stderr = err instanceof Error && 'stderr' in err
+            ? String(err.stderr).slice(0, 500)
+            : 'unknown error';
+        results.push(fail('buildSucceeds', 'npm run build succeeds', stderr));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: contentCompile — aci compile-registry succeeds
+// ---------------------------------------------------------------------------
+export function checkContentCompile(ctx) {
+    const results = [];
+    // Look for the compile-registry script in the SDK
+    const compileScript = findFirstExisting(ctx.rootDir, [
+        'node_modules/@gradial/aci/src/cli/compile-registry.mjs',
+        'node_modules/@gradial/aci/dist/cli/compile-registry.mjs',
+    ]);
+    if (!compileScript) {
+        results.push(fail('contentCompile', 'content compile script found', '@gradial/aci compile-registry not found in node_modules'));
+        return results;
+    }
+    try {
+        execSync('npx aci compile', {
+            cwd: ctx.rootDir,
+            stdio: 'pipe',
+            timeout: 60_000,
+        });
+        results.push(ok('contentCompile', 'content compilation succeeds'));
+    }
+    catch (err) {
+        const stderr = err instanceof Error && 'stderr' in err
+            ? String(err.stderr).slice(0, 500)
+            : 'unknown error';
+        results.push(fail('contentCompile', 'content compilation succeeds', stderr));
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check: sdkVersion — SDK version is current
+// ---------------------------------------------------------------------------
+export function checkSdkVersion(ctx) {
+    const results = [];
+    // Read the installed SDK version
+    const installedPkg = readJSON(join(ctx.rootDir, 'node_modules', '@gradial', 'aci', 'package.json'));
+    if (!installedPkg || !installedPkg.version) {
+        results.push(fail('sdkVersion', '@gradial/aci is installed', 'package not found in node_modules'));
+        return results;
+    }
+    results.push(ok('sdkVersion', '@gradial/aci is installed', `v${installedPkg.version}`));
+    // Read the declared version in site's package.json
+    const sitePkg = readJSON(join(ctx.rootDir, 'package.json'));
+    if (sitePkg) {
+        const declaredVersion = sitePkg.dependencies?.['@gradial/aci'] ??
+            sitePkg.devDependencies?.['@gradial/aci'];
+        if (declaredVersion) {
+            results.push(ok('sdkVersion', '@gradial/aci declared in package.json', declaredVersion));
+        }
+        else {
+            results.push(fail('sdkVersion', '@gradial/aci declared in package.json', 'missing from dependencies and devDependencies'));
+        }
+    }
+    return results;
+}
+// ---------------------------------------------------------------------------
+// Check registry: maps check names to functions
+// ---------------------------------------------------------------------------
+export const CHECK_REGISTRY = {
+    config: checkConfig,
+    registry: checkRegistry,
+    pageEntry: checkPageEntry,
+    middleware: checkMiddleware,
+    noFileContentProvider: checkNoFileContentProvider,
+    noCustomContent: checkNoCustomContent,
+    noLegacyAssetRoute: checkNoLegacyAssetRoute,
+    buildSucceeds: checkBuildSucceeds,
+    contentCompile: checkContentCompile,
+    sdkVersion: checkSdkVersion,
+};

package/dist/testing/conformance/index.d.ts

@@ -0,0 +1,3 @@
+export { conformancePreset, runConformanceChecks } from './preset.js';
+export { checkConfig, checkRegistry, checkPageEntry, checkMiddleware, checkNoFileContentProvider, checkNoCustomContent, checkNoLegacyAssetRoute, checkBuildSucceeds, checkContentCompile, checkSdkVersion, CHECK_REGISTRY, } from './checks.js';
+export type { ConformanceFramework, ConformanceCheckName, ConformancePresetOptions, ConformanceCheckResult, ConformanceResult, ConformanceContext, ConformanceCheckFn, } from './types.js';

package/dist/testing/conformance/index.js

@@ -0,0 +1,2 @@
+export { conformancePreset, runConformanceChecks } from './preset.js';
+export { checkConfig, checkRegistry, checkPageEntry, checkMiddleware, checkNoFileContentProvider, checkNoCustomContent, checkNoLegacyAssetRoute, checkBuildSucceeds, checkContentCompile, checkSdkVersion, CHECK_REGISTRY, } from './checks.js';

package/dist/testing/conformance/preset.d.ts

@@ -0,0 +1,14 @@
+import type { ConformancePresetOptions, ConformanceResult } from './types.js';
+/**
+ * Run all resolved checks and return an aggregate result.
+ * This is the programmatic API — call it directly if you don't want the
+ * node:test integration.
+ */
+export declare function runConformanceChecks(options: ConformancePresetOptions): ConformanceResult;
+/**
+ * Register a conformance test suite using node:test.
+ *
+ * Each check runs as a subtest within a "ACI conformance" suite.
+ * Failures are reported as test assertion failures.
+ */
+export declare function conformancePreset(options: ConformancePresetOptions): void;

package/dist/testing/conformance/preset.js

@@ -0,0 +1,98 @@
+/**
+ * Conformance preset for @gradial/aci sites.
+ *
+ * Usage in a customer repo's test suite:
+ *
+ * ```ts
+ * import test from 'node:test';
+ * import { conformancePreset } from '@gradial/aci/testing';
+ *
+ * conformancePreset({
+ *   framework: 'next',
+ *   siteId: 'site_mysite',
+ * });
+ * ```
+ *
+ * This registers a test suite using node:test that verifies the site's ACI
+ * integration conforms to the canonical patterns.
+ */
+import test from 'node:test';
+import assert from 'node:assert/strict';
+import { CHECK_REGISTRY } from './checks.js';
+/** All check names in default execution order. */
+const ALL_CHECKS = [
+    'config',
+    'registry',
+    'pageEntry',
+    'middleware',
+    'noFileContentProvider',
+    'noCustomContent',
+    'noLegacyAssetRoute',
+    'sdkVersion',
+    // Expensive checks last — these shell out
+    'contentCompile',
+    'buildSucceeds',
+];
+/** Default checks exclude the expensive build/compile checks. */
+const DEFAULT_CHECKS = ALL_CHECKS.filter((c) => c !== 'buildSucceeds' && c !== 'contentCompile');
+function resolveChecks(input) {
+    if (!input)
+        return DEFAULT_CHECKS;
+    if (Array.isArray(input)) {
+        return input.filter((c) => c in CHECK_REGISTRY);
+    }
+    // Object form: start with defaults, apply overrides
+    return ALL_CHECKS.filter((name) => {
+        if (name in input)
+            return input[name];
+        return DEFAULT_CHECKS.includes(name);
+    });
+}
+/**
+ * Run all resolved checks and return an aggregate result.
+ * This is the programmatic API — call it directly if you don't want the
+ * node:test integration.
+ */
+export function runConformanceChecks(options) {
+    const ctx = {
+        framework: options.framework,
+        siteId: options.siteId,
+        rootDir: options.rootDir || process.cwd(),
+    };
+    const checks = resolveChecks(options.checks);
+    const allResults = checks.flatMap((name) => {
+        const checkFn = CHECK_REGISTRY[name];
+        return checkFn(ctx);
+    });
+    const failures = allResults.filter((r) => !r.ok);
+    return {
+        passed: failures.length === 0,
+        checks: allResults,
+        failures,
+    };
+}
+/**
+ * Register a conformance test suite using node:test.
+ *
+ * Each check runs as a subtest within a "ACI conformance" suite.
+ * Failures are reported as test assertion failures.
+ */
+export function conformancePreset(options) {
+    const checks = resolveChecks(options.checks);
+    test('ACI conformance', async (t) => {
+        const ctx = {
+            framework: options.framework,
+            siteId: options.siteId,
+            rootDir: options.rootDir || process.cwd(),
+        };
+        for (const checkName of checks) {
+            await t.test(checkName, () => {
+                const checkFn = CHECK_REGISTRY[checkName];
+                const results = checkFn(ctx);
+                for (const result of results) {
+                    assert.ok(result.ok, `${result.label}${result.detail ? ` (${result.detail})` : ''}`);
+                }
+            });
+        }
+    });
+}

package/dist/testing/conformance/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Conformance preset types for @gradial/aci/testing.
+ *
+ * These types define the contract for conformance checks that customer repos
+ * run in their own CI to verify their ACI integration stays canonical.
+ */
+/** Supported framework identifiers. */
+export type ConformanceFramework = 'next' | 'astro';
+/** Individual check names that can be enabled/disabled. */
+export type ConformanceCheckName = 'config' | 'registry' | 'pageEntry' | 'middleware' | 'noFileContentProvider' | 'noCustomContent' | 'noLegacyAssetRoute' | 'buildSucceeds' | 'contentCompile' | 'sdkVersion';
+/** Options for the conformance preset. */
+export interface ConformancePresetOptions {
+    /** Framework the site uses. */
+    framework: ConformanceFramework;
+    /** Expected siteId value (verified in config and middleware). */
+    siteId: string;
+    /** Root directory of the site project. Defaults to process.cwd(). */
+    rootDir?: string;
+    /**
+     * Which checks to run. Defaults to all checks.
+     * Pass an array to run only those checks, or an object to enable/disable individually.
+     */
+    checks?: ConformanceCheckName[] | Partial<Record<ConformanceCheckName, boolean>>;
+}
+/** Result of a single conformance check. */
+export interface ConformanceCheckResult {
+    name: ConformanceCheckName;
+    label: string;
+    ok: boolean;
+    detail?: string;
+}
+/** Aggregated result of all conformance checks. */
+export interface ConformanceResult {
+    passed: boolean;
+    checks: ConformanceCheckResult[];
+    failures: ConformanceCheckResult[];
+}
+/** A conformance check function. */
+export type ConformanceCheckFn = (ctx: ConformanceContext) => ConformanceCheckResult[];
+/** Context passed to each check function. */
+export interface ConformanceContext {
+    framework: ConformanceFramework;
+    siteId: string;
+    rootDir: string;
+}

package/dist/testing/conformance/types.js

@@ -0,0 +1,7 @@
+/**
+ * Conformance preset types for @gradial/aci/testing.
+ *
+ * These types define the contract for conformance checks that customer repos
+ * run in their own CI to verify their ACI integration stays canonical.
+ */
+export {};