@gradial/aci 0.1.53-rc.2 → 0.1.53-rc.4

package/dist/testing/conformance/root-identity.js

@@ -1,361 +1,53 @@
 /**
- * Conformance check: rootIdentity (ADR 0051).
+ * Conformance check: rootIdentity (sdk I-31, ADR 0063).
  *
- * The ACI renderer passes every block `data-aci-block` and
- * `data-aci-component` as props; a component must spread them onto the
- * element it returns. The registry type constraint proves a component
- * declares the props. This check proves it renders them, by rendering every
- * registered component through the SDK's own seam and reading the root of
- * the markup.
- *
- * Next: components are rendered with react-dom/server from the site's own
- * node_modules; next/link and next/image are stubbed (see next-stubs.ts)
- * because their CommonJS interop objects cannot render outside Next.
- * Astro: components cannot be rendered outside Astro, so the built site's
- * HTML is scanned for every authored block id instead (building first when
- * `dist/` is absent).
+ * The renderer passes every block `data-aci-block` and `data-aci-component`
+ * as props; a component must place them on the element it returns. The
+ * registry type constraint proves a component declares the props. This
+ * check proves it renders them: it renders every registered component in
+ * isolation through the framework adapter (Next: react-dom/server; Astro:
+ * the Container API over a Vite server rooted at the site) and hands each
+ * render to the same rootIdentity test publish runs. No site build.
  */
-import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { createRequire } from 'node:module';
-import { join, relative, resolve } from 'node:path';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-import { execSync } from 'node:child_process';
+import { LoaderMissingError } from '../../platform-tests/adapters/site.js';
+import { checkSiteRootIdentity, formatRootIdentityCoverage, formatRootIdentityFailures, } from '../../platform-tests/site-check.js';
+import { existsSync, statSync } from 'node:fs';
+import { resolve } from 'node:path';
 const CHECK = 'rootIdentity';
 const LABEL = 'components render data-aci-block on their root element';
-// ---------------------------------------------------------------------------
-// Pure core (unit-tested with in-memory registries)
-// ---------------------------------------------------------------------------
-/**
- * Render each block through the SDK renderer and report every component
- * whose root element lacks the identity attributes. `blocks` are the blocks
- * to exercise; registry entries not covered by a block are probed with empty
- * props so an unused component cannot hide a forgotten spread.
- */
-export async function findRootIdentityFailures(registry, blocks, react, fileFor = () => undefined) {
-    const { renderBlock } = await import('../../next/render.js');
-    const failures = new Map();
-    const covered = new Set();
-    const probe = async (block, contentBacked) => {
-        if (failures.has(block.component))
-            return;
-        const element = await renderBlock(block, registry, `probe:${block.id}`);
-        let html;
-        try {
-            html = await markupFor(element, react);
-        }
-        catch (err) {
-            // A component the content never uses is probed with empty props; if it
-            // needs real props to render, that proves nothing about identity, so
-            // it is skipped rather than reported. Content-backed renders that
-            // throw are real failures.
-            if (!contentBacked)
-                return;
-            failures.set(block.component, {
-                component: block.component,
-                file: fileFor(block.component),
-                missing: [`render threw: ${err instanceof Error ? err.message : String(err)}`],
-            });
-            return;
-        }
-        const root = rootAttributes(html);
-        const missing = [];
-        if (root.block !== block.id)
-            missing.push('data-aci-block');
-        if (root.component !== block.component)
-            missing.push('data-aci-component');
-        if (missing.length > 0) {
-            failures.set(block.component, { component: block.component, file: fileFor(block.component), missing });
-        }
-    };
-    for (const block of blocks) {
-        if (!registry.some((entry) => entry.id === block.component))
-            continue;
-        covered.add(block.component);
-        await probe(block, true);
-    }
-    for (const entry of registry) {
-        if (covered.has(entry.id))
-            continue;
-        await probe({ $type: 'component', id: `probe-${entry.id}`, component: entry.id, props: {} }, false);
-    }
-    return [...failures.values()];
-}
-/** The failure message: one line of what, the list, one line of fix. */
-export function formatRootIdentityFailures(failures, framework) {
-    const width = Math.max(...failures.map((f) => f.component.length), 0);
-    const lines = failures.map((f) => {
-        const note = f.missing.length === 1 && f.missing[0].startsWith('data-aci-') && f.missing[0] !== 'data-aci-block'
-            ? `(missing ${f.missing[0]})`
-            : f.missing[0]?.startsWith('render threw') ? `(${f.missing[0]})` : '';
-        return ['  ' + f.component.padEnd(width), f.file, note].filter(Boolean).join('  ');
-    });
-    const fix = framework === 'next'
-        ? [
-            'Fix: extend RootIdentityProps and spread the rest props onto the root:',
-            '  function StatsBar({ stats, ...root }: StatsBarProps) { return <section {...root} …',
-        ]
-        : [
-            'Fix: extend RootIdentityProps and spread the rest props onto the root:',
-            '  const { stats, ...root } = Astro.props;   <section {...root} …',
-        ];
-    return [
-        `${CHECK}: ${failures.length} component${failures.length === 1 ? '' : 's'} do${failures.length === 1 ? 'es' : ''} not render data-aci-block on their root element`,
-        '',
-        ...lines,
-        '',
-        ...fix,
-    ].join('\n');
-}
-/**
- * Slot components are async server components in Next; react-dom/server
- * cannot render those, so the element the SDK produced is unwrapped by
- * awaiting the component function directly.
- */
-async function markupFor(element, react) {
-    const el = element;
-    const type = el.type;
-    if (typeof type === 'function' && type.constructor?.name === 'AsyncFunction') {
-        const resolved = await type(el.props);
-        return react.renderToStaticMarkup(resolved);
-    }
-    return react.renderToStaticMarkup(element);
-}
-function rootAttributes(html) {
-    // react-dom hoists resource hints (<link rel="preload">, <meta>) ahead of
-    // the component's markup; they are not the root element.
-    const body = html.trim().replace(/^(?:<(?:link|meta)\b[^>]*\/?>\s*)+/i, '');
-    const root = /^<([a-z][a-z0-9-]*)([^>]*)>/i.exec(body);
-    if (!root)
-        return {};
-    const attrs = root[2];
-    return {
-        block: /\sdata-aci-block="([^"]*)"/.exec(attrs)?.[1],
-        component: /\sdata-aci-component="([^"]*)"/.exec(attrs)?.[1],
-    };
-}
-// ---------------------------------------------------------------------------
-// Site integration
-// ---------------------------------------------------------------------------
 export async function checkRootIdentity(ctx) {
-    return ctx.framework === 'next' ? checkNextRootIdentity(ctx) : checkAstroRootIdentity(ctx);
-}
-async function checkNextRootIdentity(ctx) {
-    if (!ctx.registry?.trim()) {
-        return [fail(`${CHECK}: set the conformance registry option to the render registry module used by the app`)];
-    }
-    const registryFile = resolve(ctx.rootDir, ctx.registry);
-    if (!existsSync(registryFile) || !statSync(registryFile).isFile()) {
+    // A registry the site names explicitly must exist: a wrong option is a
+    // configuration error, not a limit of the isolated check.
+    const explicit = ctx.registry?.trim() ? resolve(ctx.rootDir, ctx.registry) : undefined;
+    if (explicit && !(existsSync(explicit) && statSync(explicit).isFile())) {
         return [fail(`${CHECK}: registry module does not exist: ${ctx.registry}`)];
     }
-    const siteRequire = createRequire(join(ctx.rootDir, 'package.json'));
-    let react;
-    try {
-        react = siteRequire('react-dom/server');
-        // The site's tsconfig may keep `jsx: preserve` for Next, in which case
-        // the test transform emits classic React.createElement calls.
-        globalThis.React = siteRequire('react');
-    }
-    catch (err) {
-        return [fail(`${CHECK}: cannot load react-dom/server from the site (${err instanceof Error ? err.message : String(err)})`)];
-    }
-    const { register } = await import('node:module');
-    register(stubHookURL());
-    let mod;
+    let result;
     try {
-        mod = (await import(pathToFileURL(registryFile).href));
+        result = await checkSiteRootIdentity(ctx.framework, ctx.rootDir, {
+            registryFiles: explicit ? [explicit] : [],
+        });
     }
     catch (err) {
-        return [fail(`${CHECK}: cannot load ${relative(ctx.rootDir, registryFile)} (${err instanceof Error ? err.message : String(err)})`)];
-    }
-    const registry = Object.values(mod).find(isRegistry);
-    if (!registry) {
-        return [fail(`${CHECK}: ${relative(ctx.rootDir, registryFile)} does not export the createRegistry result`)];
-    }
-    const source = readFileSync(registryFile, 'utf8');
-    const failures = await findRootIdentityFailures(registry, compiledBlocks(ctx.rootDir), react, componentFileResolver(source, registry));
-    if (failures.length === 0) {
-        return [ok(`${registry.length} registered components`)];
-    }
-    return [fail(formatRootIdentityFailures(failures, 'next'))];
-}
-async function checkAstroRootIdentity(ctx) {
-    const distDir = join(ctx.rootDir, 'dist');
-    if (!existsSync(distDir) || distIsStale(distDir, [join(ctx.rootDir, 'src'), join(ctx.rootDir, '.content')])) {
-        try {
-            execSync('npm run build', { cwd: ctx.rootDir, stdio: 'pipe', timeout: 300_000, env: { ...process.env, NODE_ENV: 'production' } });
-        }
-        catch (err) {
-            const stderr = err instanceof Error && 'stderr' in err ? String(err.stderr).slice(0, 500) : String(err);
-            return [fail(`${CHECK}: npm run build failed, cannot scan dist/ (${stderr})`)];
-        }
-    }
-    const authored = astroAuthoredBlocks(join(ctx.rootDir, '.content'));
-    if (authored.length === 0) {
-        return [fail(`${CHECK}: no authored blocks found under .content/pages`)];
-    }
-    const html = walkHTML(distDir).map((file) => readFileSync(file, 'utf8')).join('\n');
-    const missing = authored.filter(({ id, component }) => {
-        const pattern = new RegExp(`<[a-z][^>]*(?:data-aci-block="${escapeRegExp(id)}"[^>]*data-aci-component="${escapeRegExp(component)}"` +
-            `|data-aci-component="${escapeRegExp(component)}"[^>]*data-aci-block="${escapeRegExp(id)}")`);
-        return !pattern.test(html);
-    });
-    if (missing.length === 0) {
-        return [ok(`${authored.length} authored blocks found on component roots in dist/`)];
-    }
-    const byComponent = new Map();
-    for (const m of missing) {
-        if (!byComponent.has(m.component))
-            byComponent.set(m.component, { component: m.component, missing: ['data-aci-block'] });
-    }
-    return [fail(formatRootIdentityFailures([...byComponent.values()], 'astro'))];
-}
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-/** The stub hook next to this module: compiled `.js` in dist, `.ts` when run from source. */
-function stubHookURL() {
-    const js = new URL('./next-stubs.js', import.meta.url);
-    if (existsSync(fileURLToPath(js)))
-        return js;
-    return new URL('./next-stubs.ts', import.meta.url);
-}
-function ok(detail) {
-    return { name: CHECK, label: LABEL, ok: true, detail };
+        // No TypeScript/JSX loader in this test process: nothing was checked and
+        // the fix is one line, so this fails rather than passing quietly.
+        if (err instanceof LoaderMissingError)
+            return [fail(`${CHECK}: ${err.message}`)];
+        // Any other failure to open the site is a limit of the isolated check,
+        // not a finding about the site; publish checks it in the real renderer.
+        const reason = (err instanceof Error ? err.message : String(err)).split('\n')[0];
+        return [{ name: CHECK, label: LABEL, ok: true, detail: `${CHECK}: not run (${reason}); publish checks every placed block` }];
+    }
+    const coverage = formatRootIdentityCoverage(result);
+    if (result.notRun.length > 0)
+        console.warn(`[aci] ${coverage}`);
+    if (result.failures.length === 0) {
+        return [{ name: CHECK, label: LABEL, ok: true, detail: coverage }];
+    }
+    return [fail(`${formatRootIdentityFailures(result.failures)}\n\n${coverage}`)];
 }
 // A failure's label is the message itself so the test runner prints it
 // without a generic prefix; the check name is the first word of the message.
 function fail(message) {
     return { name: CHECK, label: message, ok: false };
 }
-function isRegistry(value) {
-    return Array.isArray(value) && value.length > 0
-        && value.every((e) => e && typeof e === 'object' && typeof e.id === 'string' && 'component' in e && 'contract' in e);
-}
-/** Map a registered component id to the import path the registry file names for it. */
-function componentFileResolver(registrySource, registry) {
-    const imports = new Map();
-    for (const m of registrySource.matchAll(/import\s+(?:\{([^}]*)\}|(\w+))\s+from\s+['"]([^'"]+)['"]/g)) {
-        const names = (m[1] ?? m[2]).split(',').map((n) => n.trim().split(/\s+as\s+/).pop()).filter(Boolean);
-        for (const name of names)
-            imports.set(name, m[3]);
-    }
-    const byId = new Map();
-    for (const entry of registry) {
-        const fn = entry.component;
-        const file = typeof fn === 'function' && fn.name ? imports.get(fn.name) : undefined;
-        if (file)
-            byId.set(entry.id, file);
-    }
-    return (component) => byId.get(component);
-}
-/** Blocks from the site's compiled content, when `npm run content:compile` has run. */
-function compiledBlocks(rootDir) {
-    const compiled = join(rootDir, '.aci', 'compiled');
-    if (!existsSync(compiled))
-        return [];
-    const blocks = [];
-    const routes = join(compiled, 'routes');
-    if (existsSync(routes)) {
-        for (const file of walkJSON(routes)) {
-            const doc = JSON.parse(readFileSync(file, 'utf8'));
-            for (const region of Object.values(doc.regions ?? {}))
-                blocks.push(...region);
-        }
-    }
-    const fragments = join(compiled, 'fragments');
-    if (existsSync(fragments)) {
-        for (const file of walkJSON(fragments)) {
-            const doc = JSON.parse(readFileSync(file, 'utf8'));
-            if (doc.block) {
-                const id = file.slice(fragments.length + 1).replace(/\.json$/, '');
-                blocks.push({ $type: 'component', id, component: doc.block.component, props: doc.block.props });
-            }
-        }
-    }
-    return blocks;
-}
-/**
- * Every block the Astro scan must find in dist/: page blocks by their own id,
- * plus fragments (navbar, footer) by fragment id, which is the block id the
- * renderer synthesizes when a layout slot default places them.
- */
-export function astroAuthoredBlocks(contentDir) {
-    const out = authoredBlocks(join(contentDir, 'pages'));
-    const fragmentsDir = join(contentDir, 'fragments');
-    if (existsSync(fragmentsDir)) {
-        for (const entry of readdirSync(fragmentsDir, { withFileTypes: true })) {
-            if (!entry.isDirectory())
-                continue;
-            const file = join(fragmentsDir, entry.name, '_index.json');
-            if (!existsSync(file))
-                continue;
-            const doc = JSON.parse(readFileSync(file, 'utf8'));
-            const component = doc.block?.component;
-            if (typeof component === 'string' && component !== '') {
-                out.push({ id: doc.fragmentId ?? entry.name, component });
-            }
-        }
-    }
-    return out;
-}
-/** dist/ is stale when any source or content file is newer than its newest output. */
-function distIsStale(distDir, inputs) {
-    const newest = (dir) => {
-        if (!existsSync(dir))
-            return 0;
-        let max = 0;
-        for (const entry of readdirSync(dir, { withFileTypes: true })) {
-            const full = join(dir, entry.name);
-            max = Math.max(max, entry.isDirectory() ? newest(full) : statSync(full).mtimeMs);
-        }
-        return max;
-    };
-    const built = newest(distDir);
-    return inputs.some((dir) => newest(dir) > built);
-}
-function authoredBlocks(pagesDir) {
-    if (!existsSync(pagesDir))
-        return [];
-    const out = [];
-    const collect = (value) => {
-        if (Array.isArray(value)) {
-            value.forEach(collect);
-            return;
-        }
-        if (!value || typeof value !== 'object')
-            return;
-        const node = value;
-        if (typeof node.component === 'string' && node.props && typeof node.props === 'object' && typeof node.id === 'string' && node.id !== '') {
-            out.push({ id: node.id, component: node.component });
-        }
-        Object.values(node).forEach(collect);
-    };
-    for (const file of walkJSON(pagesDir)) {
-        if (!file.endsWith('_index.json'))
-            continue;
-        const doc = JSON.parse(readFileSync(file, 'utf8'));
-        if (doc.$type === 'page')
-            collect(doc.regions);
-    }
-    return out;
-}
-function walkJSON(dir) {
-    return walkExt(dir, '.json');
-}
-function walkHTML(dir) {
-    return walkExt(dir, '.html');
-}
-function walkExt(dir, ext) {
-    const out = [];
-    for (const entry of readdirSync(dir, { withFileTypes: true })) {
-        const full = join(dir, entry.name);
-        if (entry.isDirectory())
-            out.push(...walkExt(full, ext));
-        else if (entry.name.endsWith(ext))
-            out.push(full);
-    }
-    return out;
-}
-function escapeRegExp(value) {
-    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}

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

@@ -29,7 +29,7 @@ export interface ConformancePresetOptions {
      * check verifies .aci.yaml does NOT declare a siteId.
      */
     siteId?: string;
-    /** Render registry module, relative to rootDir (or absolute). Required for Next rootIdentity. */
+    /** A registry module to check in addition to every file that calls createRegistry(, relative to rootDir (or absolute). Optional. */
     registry?: string;
     /** Root directory of the site project. Defaults to process.cwd(). */
     rootDir?: string;

package/dist/types/component.d.ts

@@ -20,13 +20,21 @@ export interface ComponentValidationIssue {
 }
 /**
  * Root identity props the SDK renderers inject into every page and fragment
- * block (sdk I-19, ADR 0051). A component spreads them onto its own root
- * element; the starter conformance test fails a component that drops them.
+ * block (sdk I-31, ADR 0051). A component places them on its own root
+ * element with `{...aciRootAttrs(props)}` or a rest-spread; the conformance
+ * check fails a component that drops them (ADR 0063).
  */
-export interface RootIdentityProps {
+export interface AciRootProps {
     'data-aci-block'?: string;
     'data-aci-component'?: string;
 }
+/** The former name of {@link AciRootProps} (sdk D-9). */
+export type RootIdentityProps = AciRootProps;
+/**
+ * Exactly the {@link AciRootProps} keys of `props`, for the root element:
+ * `<section {...aciRootAttrs(props)}>`. Nothing else in `props` leaks.
+ */
+export declare function aciRootAttrs(props: AciRootProps): AciRootProps;
 export interface ComponentDefinition<TId extends string = string, TSchema = unknown> {
     id: TId;
     displayName?: string;

package/dist/types/component.js

@@ -1 +1,10 @@
-export {};
+/**
+ * Exactly the {@link AciRootProps} keys of `props`, for the root element:
+ * `<section {...aciRootAttrs(props)}>`. Nothing else in `props` leaks.
+ */
+export function aciRootAttrs(props) {
+    return {
+        'data-aci-block': props['data-aci-block'],
+        'data-aci-component': props['data-aci-component'],
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@gradial/aci",
-  "version": "0.1.53-rc.2",
+  "version": "0.1.53-rc.4",
   "repository": {
     "type": "git",
     "url": "https://github.com/gradial/bare-metal-go.git",
@@ -160,14 +160,15 @@
     "next": "^15.5.19",
     "tsx": "^4.20.0",
     "typescript": "^5.9.3",
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "astro": "^6.4.8"
   },
   "optionalDependencies": {
-    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.2",
-    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.2",
-    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.2",
-    "@gradial/aci-cli-linux-x64": "0.1.53-rc.2",
-    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.2",
-    "@gradial/aci-cli-win32-x64": "0.1.53-rc.2"
+    "@gradial/aci-cli-darwin-arm64": "0.1.53-rc.4",
+    "@gradial/aci-cli-darwin-x64": "0.1.53-rc.4",
+    "@gradial/aci-cli-linux-arm64": "0.1.53-rc.4",
+    "@gradial/aci-cli-linux-x64": "0.1.53-rc.4",
+    "@gradial/aci-cli-win32-arm64": "0.1.53-rc.4",
+    "@gradial/aci-cli-win32-x64": "0.1.53-rc.4"
   }
 }