Post & fixture
+
+
+ Content & fixture
+LateCoreMapProbe
' ); + file_put_contents( $directory . '/recursive.twig', 'DynamicInnerBlockProbe
'; + }, + ) + ); + $registered[] = $block_names[0]; + register_block_type( + $block_names[1], + array( + 'uses_context' => array( 'postId' ), + 'render_callback' => static fn(): string => 'RecursiveBlockProbe
', + ) + ); + $registered[] = $block_names[1]; + $add_filter( + 'render_block_core/paragraph', + static fn( string $html ): string => $html . '' + ); + $add_filter( + 'pre_render_block', + static function ( $html, array $block ) { + return ! empty( $block['attrs']['fixtureShortCircuit'] ) ? 'ShortCircuitInnerProbe
' : $html; + }, + 10, + 2 + ); + $examples = array( + 'group' => 'GroupInnerProbe
DiscardedInnerProbe
', + 'nested' => 'QuoteInnerProbe
NestedInnerProbe
ContentOnlyProbe
'; + $heading_baseline = do_blocks( $heading ); + $unmapped = 'UnmappedBytesProbe & text
'; + $unmapped_baseline = do_blocks( $unmapped ); + $map = array( + 'core/group' => $relative . '/inner.twig', + 'core/quote' => $relative . '/inner.twig', + 'core/post-title' => $relative . '/post.twig', + 'core/heading' => $relative . '/content.twig', + ); + $map_filter = static fn( array $values ): array => array_merge( $values, $map ); + $add_filter( 'emulsify_theme_core_block_twig_template_map', $map_filter ); + $add_filter( 'emulsify_theme_core_block_twig_rendering_enabled', static fn(): bool => true ); + $renderer = new CoreBlockTwigRenderer(); + $renderer->register(); + $renderers[] = $renderer; + foreach ( $examples as $name => $source ) { + $dynamic_renders = 0; + $actual = do_blocks( $source ); + emulsify_block_context_assert( $actual === $baseline[ $name ], 'Mapped ' . $name . ' must retain full rendered inner content byte-for-byte, including final child filters.' ); + if ( 'group' === $name ) { + emulsify_block_context_assert( 1 === $dynamic_renders && 1 === substr_count( $actual, 'DynamicInnerBlockProbe' ) && 1 === substr_count( $actual, 'ShortCircuitInnerProbe' ), 'Inner dynamic and short-circuited blocks must appear once and never render twice.' ); + } + } + emulsify_block_context_assert( do_blocks( $heading ) === $heading_baseline, 'Templates printing content must preserve their rendered output byte-for-byte.' ); + emulsify_block_context_assert( do_blocks( $unmapped ) === $unmapped_baseline, 'Unmapped blocks must preserve every output byte.' ); + $late_map = static function ( array $values ) use ( $relative ): array { + $values['core/heading'] = $relative . '/late.twig'; + return $values; + }; + $add_filter( 'emulsify_theme_core_block_twig_template_map', $late_map, 11 ); + emulsify_block_context_assert( 'LateCoreMapProbe
' === do_blocks( $heading ), 'A template-map filter registered after initial rendering must take effect.' ); + emulsify_block_context_assert( 0 === $the_post_calls, 'The first mapped block context must not call setup() on a singular request.' ); + for ( $index = 0; $index < 20; ++$index ) { + $post_id = $created_posts[ $index % 2 ]; + $instance = new WP_Block( parse_blocks( '' )[0], array( 'postId' => $post_id ) ); + $global_before = $GLOBALS['post']; + $output = $instance->render(); + emulsify_block_context_assert( '' === $output, 'Mapped blocks must use their own postId context across repeated Query Loop post contexts.' ); + emulsify_block_context_assert( $global_before === $GLOBALS['post'], 'Mapped block context must not replace the global post.' ); + } + emulsify_block_context_assert( 0 === $the_post_calls, 'Many mapped blocks must not call setup() or fire the_post again.' ); + emulsify_block_context_assert( 1 === $context_builds, 'Many mapped blocks must reuse a single global Timber context build.' ); + + $add_filter( + 'query_loop_block_query_vars', + static fn( array $values ): array => array_merge( $values, array( 'post__in' => $created_posts, 'orderby' => 'post__in', 'posts_per_page' => 2 ) ) + ); + $query_blocks = ''; + remove_filter( 'render_block', array( $renderer, 'render_block' ), 20 ); + $the_post_calls = 0; + do_blocks( $query_blocks ); + $baseline_post_calls = $the_post_calls; + add_filter( 'render_block', array( $renderer, 'render_block' ), 20, 3 ); + $the_post_calls = 0; + $query_output = do_blocks( $query_blocks ); + foreach ( $created_posts as $post_id ) { + emulsify_block_context_assert( 1 === substr_count( $query_output, 'data-context-post="' . $post_id . '"' ), 'Real Query Loop iterations must render each block post exactly once without context leakage.' ); + } + emulsify_block_context_assert( $the_post_calls === $baseline_post_calls, 'Mapped Query Loop rendering must not add the_post callbacks beyond WordPress itself.' ); + + remove_filter( 'render_block', array( $renderer, 'render_block' ), 20 ); + $add_filter( + 'emulsify_theme_core_block_twig_template_map', + static function ( array $values ) use ( $relative ): array { + $values['emulsify-fixture/recursive'] = $relative . '/recursive.twig'; + return $values; + }, + 12 + ); + $recursion_id = wp_insert_post( array( 'post_type' => 'post', 'post_status' => 'publish', 'post_title' => 'Recursive block fixture', 'post_content' => '' ), true ); + emulsify_block_context_assert( ! is_wp_error( $recursion_id ), 'Could not create recursive block fixture.' ); + $created_posts[] = $recursion_id; + $query = new WP_Query( array( 'p' => $recursion_id ) ); + $query->get_queried_object(); + $GLOBALS['wp_query'] = $query; + $GLOBALS['wp_the_query'] = $query; + $GLOBALS['post'] = get_post( $recursion_id ); + $recursion_calls = 0; + $add_filter( + 'emulsify_theme_core_block_twig_context', + static function ( array $context ) use ( &$recursion_calls ): array { + // Bound a regression before it can exhaust memory in the fixture. + if ( ++$recursion_calls > 8 ) throw new RuntimeException( 'Mapped content recursion did not stop.' ); + return $context; + } + ); + $recursive_renderer = new CoreBlockTwigRenderer(); + $recursive_renderer->register(); + $renderers[] = $recursive_renderer; + $output = do_blocks( get_post_field( 'post_content', $recursion_id ) ); + emulsify_block_context_assert( 1 === substr_count( $output, 'RecursiveBlockProbe' ) && $recursion_calls <= 2, 'Mapped post.content recursion must stop with WordPress markup and retain its content once.' ); + echo "Mapped block WordPress context smoke passed.\n"; +} finally { + foreach ( $renderers as $renderer ) remove_filter( 'render_block', array( $renderer, 'render_block' ), 20 ); + foreach ( array_reverse( $filters ) as $filter ) remove_filter( $filter[0], $filter[1], $filter[2] ); + foreach ( $created_posts as $id ) wp_delete_post( $id, true ); + foreach ( $registered as $name ) unregister_block_type( $name ); + if ( is_dir( $directory ) ) { + foreach ( glob( $directory . '/*.twig' ) as $file ) unlink( $file ); + rmdir( $directory ); + } + Timber::$context_cache = $saved_context; + foreach ( $saved_globals as $name => $saved ) { + if ( $saved[0] ) $GLOBALS[ $name ] = $saved[1]; + else unset( $GLOBALS[ $name ] ); + } +} diff --git a/.github/scripts/core-block-twig-renderer-smoke.php b/.github/scripts/core-block-twig-renderer-smoke.php index 94cc2b5..8dbd354 100644 --- a/.github/scripts/core-block-twig-renderer-smoke.php +++ b/.github/scripts/core-block-twig-renderer-smoke.php @@ -23,6 +23,11 @@ final class Timber { * @var array */ public static $compiled = array(); + public static $context_calls = 0; + public static $global_context_calls = 0; + public static $post_queries = array(); + public static $recursive_calls = 0; + public static $recursive_renderer; /** * Gets Timber context. @@ -30,9 +35,25 @@ final class Timber { * @return array Context. */ public static function context(): array { + ++self::$context_calls; + if ( ! empty( $GLOBALS['emulsify_core_block_reset_post'] ) ) { + $GLOBALS['post'] = $GLOBALS['emulsify_core_block_queried_post']; + } + return self::$context; + } + + public static function context_global(): array { + ++self::$global_context_calls; return self::$context; } + public static function get_post( $query = false ) { + self::$post_queries[] = $query; + $query = false === $query ? ( $GLOBALS['emulsify_core_block_queried_post'] ?? null ) : $query; + $id = is_object( $query ) ? $query->ID : $query; + return $id ? (object) array( 'ID' => (int) $id ) : null; + } + /** * Compiles a template. * @@ -42,6 +63,19 @@ public static function context(): array { */ public static function compile( string $template, array $context ): string { self::$compiled[] = compact( 'template', 'context' ); + if ( false !== strpos( $template, 'recursive.twig' ) ) { + if ( ++self::$recursive_calls > 4 ) { + throw new \RuntimeException( 'Unbounded mapped post.content recursion.' ); + } + return '%s:%s:%s
', $template, $context['block_name'] ?? '', - $context['attributes']['className'] ?? '' + $context['block_attributes']['className'] ?? '' ); } } @@ -179,6 +213,16 @@ function apply_filters( string $hook, $value, ...$arguments ) { } } + function remove_filter( string $hook, callable $callback, int $priority = 10 ): bool { + foreach ( $GLOBALS['emulsify_core_block_twig_smoke_filters'][ $hook ][ $priority ] ?? array() as $index => $entry ) { + if ( $entry['callback'] === $callback ) { + unset( $GLOBALS['emulsify_core_block_twig_smoke_filters'][ $hook ][ $priority ][ $index ] ); + return true; + } + } + return false; + } + if ( ! function_exists( 'get_stylesheet_directory' ) ) { function get_stylesheet_directory(): string { return $GLOBALS['emulsify_core_block_twig_smoke_child']; @@ -244,6 +288,11 @@ function emulsify_core_block_twig_smoke_assert( bool $condition, string $message } } + function render_block( array $block ): string { + ++$GLOBALS['emulsify_core_block_rerenders']; + return 'Unexpected second render'; + } + /** * Writes a fixture file. * @@ -310,6 +359,8 @@ function emulsify_core_block_twig_smoke_remove( string $path ): void { 'blockName' => 'core/paragraph', 'attrs' => array( 'className' => 'intro', + 'level' => 2, + 'anchor' => 'saved-anchor', ), 'innerContent' => array( 'Original' ), 'innerBlocks' => array(), @@ -342,13 +393,15 @@ static function ( array $map ): array { 'emulsify_theme_core_block_twig_context', static function ( array $context ): array { $context['smoke_context'] = true; + $context['legacy_level'] = $context['attributes']['level'] ?? 'empty'; return $context; } ); \Timber\Timber::$context = array( - 'site' => 'Smoke Site', + 'site' => 'Smoke Site', + 'attributes' => array( 'data-global' => 'must not leak' ), ); $enabled = new \Emulsify\Theme\Blocks\CoreBlockTwigRenderer(); @@ -361,9 +414,24 @@ static function ( array $context ): array { $mapped = apply_filters( 'render_block', $original, $block, null ); + emulsify_core_block_twig_smoke_assert( + array() === \Timber\Timber::$compiled[0]['context']['attributes'], + 'Mapped blocks must start with an empty HTML attributes array.' + ); + foreach ( array( 'block_attributes', 'block', 'block_metadata' ) as $key ) { + $actual = \Timber\Timber::$compiled[0]['context'][ $key ]; + emulsify_core_block_twig_smoke_assert( + $block['attrs'] === ( 'block_attributes' === $key ? $actual : $actual['attrs'] ), + 'Mapped block data must remain available through ' . $key . '.' + ); + } + emulsify_core_block_twig_smoke_assert( + 'empty' === \Timber\Timber::$compiled[0]['context']['legacy_level'], + 'Legacy array reads must be empty without throwing or falling back to core markup.' + ); emulsify_core_block_twig_smoke_assert( false !== strpos( $mapped, 'dist/components/paragraph/paragraph.twig:core/paragraph:intro' ), - 'Mapped block should render through Timber compile with attributes.' + 'Mapped block should render through Timber compile with block_attributes.' ); emulsify_core_block_twig_smoke_assert( true === \Timber\Timber::$compiled[0]['context']['smoke_context'], @@ -443,6 +511,128 @@ static function ( array $context ): array { 'Class cleanup should remove base wp-block classes only when enabled.' ); + unset( $GLOBALS['emulsify_core_block_twig_smoke_filters']['emulsify_theme_core_block_twig_cleanup_classes_enabled'] ); + $GLOBALS['emulsify_core_block_rerenders'] = 0; + emulsify_core_block_twig_smoke_write( $child . '/dist/components/inner.twig', '{{ inner_content|raw }}' ); + emulsify_core_block_twig_smoke_write( $child . '/dist/components/content.twig', '{{ content|raw }}' ); + add_filter( + 'emulsify_theme_core_block_twig_template_map', + static function ( array $map ): array { + $map['core/group'] = 'dist/components/inner.twig'; + $map['core/quote'] = 'dist/components/inner.twig'; + $map['core/details'] = 'dist/components/content.twig'; + return $map; + } + ); + $composite_errors = array(); + foreach ( array( 'core/group', 'core/quote' ) as $name ) { + $wrapper = 'core/group' === $name ? 'div' : 'blockquote'; + $before = '<' . $wrapper . ' class="saved-wrapper">'; + $after = ''; + $first = 'First rendered child
'; + $second = ''; + $html = $before . $first . '\n' . $second . $after; + $parsed = array( + 'blockName' => $name, + 'attrs' => array(), + 'innerContent' => array( $before, null, '\n', null, $after ), + 'innerBlocks' => array( array( 'blockName' => 'core/paragraph' ), array( 'blockName' => 'core/html' ) ), + ); + $actual = $enabled->render_block( $html, $parsed ); + if ( $actual !== $html || 1 !== substr_count( $actual, $first ) || 1 !== substr_count( $actual, $second ) ) { + $composite_errors[] = $name . ' must preserve already rendered children, their filters and the original wrapper exactly once.'; + } + $parsed['blockName'] = 'core/details'; + emulsify_core_block_twig_smoke_assert( $html === $enabled->render_block( $html, $parsed ), 'Mapped templates using content must keep every original byte.' ); + } + emulsify_core_block_twig_smoke_assert( 0 === $GLOBALS['emulsify_core_block_rerenders'], 'Inner content must never render a child for a second time.' ); + emulsify_core_block_twig_smoke_assert( array() === $composite_errors, implode( "\n", $composite_errors ) ); + + // Mirror Timber::context()'s queried-post setup and count the cheaper + // global-context entry point independently. + $GLOBALS['emulsify_core_block_twig_smoke_caps'] = array(); + $GLOBALS['post'] = (object) array( 'ID' => 77 ); + $GLOBALS['emulsify_core_block_queried_post'] = (object) array( 'ID' => 999 ); + $GLOBALS['emulsify_core_block_reset_post'] = true; + \Timber\Timber::$context = array( 'site' => 'Global site', 'post' => (object) array( 'ID' => 999 ) ); + \Timber\Timber::$context_calls = 0; + \Timber\Timber::$global_context_calls = 0; + \Timber\Timber::$compiled = array(); + $performance = new \Emulsify\Theme\Blocks\CoreBlockTwigRenderer(); + $performance_errors = array(); + $posts = array(); + for ( $index = 0; $index < 20; ++$index ) { + $instance = (object) array( 'context' => array( 'postId' => 41 + $index % 2 ) ); + $performance->render_block( $original, $block, $instance ); + $latest = end( \Timber\Timber::$compiled ); + $posts[] = ( $latest['context']['post']->ID ?? null ) === $instance->context['postId']; + } + if ( 1 !== \Timber\Timber::$global_context_calls || 0 !== \Timber\Timber::$context_calls ) { + $performance_errors[] = 'Many mapped blocks must build the base global Timber context once without calling context().'; + } + if ( in_array( false, $posts, true ) || 77 !== $GLOBALS['post']->ID ) { + $performance_errors[] = 'Block postId values must select each block post without changing the WordPress global post.'; + } + $GLOBALS['post'] = (object) array( 'ID' => 77 ); + $performance->render_block( $original, $block ); + $latest = end( \Timber\Timber::$compiled ); + if ( 77 !== ( $latest['context']['post']->ID ?? null ) ) { + $performance_errors[] = 'A block without explicit post context must use the current global post rather than the cached base post.'; + } + $performance->render_block( $original, $block, (object) array( 'context' => array( 'postId' => null ) ) ); + $latest = end( \Timber\Timber::$compiled ); + if ( null !== $latest['context']['post'] ) { + $performance_errors[] = 'An explicit missing postId must not reuse another block post.'; + } + + $late_filter = static function ( array $map ): array { + $map['core/heading'] = 'dist/components/inner.twig'; + $map['core/table'] = 'dist/components'; + $map['core/recursive'] = 'dist/components/recursive.twig'; + return $map; + }; + add_filter( 'emulsify_theme_core_block_twig_template_map', $late_filter ); + $heading = array( 'blockName' => 'core/heading', 'innerContent' => array( 'Late mapping' ) ); + if ( 'Late mapping' !== $performance->render_block( 'Late mapping
', $heading ) ) { + $performance_errors[] = 'A template-map filter registered after the first render must take effect.'; + } + $count = count( \Timber\Timber::$compiled ); + if ( 'Core fallback
', array( 'blockName' => 'core/recursive' ) ); + if ( 'Core fallback
Late mapping
' !== $performance->render_block( 'Late mapping
', $heading ) ) { + $performance_errors[] = 'Removing a template-map filter must invalidate its mapping.'; + } + $dynamic_template = 'dist/components/inner.twig'; + add_filter( + 'emulsify_theme_core_block_twig_template_map', + static function ( array $map ) use ( &$dynamic_template ): array { + $map['core/list'] =& $dynamic_template; + return $map; + } + ); + $list = array( 'blockName' => 'core/list', 'innerContent' => array( 'Dynamic' ) ); + $first = $performance->render_block( '- Dynamic
- Dynamic
- Dynamic
Error fallback', array( 'blockName' => 'core/code' ) ); + $recovered = $performance->render_block( $original, $block ); + if ( false === strpos( $recovered, 'mapped' ) ) { + $performance_errors[] = 'Exceptions must unwind the recursion guard so later mapped blocks still render.'; + } + emulsify_core_block_twig_smoke_assert( array() === $performance_errors, implode( "\n", $performance_errors ) ); + echo "Core block Twig renderer smoke checks passed.\n"; } finally { emulsify_core_block_twig_smoke_remove( $work_root ); diff --git a/.github/scripts/docs-command-check.cjs b/.github/scripts/docs-command-check.cjs index 72b3d3b..cf1b73c 100644 --- a/.github/scripts/docs-command-check.cjs +++ b/.github/scripts/docs-command-check.cjs @@ -8,6 +8,14 @@ const repoRoot = path.resolve(__dirname, '../..'); // Documentation that describes the repository itself. Each entry is scoped to a // heading so unrelated prose in the same file cannot satisfy the check. const ROOT_CHECKS = [ + { + relativePath: 'docs/timber-and-twig-authoring.md', + heading: 'Helper characterization', + packagePath: 'package.json', + packageLabel: 'the maintainer checkout', + includeInlineCode: true, + expectedScripts: ['test:twig-helpers', 'whisk:install'], + }, { relativePath: 'README.md', heading: 'Working inside a generated child theme', @@ -98,6 +106,16 @@ const ROOT_CHECKS = [ // against the Whisk source and once against real generated output, so a command // cannot drift between the template and the theme a project actually receives. const THEME_DOC_CHECKS = [ + ...[ + 'AGENTS.md', + 'docs/wordpress-integration.md', + '.agents/skills/emulsify-wordpress-integration/SKILL.md', + ].map((relativePath) => ({ + relativePath, + packagePath: 'package.json', + packageLabel: 'the generated child theme', + includeInlineCode: true, + })), { relativePath: 'README.md', packagePath: 'package.json', diff --git a/.github/scripts/fallback-navigation-smoke.php b/.github/scripts/fallback-navigation-smoke.php new file mode 100644 index 0000000..0190ab6 --- /dev/null +++ b/.github/scripts/fallback-navigation-smoke.php @@ -0,0 +1,231 @@ +loadHTML( '' . $html . '' ); + libxml_clear_errors(); + libxml_use_internal_errors( $previous ); + return new DOMXPath( $document ); +} + +/** + * Records an assertion without stopping the other regression checks. + * + * @param bool $condition Assertion result. + * @param string $message Failure explanation. + * @param array $errors Collected failures. + * @return void + */ +function emulsify_navigation_expect( bool $condition, string $message, array &$errors ): void { + if ( ! $condition ) { + $errors[] = $message; + } +} + +$integration = new Twig(); +$loader = new \Twig\Loader\FilesystemLoader(); +$loader->addPath( __DIR__ . '/../../templates', 'templates' ); +$environment = new \Twig\Environment( $loader, $integration->environment_options( array( 'cache' => false ) ) ); + +foreach ( $integration->functions( array() ) as $name => $definition ) { + $environment->addFunction( + new \Twig\TwigFunction( + $name, + $definition['callable'], + $definition['options'] ?? array() + ) + ); +} + +$environment->addFunction( new \Twig\TwigFunction( 'function', array( new \Timber\Twig(), 'exec_function' ) ) ); +emulsify_register_wordpress_text_test_filters( $environment ); +$integration->extensions( $environment ); + +$hostile = '">'; +$urls = array( + 'Previous' => '/?s=needle&paged=4&filter=a%26b', + '1' => '/?s=needle&paged=1&filter=a%26b', + $hostile => '/?s=needle&paged=6&filter=a%26b', + 'Next' => '/?s=needle&paged=6&filter=a%26b', +); +$display_url = static function ( string $url ): string { + return str_replace( '&', '&', $url ); +}; +$pagination_context = array( + 'pagination' => array( + 'prev' => array( 'link' => $display_url( $urls['Previous'] ) ), + 'pages' => array( + array( 'class' => 'page-number page-numbers', 'title' => '1', 'link' => $display_url( $urls['1'] ), 'current' => false ), + array( 'class' => 'dots', 'title' => '…' ), + array( 'class' => 'page-number page-numbers current', 'title' => '5', 'current' => true ), + array( 'class' => 'page-number page-numbers', 'title' => $hostile, 'link' => $display_url( $urls[ $hostile ] ), 'current' => false ), + ), + 'next' => array( 'link' => $display_url( $urls['Next'] ) ), + ), +); +$pagination = $environment->render( + '@templates/partials/pagination.twig', + $pagination_context +); +$pager_dom = emulsify_navigation_dom( $pagination ); +$checks = array( + 'pagination current page' => array(), + 'pagination literal ellipsis' => array(), + 'pagination page prefixes' => array(), + 'pagination URL escaping' => array(), + 'pagination localized numbers' => array(), + 'menu current item' => array(), +); + +$current = $pager_dom->query( '//nav//*[@aria-current="page"]' ); +emulsify_navigation_expect( 1 === $current->length && '5' === trim( $current->item( 0 )->textContent ), 'Only the actual current page must have aria-current="page".', $checks['pagination current page'] ); +emulsify_navigation_expect( 1 === $pager_dom->query( '//li[contains(concat(" ", normalize-space(@class), " "), " pagination__item--current ")]' )->length, 'The current item must preserve its BEM modifier.', $checks['pagination current page'] ); + +// Current state must also work when a pagination provider supplies a link. +$pagination_context['pagination']['pages'][2]['link'] = $display_url( '/?s=needle&paged=5&filter=a%26b' ); +$linked_current_dom = emulsify_navigation_dom( $environment->render( '@templates/partials/pagination.twig', $pagination_context ) ); +$linked_current = $linked_current_dom->query( '//nav//*[@aria-current="page"]' ); +emulsify_navigation_expect( 1 === $linked_current->length && '5' === trim( $linked_current->item( 0 )->lastChild->textContent ), 'An explicitly current item must be marked even when it supplies a link.', $checks['pagination current page'] ); + +$dots = $pager_dom->query( '//nav//*[contains(concat(" ", normalize-space(@class), " "), " dots ")]' ); +emulsify_navigation_expect( 1 === $dots->length && 'span' === $dots->item( 0 )->nodeName && '…' === trim( $dots->item( 0 )->textContent ), 'Timber ellipsis items must render as non-interactive spans with the literal … character.', $checks['pagination literal ellipsis'] ); +emulsify_navigation_expect( false !== strpos( $pagination, '…' ) && false === strpos( $pagination, '…' ), 'The ellipsis must not appear as literal entity text.', $checks['pagination literal ellipsis'] ); +emulsify_navigation_expect( in_array( array( '…', 'emulsify' ), $GLOBALS['emulsify_navigation_translations'] ?? array(), true ), 'The literal ellipsis must pass through the theme translation domain.', $checks['pagination literal ellipsis'] ); + +$links = $pager_dom->query( '//nav//a' ); +emulsify_navigation_expect( count( $urls ) === $links->length, 'Previous, numeric, and next pagination links must all render.', $checks['pagination URL escaping'] ); + +$numbered_links = $pager_dom->query( '//nav//a[contains(concat(" ", normalize-space(@class), " "), " page-number ")]' ); +$prefix_query = './span[contains(concat(" ", normalize-space(@class), " "), " screen-reader-text ")]'; +emulsify_navigation_expect( 2 === $numbered_links->length, 'The fixture must contain two numbered pagination links.', $checks['pagination page prefixes'] ); +foreach ( $numbered_links as $link ) { + $prefixes = $pager_dom->query( $prefix_query, $link ); + emulsify_navigation_expect( 1 === $prefixes->length && 'Page ' === $prefixes->item( 0 )->textContent, 'Each numbered pagination link must contain one screen-reader-text span with Page and a trailing space.', $checks['pagination page prefixes'] ); +} +$linked_prefixes = $linked_current_dom->query( $prefix_query, $linked_current->item( 0 ) ); +emulsify_navigation_expect( 1 === $linked_prefixes->length && 'Page ' === $linked_prefixes->item( 0 )->textContent, 'A current page supplied as a numbered link must retain the Page prefix.', $checks['pagination page prefixes'] ); +emulsify_navigation_expect( 2 === $pager_dom->query( '//nav//span[contains(concat(" ", normalize-space(@class), " "), " screen-reader-text ")]' )->length, 'Previous, next, unlinked current, and ellipsis items must not acquire Page prefix spans.', $checks['pagination page prefixes'] ); +emulsify_navigation_expect( in_array( array( 'Page', 'emulsify' ), $GLOBALS['emulsify_navigation_translations'] ?? array(), true ), 'The Page prefix must use the parent theme translation domain.', $checks['pagination page prefixes'] ); + +$GLOBALS['emulsify_navigation_translation_overrides']['emulsify']['Page'] = $hostile; +$translated_pagination = $environment->render( '@templates/partials/pagination.twig', $pagination_context ); +$translated_dom = emulsify_navigation_dom( $translated_pagination ); +$translated_prefixes = $translated_dom->query( '//nav//span[contains(concat(" ", normalize-space(@class), " "), " screen-reader-text ")]' ); +emulsify_navigation_expect( $translated_prefixes->length > 0 && $hostile . ' ' === $translated_prefixes->item( 0 )->textContent && 0 === $translated_dom->query( '//script' )->length, 'Translated Page prefixes must remain HTML escaped and retain their separating space.', $checks['pagination page prefixes'] ); +unset( $GLOBALS['emulsify_navigation_translation_overrides'] ); + +$localized_pagination = $environment->render( + '@templates/partials/pagination.twig', + array( + 'pagination' => array( + 'pages' => array( + array( 'title' => '1 000', 'current' => true ), + array( 'title' => '1 001', 'link' => '/?paged=1001', 'current' => false ), + ), + ), + ) +); +$localized_dom = emulsify_navigation_dom( $localized_pagination ); +$localized_current = $localized_dom->query( '//nav//span[@aria-current="page"]' ); +$localized_link = $localized_dom->query( '//nav//a' ); +emulsify_navigation_expect( 1 === $localized_current->length && "1\u{00A0}000" === $localized_current->item( 0 )->textContent, 'Current page numbers must render a non-breaking thousands separator.', $checks['pagination localized numbers'] ); +emulsify_navigation_expect( 1 === $localized_link->length && "Page 1\u{00A0}001" === $localized_link->item( 0 )->textContent, 'Linked page numbers must retain the Page prefix and a non-breaking thousands separator.', $checks['pagination localized numbers'] ); +emulsify_navigation_expect( false === strpos( $localized_pagination, ' ' ) && false === strpos( $localized_pagination, ' ' ), 'Localized numbers must contain the actual non-breaking space, not literal or double-escaped entity text.', $checks['pagination localized numbers'] ); + +$expected_urls = array_values( $urls ); +foreach ( $links as $index => $link ) { + $title = trim( $link->textContent ); + $actual = $link->getAttribute( 'href' ); + $expected = $expected_urls[ $index ] ?? ''; + parse_str( (string) parse_url( $actual, PHP_URL_QUERY ), $actual_query ); + parse_str( (string) parse_url( $expected, PHP_URL_QUERY ), $expected_query ); + emulsify_navigation_expect( '' !== $expected && $actual === $expected && $actual_query === $expected_query && null === parse_url( $actual, PHP_URL_FRAGMENT ), sprintf( '%s link must decode once to %s; got %s.', $title, $expected, $actual ), $checks['pagination URL escaping'] ); +} + +$raw_url = '/?s=x&paged=2"e=" onmouseover="alert(1)'; +$attributes = $environment->createTemplate( '{{ title }}' )->render( array( 'url' => $raw_url, 'title' => $hostile ) ); +$raw_dom = emulsify_navigation_dom( $attributes ); +$raw_link = $raw_dom->query( '//a' )->item( 0 ); +emulsify_navigation_expect( $raw_url === $raw_link->getAttribute( 'href' ) && $hostile === $raw_link->getAttribute( 'title' ) && ! $raw_link->hasAttribute( 'onmouseover' ) && 0 === $raw_dom->query( '//script' )->length && false !== strpos( $attributes, '&paged=' ), 'AttributeBag must continue escaping raw ampersands, quotes, and hostile titles.', $checks['pagination URL escaping'] ); +emulsify_navigation_expect( 0 === $pager_dom->query( '//script' )->length, 'Pagination titles must remain HTML escaped.', $checks['pagination URL escaping'] ); + +$menu = $environment->render( + '@templates/partials/menu.twig', + array( + 'items' => array( + array( + 'title' => 'Ancestor', + 'link' => '/ancestor/', + 'current' => false, + 'current_item_ancestor' => true, + 'current_item_parent' => true, + 'classes' => array( 'current-menu-ancestor', 'current-menu-parent' ), + 'children' => array( + array( 'title' => 'Current', 'link' => '/current/', 'current' => true ), + ), + ), + array( 'title' => $hostile, 'link' => '/unrelated/?a=1&b=2', 'current' => false ), + ), + ) +); +$menu_dom = emulsify_navigation_dom( $menu ); +$current = $menu_dom->query( '//ul//a[@aria-current="page"]' ); +emulsify_navigation_expect( 1 === $current->length && '/current/' === $current->item( 0 )->getAttribute( 'href' ), 'Only the actual current menu link must have aria-current="page"; ancestors stay unmarked.', $checks['menu current item'] ); +emulsify_navigation_expect( 1 === $menu_dom->query( '//ul[contains(concat(" ", normalize-space(@class), " "), " menu--sub ")]' )->length && 0 === $menu_dom->query( '//script' )->length, 'Nested menu BEM classes and HTML-escaped titles must remain intact.', $checks['menu current item'] ); + +$failed = false; + +foreach ( $checks as $name => $errors ) { + if ( $errors ) { + $failed = true; + fwrite( STDERR, 'FAIL ' . $name . ': ' . implode( ' ', $errors ) . "\n" ); + } else { + echo 'PASS ' . $name . "\n"; + } +} + +exit( $failed ? 1 : 0 ); diff --git a/.github/scripts/file-discovery-smoke.php b/.github/scripts/file-discovery-smoke.php new file mode 100644 index 0000000..7817974 --- /dev/null +++ b/.github/scripts/file-discovery-smoke.php @@ -0,0 +1,185 @@ +isDir() && ! $file->isLink() ? rmdir( $file->getPathname() ) : unlink( $file->getPathname() ); + } + rmdir( $path ); +} + +/** Removes a selected directory exactly when SPL attempts to open it. */ +final class DiscoveryVanishingDirectory { + public $context; + private $directory; + public static string $remove_on_open; + public static bool $removed = false; + + private static function native( callable $operation ) { + stream_wrapper_restore( 'file' ); + try { + return $operation(); + } finally { + stream_wrapper_unregister( 'file' ); + stream_wrapper_register( 'file', self::class ); + } + } + public function url_stat( $path, $flags ) { + return self::native( static fn() => $flags & STREAM_URL_STAT_LINK ? @lstat( $path ) : @stat( $path ) ); + } + public function dir_opendir( $path, $options ): bool { + if ( ! self::$removed && $path === self::$remove_on_open ) { + self::native( static function () use ( $path ): void { discovery_remove( $path ); } ); + self::$removed = true; + } + $this->directory = self::native( static fn() => @opendir( $path ) ); + return is_resource( $this->directory ); + } + public function dir_readdir() { return readdir( $this->directory ); } + public function dir_rewinddir(): bool { rewinddir( $this->directory ); return true; } + public function dir_closedir(): bool { closedir( $this->directory ); return true; } +} + +$root = sys_get_temp_dir() . '/emulsify-file-discovery-' . bin2hex( random_bytes( 5 ) ); +$failures = array(); +$wrapped = false; +$denied = $root . '/permissions/a-denied'; +try { + discovery_write( $root . '/ordinary/z.js' ); + discovery_write( $root . '/ordinary/a/deep.CSS' ); + discovery_write( $root . '/ordinary/a/readme.txt' ); + $expected = array( $root . '/ordinary/a/deep.CSS', $root . '/ordinary/z.js' ); + discovery_assert( $expected === FileDiscovery::recursive_files( $root . '/ordinary', array( '.CSS', 'js' ) ), 'Discovery must retain deterministic ordering and extension normalization.' ); + discovery_assert( array( $root . '/ordinary/z.js' ) === FileDiscovery::directory_files( $root . '/ordinary', array( 'js' ) ), 'Non-recursive discovery must retain its immediate-file behavior.' ); + $complete = false; + FileDiscovery::file_records( array( array( 'path' => $root . '/ordinary' ) ), array( 'js' ), true, $complete ); + discovery_assert( $complete, 'A complete file-record scan must set its completion flag.' ); + + discovery_write( $root . '/permissions/z-readable/visible.component.json' ); + discovery_write( $denied . '/hidden.component.json' ); + chmod( $denied, 0000 ); + clearstatcache( true ); + if ( ! is_readable( $denied ) ) { + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + try { + $complete = true; + $actual = FileDiscovery::recursive_files( $root . '/permissions', array( 'json' ), $complete ); + discovery_assert( array( $root . '/permissions/z-readable/visible.component.json' ) === $actual, 'An unreadable component branch must not hide readable siblings.' ); + discovery_assert( ! $complete, 'An unreadable branch must mark its scan incomplete so it cannot be cached.' ); + FileDiscovery::recursive_files( $root . '/permissions', array( 'json' ) ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'An unreadable branch must report once per root only in debug mode.' ); + } catch ( Throwable $error ) { + $failures[] = 'Unreadable subdirectory: ' . $error->getMessage(); + } + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + discovery_assert( array() === FileDiscovery::normalize_roots( array( $denied ) ), 'An unreadable root must be excluded.' ); + FileDiscovery::normalize_roots( array( $denied ) ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'An existing unreadable root must report once in debug mode.' ); + } else { + echo "Permission bits are bypassed by this user; the vanished-directory race below still exercises failure handling.\n"; + } + chmod( $denied, 0755 ); + + discovery_write( $root . '/race/z-readable/visible.json' ); + discovery_write( $root . '/race/a-vanishing/hidden.json' ); + DiscoveryVanishingDirectory::$remove_on_open = $root . '/race/a-vanishing'; + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + stream_wrapper_unregister( 'file' ); + stream_wrapper_register( 'file', DiscoveryVanishingDirectory::class ); + $wrapped = true; + try { + $complete = true; + $actual = FileDiscovery::file_records( array( array( 'path' => $root . '/race' ) ), array( 'json' ), true, $complete ); + discovery_assert( DiscoveryVanishingDirectory::$removed, 'The race fixture must actually remove a directory during the scan.' ); + discovery_assert( array( $root . '/race/z-readable/visible.json' ) === array_column( $actual, 'path' ), 'A vanished branch must not stop discovery of readable siblings.' ); + discovery_assert( ! $complete, 'A vanished branch must mark file records incomplete so they cannot be cached.' ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'A vanished branch must report once per root only in debug mode.' ); + } catch ( Throwable $error ) { + $failures[] = 'Vanished subdirectory: ' . $error->getMessage(); + } finally { + stream_wrapper_restore( 'file' ); + $wrapped = false; + } + discovery_write( $root . '/race-flat/hidden.json' ); + DiscoveryVanishingDirectory::$remove_on_open = $root . '/race-flat'; + DiscoveryVanishingDirectory::$removed = false; + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + stream_wrapper_unregister( 'file' ); + stream_wrapper_register( 'file', DiscoveryVanishingDirectory::class ); + $wrapped = true; + try { + $complete = true; + discovery_assert( array() === FileDiscovery::directory_files( $root . '/race-flat', array(), $complete ), 'A vanished non-recursive root must return an empty result.' ); + discovery_assert( DiscoveryVanishingDirectory::$removed && ! $complete, 'A vanished non-recursive root must mark its scan incomplete.' ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'A vanished non-recursive root must report only in debug mode.' ); + } finally { + stream_wrapper_restore( 'file' ); + $wrapped = false; + } + + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + try { + $complete = true; + discovery_assert( array() === FileDiscovery::recursive_files( $root . '/missing', array(), $complete ), 'A missing scan root must return an empty result.' ); + discovery_assert( ! $complete, 'A missing root must mark its scan incomplete.' ); + FileDiscovery::recursive_files( $root . '/missing' ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'A missing scan root must not be silently dropped in debug mode.' ); + } catch ( Throwable $error ) { + $failures[] = 'Missing root: ' . $error->getMessage(); + } + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + $complete = true; + discovery_assert( array() === FileDiscovery::directory_files( $root . '/missing-flat', array(), $complete ) && ! $complete, 'A missing non-recursive root must be harmless and mark its scan incomplete.' ); + discovery_assert( ( WP_DEBUG ? 1 : 0 ) === count( $GLOBALS['file_discovery_diagnostics'] ) - $before, 'A missing non-recursive root must report only in debug mode.' ); + $before = count( $GLOBALS['file_discovery_diagnostics'] ); + FileDiscovery::normalize_roots( array( $root . '/missing-optional' ) ); + discovery_assert( $before === count( $GLOBALS['file_discovery_diagnostics'] ), 'Optional missing roots must stay quiet.' ); + if ( $failures ) { + throw new RuntimeException( implode( "\n", $failures ) ); + } + echo 'File discovery smoke passed in ' . ( WP_DEBUG ? 'debug' : 'production' ) . " mode.\n"; + if ( WP_DEBUG ) { + passthru( escapeshellarg( PHP_BINARY ) . ' ' . escapeshellarg( __FILE__ ) . ' --production', $status ); + discovery_assert( 0 === $status, 'Production-mode discovery must also pass.' ); + } +} finally { + if ( $wrapped ) { + stream_wrapper_restore( 'file' ); + } + if ( is_dir( $denied ) ) { + chmod( $denied, 0755 ); + } + discovery_remove( $root ); +} diff --git a/.github/scripts/formatted-text-dom-smoke.php b/.github/scripts/formatted-text-dom-smoke.php new file mode 100644 index 0000000..28d6b16 --- /dev/null +++ b/.github/scripts/formatted-text-dom-smoke.php @@ -0,0 +1,60 @@ +loadHTML( '' . $fixture['html'] ); +libxml_clear_errors(); +$xpath = new DOMXPath( $document ); + +foreach ( $fixture['assertions'] as $assertion ) { + $nodes = $xpath->query( $assertion['xpath'] ); + if ( false === $nodes || 0 === $nodes->length ) { + throw new RuntimeException( $fixture['name'] . ': missing ' . $assertion['xpath'] ); + } + foreach ( $nodes as $node ) { + $actual = isset( $assertion['attribute'] ) ? $node->getAttribute( $assertion['attribute'] ) : trim( $node->textContent ); + if ( isset( $assertion['contains'] ) ) { + $matches = str_contains( $actual, $assertion['contains'] ); + } else { + $matches = $actual === $assertion['text']; + } + if ( ! $matches ) { + throw new RuntimeException( $fixture['name'] . ': ' . $assertion['xpath'] . ' visible value was ' . json_encode( $actual ) . '; expected ' . json_encode( $assertion['text'] ?? $assertion['contains'] ) ); + } + if ( preg_match( '/&(?:amp|quot|lt|gt|#\d+|#x[0-9a-f]+);/i', $actual ) ) { + throw new RuntimeException( $fixture['name'] . ': literal HTML entity in DOM value.' ); + } + $allowed = $assertion['elements'] ?? array(); + foreach ( $node->getElementsByTagName( '*' ) as $element ) { + if ( ! in_array( strtolower( $element->tagName ), $allowed, true ) ) { + throw new RuntimeException( $fixture['name'] . ': unexpected ' . $element->tagName . ' inside ' . $assertion['xpath'] ); + } + foreach ( $element->attributes as $attribute ) { + if ( str_starts_with( strtolower( $attribute->name ), 'on' ) ) { + throw new RuntimeException( $fixture['name'] . ': executable event attribute survived.' ); + } + if ( in_array( strtolower( $attribute->name ), array( 'src', 'href' ), true ) && preg_match( '/^\s*(?:javascript|vbscript|data):/i', $attribute->value ) ) { + throw new RuntimeException( $fixture['name'] . ': unsafe URL protocol survived.' ); + } + } + } + if ( isset( $assertion['elementCount'] ) && $node->getElementsByTagName( '*' )->length !== $assertion['elementCount'] ) { + throw new RuntimeException( $fixture['name'] . ': safe inline title markup was lost.' ); + } + if ( isset( $assertion['attribute'] ) ) { + foreach ( $node->attributes as $attribute ) { + if ( ! in_array( $attribute->name, array( 'src', 'alt' ), true ) ) { + throw new RuntimeException( $fixture['name'] . ': image attribute breakout: ' . $attribute->name ); + } + } + } + } +} + +echo "DOM text and attributes passed.\n"; diff --git a/.github/scripts/generated-audit-wrappers.test.cjs b/.github/scripts/generated-audit-wrappers.test.cjs new file mode 100644 index 0000000..d9481a9 --- /dev/null +++ b/.github/scripts/generated-audit-wrappers.test.cjs @@ -0,0 +1,156 @@ +#!/usr/bin/env node + +// Opt-in integration: generate the real child theme and install a packed Core +// artifact. No network installation is added to the ordinary contract tests. +const assert = require('node:assert/strict'); +const { spawnSync } = require('node:child_process'); +const { createHash } = require('node:crypto'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { test } = require('node:test'); + +const repoRoot = path.resolve(__dirname, '../..'); +const excluded = new Set(['.git', 'node_modules', 'dist', '.out', '.coverage', '.cache']); +const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'; +const npx = process.platform === 'win32' ? 'npx.cmd' : 'npx'; + +function writeJson(file, value) { + fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`); +} + +function run(command, args, cwd, env) { + const result = spawnSync(command, args, { + cwd, + env, + encoding: 'utf8', + timeout: 180000, + maxBuffer: 8 * 1024 * 1024, + }); + assert.ifError(result.error); + assert.equal(result.signal, null, `Unexpected signal: ${result.signal}`); + return result; +} + +function assertWrapper(result, direct, footer) { + assert.equal(result.status, direct.status, 'Wrapper must preserve the exact Core exit status.'); + let report; + assert.doesNotThrow(() => { + // Parsing a substring or dropping a footer would conceal this regression. + report = JSON.parse(result.stdout); + }, 'The entire stdout stream must be valid JSON.'); + assert.deepEqual(report, JSON.parse(direct.stdout), 'Wrapper must forward every argument unchanged.'); + assert.equal(report.schemaVersion, 1); + assert.equal(report.tool.name, '@emulsify/core'); + assert.equal(result.stderr, `${direct.stderr}\n${footer}\n`, 'The exact documentation footer belongs on stderr.'); + assert.ok(!result.stdout.includes(footer), 'Documentation footer must not enter stdout.'); +} + +test('real generated audit wrappers retain the packed Core CLI contract', { timeout: 240000 }, async (t) => { + assert.ok(process.env.EMULSIFY_CORE_TARBALL, 'Set EMULSIFY_CORE_TARBALL to a local npm pack .tgz artifact.'); + const tarball = path.resolve(process.env.EMULSIFY_CORE_TARBALL); + const tarballHash = createHash('sha256').update(fs.readFileSync(tarball)).digest('hex'); + const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'emulsify-generated-audit-')); + const consumer = path.join(workRoot, 'generated child with spaces'); + const env = { + ...process.env, + CI: '1', + FORCE_COLOR: '0', + PUPPETEER_SKIP_DOWNLOAD: 'true', + npm_config_cache: process.env.npm_config_cache || path.join(workRoot, 'npm-cache'), + }; + + try { + fs.cpSync(path.join(repoRoot, 'whisk'), consumer, { + recursive: true, + filter: (source) => !excluded.has(path.basename(source)), + }); + const projectPath = path.join(consumer, 'project.emulsify.json'); + const project = JSON.parse(fs.readFileSync(projectPath, 'utf8')); + Object.assign(project.project, { + name: 'Audit Fixture', machineName: 'audit-fixture', description: 'Generated audit wrapper contract.', + }); + writeJson(projectPath, project); + const generation = run(process.execPath, [path.join(consumer, '.cli/init.js')], consumer, env); + assert.equal(generation.status, 0, generation.stderr); + const packagePath = path.join(consumer, 'package.json'); + const generated = JSON.parse(fs.readFileSync(packagePath, 'utf8')); + const source = JSON.parse(fs.readFileSync(path.join(repoRoot, 'whisk/package.json'), 'utf8')); + assert.deepEqual(generated.scripts, source.scripts, 'Generation must retain the real starter scripts.'); + const install = run(npm, ['install', '--ignore-scripts', '--no-audit', '--no-fund', '--package-lock=false', '--save-exact', tarball], consumer, env); + assert.equal(install.status, 0, install.stderr); + const installed = JSON.parse(fs.readFileSync(packagePath, 'utf8')); + assert.deepEqual(installed.scripts, generated.scripts); + const coreRoot = path.join(consumer, 'node_modules/@emulsify/core'); + assert.equal(fs.lstatSync(coreRoot).isSymbolicLink(), false, 'Use an installed package, not a source symlink.'); + const coreVersion = JSON.parse(fs.readFileSync(path.join(coreRoot, 'package.json'), 'utf8')).version; + t.diagnostic(JSON.stringify({ coreVersion, tarballSha256: tarballHash, generatedScripts: { audit: generated.scripts.audit, 'audit:twig-stories': generated.scripts['audit:twig-stories'] } })); + + const auditRoot = path.join(workRoot, 'audit root with spaces'); + const component = path.join(auditRoot, 'src/components/card'); + fs.mkdirSync(component, { recursive: true }); + writeJson(path.join(auditRoot, 'project.emulsify.json'), { project: { platform: 'none' } }); + fs.writeFileSync(path.join(component, 'card.twig'), '
{{ title }}
'); + fs.writeFileSync(path.join(component, 'card.stories.js'), 'import cardTwig from "./card.twig";\nexport const Card = (args) => cardTwig(args);\n'); + const cleanRoot = path.join(workRoot, 'clean root with spaces'); + const cleanComponent = path.join(cleanRoot, 'src/components/clean'); + fs.mkdirSync(cleanComponent, { recursive: true }); + writeJson(path.join(cleanRoot, 'project.emulsify.json'), { project: { platform: 'none' } }); + fs.writeFileSync(path.join(cleanComponent, 'clean.stories.js'), 'export default { title: "Audit/Clean" };\nexport const Clean = () => "Clean
";\n'); + + for (const [script, executable, footer, threshold] of [ + ['audit', 'audit.js', 'Audit docs: https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/migration-4x.md#storybook-migration', ['--fail-on', 'warn']], + ['audit:twig-stories', 'audit-twig-stories.js', 'Migration docs: https://github.com/emulsify-ds/emulsify-core/blob/4.x/docs/storybook.md#legacy-twig-story-compatibility', ['--fail-on-found']], + ]) { + const args = ['--root', auditRoot, '--json']; + const directRun = (options) => run(path.join(coreRoot, 'scripts', executable), options, consumer, env); + const wrapperRun = (options) => run(npm, ['run', script, '--silent', '--', ...options], consumer, env); + for (const [scenario, options, expectedStatus] of [ + ['clean scan', ['--root', cleanRoot, '--json', ...threshold], 0], + ['advisory findings', args, 0], + ['findings fail threshold', [...args, ...threshold], 1], + ['invalid argument', [...args, '--unknown-wrapper-option'], 2], + ]) { + await t.test(`${script}: ${scenario}`, () => { + const direct = directRun(options); + assert.equal(direct.status, expectedStatus, direct.stderr); + const report = JSON.parse(direct.stdout); + if (scenario === 'clean scan') { + assert.deepEqual(report.findings, []); + } else if (expectedStatus !== 2) { + assert.ok(report.findings.some((finding) => finding.id === 'legacy-twig-story' && finding.path === 'src/components/card/card.stories.js' && finding.line === 2 && finding.severity === 'warn')); + } + const wrapped = wrapperRun(options); + assertWrapper(wrapped, direct, footer); + const executableName = executable === 'audit.js' ? 'emulsify-audit' : 'emulsify-audit-twig-stories'; + const directAlias = run(npx, ['--no-install', executableName, ...options], consumer, env); + assert.equal(directAlias.status, expectedStatus); + assert.deepEqual(JSON.parse(directAlias.stdout), report); + assert.equal(directAlias.stderr, direct.stderr); + t.diagnostic(JSON.stringify({ script, scenario, options, directStatus: direct.status, wrapperStatus: wrapped.status, npxNoInstallStatus: directAlias.status, wholeStdoutJson: true, footerOnStderr: true })); + }); + } + + for (const [scenario, mutate, expectedFailure] of [ + ['rejects stdout footer', (command) => command.replace(' >&2;', ';'), /entire stdout stream/], + ['rejects masked status', (command) => command.replace('exit $status', 'exit 0'), /exact Core exit status/], + ['rejects dropped arguments', (command) => command.replace('"$@"', ''), /exact Core exit status|forward every argument/], + ]) { + await t.test(`${script}: ${scenario}`, () => { + const modified = structuredClone(installed); + modified.scripts[script] = mutate(modified.scripts[script]); + assert.notEqual(modified.scripts[script], installed.scripts[script]); + writeJson(packagePath, modified); + try { + const options = [...args, ...threshold]; + assert.throws(() => assertWrapper(wrapperRun(options), directRun(options), footer), expectedFailure); + } finally { + writeJson(packagePath, installed); + } + }); + } + } + } finally { + fs.rmSync(workRoot, { recursive: true, force: true }); + } +}); diff --git a/.github/scripts/generated-theme-contract.cjs b/.github/scripts/generated-theme-contract.cjs index f911bd7..df18f6e 100644 --- a/.github/scripts/generated-theme-contract.cjs +++ b/.github/scripts/generated-theme-contract.cjs @@ -15,6 +15,7 @@ const fs = require('fs'); const path = require('path'); const { isDeepStrictEqual } = require('util'); +const yaml = require('js-yaml'); const { validateDocumentation } = require('./docs-command-check.cjs'); @@ -24,6 +25,7 @@ const SECTION_LABELS = { frontend: 'frontend metadata', references: 'file references', documentation: 'documentation', + guidance: 'AI guidance', placeholders: 'placeholder replacement', build: 'build', }; @@ -48,7 +50,12 @@ const REQUIRED_GENERATED_FILES = [ 'docs/development.md', 'docs/support-information.md', 'docs/upgrading.md', - 'templates/page.twig', +]; + +const REQUIRED_GUIDANCE_FILES = [ + 'AGENTS.md', + 'docs/wordpress-integration.md', + '.agents/skills/emulsify-wordpress-integration/SKILL.md', ]; // Generation-only tooling and build output must never reach a project repo. @@ -181,10 +188,10 @@ function checkEqual(addError, section, themeLabel, file, key, actual, want) { } function validateGenerationShape(validator, contract) { - const { themeDir, themeLabel, sourceDir } = contract; + const { themeDir, themeLabel, sourceDir, checkBuiltAssets } = contract; const entries = listFilesRecursive(themeDir); const relativeFiles = new Set( - entries.filter((entry) => entry.file).map((entry) => entry.relativePath), + entries.filter((entry) => entry.file).map((entry) => entry.relativePath.split(path.sep).join('/')), ); for (const requiredFile of REQUIRED_GENERATED_FILES) { @@ -209,6 +216,9 @@ function validateGenerationShape(validator, contract) { } for (const forbidden of FORBIDDEN_GENERATED_PATHS) { + if (checkBuiltAssets && forbidden !== '.cli') { + continue; + } if (fs.existsSync(path.join(themeDir, forbidden))) { validator.addError( 'generation', @@ -454,6 +464,7 @@ function validateScriptReferences(validator, contract, scripts) { function validateMarkdownReferences(validator, contract, entries) { const { themeDir, themeLabel } = contract; const themeRoot = path.resolve(themeDir); + const realThemeRoot = fs.realpathSync(themeRoot); for (const entry of entries) { if (!entry.file || !entry.relativePath.endsWith('.md')) { @@ -461,6 +472,8 @@ function validateMarkdownReferences(validator, contract, entries) { } const contents = readTextFile(path.join(themeDir, entry.relativePath)); + const relativePath = entry.relativePath.split(path.sep).join('/'); + const section = REQUIRED_GUIDANCE_FILES.includes(relativePath) || relativePath.startsWith('.agents/skills/') ? 'guidance' : 'references'; for (const match of contents.matchAll(/\[[^\]]*\]\(([^)]+)\)/g)) { const target = match[1].replace(/^<|>$/g, '').split('#')[0].trim(); @@ -474,24 +487,57 @@ function validateMarkdownReferences(validator, contract, entries) { target, ); - if (!resolved.startsWith(themeRoot)) { - validator.addError( - 'references', + if (resolved !== themeRoot && !resolved.startsWith(`${themeRoot}${path.sep}`)) { + validator.addError(section, `${themeLabel} has documentation link ${expected(target)} in ${expected(entry.relativePath)} that resolves outside the generated child theme; expected a self-contained path or published package.`, ); continue; } if (!fs.existsSync(resolved)) { - validator.addError( - 'references', + validator.addError(section, `${themeLabel} has documentation link ${expected(target)} in ${expected(entry.relativePath)} that resolves to missing local path ${expected(path.relative(themeDir, resolved))}; expected it inside the generated child theme.`, ); + continue; + } + + const realTarget = fs.realpathSync(resolved); + if (realTarget !== realThemeRoot && !realTarget.startsWith(`${realThemeRoot}${path.sep}`)) { + validator.addError( + section, + `${themeLabel} has documentation link ${expected(target)} in ${expected(entry.relativePath)} that resolves outside the generated child theme through a symbolic link; expected it inside the generated child theme.`, + ); } } } } +function validateGeneratedGuidance(validator, contract, entries, relativeFiles) { + const { themeDir, themeLabel, sourceDir, checkBuiltAssets } = contract; + for (const relativePath of REQUIRED_GUIDANCE_FILES) { + if (!relativeFiles.has(relativePath)) { + validator.addError('guidance', `${themeLabel} is missing required generated guidance file ${expected(relativePath)}.`); + continue; + } + const source = path.join(sourceDir, relativePath); + if (!checkBuiltAssets && (!fs.existsSync(source) || !fs.readFileSync(path.join(themeDir, relativePath)).equals(fs.readFileSync(source)))) { + validator.addError('guidance', `${themeLabel} changed guidance file ${expected(relativePath)} during generation; expected a byte-for-byte copy of the starter guidance.`); + } + } + + for (const entry of entries.filter((file) => file.file && /^\.agents[\\/]skills[\\/][^\\/]+[\\/]SKILL\.md$/.test(file.relativePath))) { + try { + const frontmatter = readTextFile(path.join(themeDir, entry.relativePath)).match(/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)/); + if (!frontmatter) throw new Error('expected YAML frontmatter bounded by ---'); + const metadata = yaml.load(frontmatter[1]); + if (!metadata || typeof metadata !== 'object' || Array.isArray(metadata) || metadata.name !== path.basename(path.dirname(entry.relativePath))) throw new Error('frontmatter name must match the skill directory'); + if (typeof metadata.description !== 'string' || !metadata.description.trim()) throw new Error('frontmatter description must be a nonempty string'); + } catch (error) { + validator.addError('guidance', `${themeLabel} has invalid skill manifest in ${expected(entry.relativePath)}: ${error.message}.`); + } + } +} + function validateGeneratedDocumentation(validator, contract) { const { themeDir, themeLabel, machineName, displayName, description } = contract; @@ -505,7 +551,8 @@ function validateGeneratedDocumentation(validator, contract) { } for (const error of result.errors) { - validator.addError('documentation', `${themeLabel} ${error}`); + const section = REQUIRED_GUIDANCE_FILES.some((file) => error.replaceAll('\\', '/').includes(`${file}:`)) ? 'guidance' : 'documentation'; + validator.addError(section, `${themeLabel} ${error}`); } const readmePath = path.join(themeDir, 'README.md'); @@ -704,6 +751,7 @@ function validateGeneratedTheme(options) { description: normalizeWhitespace(description), parent: 'emulsify', sourceDir, + checkBuiltAssets, sourcePackage, sourceProjectFile, sourceProject: sourceProjectFile.project, @@ -712,9 +760,10 @@ function validateGeneratedTheme(options) { sourceDescription: normalizeWhitespace(sourceHeaders.Description), }; - const { entries } = validateGenerationShape(validator, contract); + const { entries, relativeFiles } = validateGenerationShape(validator, contract); validateWordPressMetadata(validator, contract); validateFrontendMetadata(validator, contract); + validateGeneratedGuidance(validator, contract, entries, relativeFiles); validateMarkdownReferences(validator, contract, entries); validateGeneratedDocumentation(validator, contract); validatePlaceholders(validator, contract, entries); diff --git a/.github/scripts/generated-theme-contract.test.cjs b/.github/scripts/generated-theme-contract.test.cjs index dad3ed6..a7f3e75 100644 --- a/.github/scripts/generated-theme-contract.test.cjs +++ b/.github/scripts/generated-theme-contract.test.cjs @@ -27,6 +27,11 @@ const excludedCopySegments = new Set([ const machineName = 'acme-site'; const displayName = 'Acme Site'; const description = 'Marketing site for Acme, Inc. (rebuild).'; +const guidanceFiles = [ + 'AGENTS.md', + 'docs/wordpress-integration.md', + '.agents/skills/emulsify-wordpress-integration/SKILL.md', +]; function copyStarter(source, destination) { fs.mkdirSync(destination, { recursive: true }); @@ -82,13 +87,14 @@ function generateTheme() { return { workRoot, target }; } -function validate(target) { +function validate(target, options = {}) { return validateGeneratedTheme({ themeDir: target, machineName, displayName, description, sourceDir: starterRoot, + ...options, }); } @@ -115,6 +121,36 @@ test('accepts a freshly generated child theme', () => { }); }); +test('freshly generated child themes inherit parent templates without local Twig files', () => { + withGeneratedTheme((target) => { + assert.equal(fs.existsSync(path.join(target, 'templates')), false); + assert.deepEqual( + fs.readdirSync(target, { recursive: true }).filter((file) => file.endsWith('.twig')), + [], + ); + }); +}); + +test('accepts a generated child theme without a local page template', () => { + withGeneratedTheme((target) => { + fs.rmSync(path.join(target, 'templates'), { recursive: true, force: true }); + const result = validate(target); + assert.deepEqual(result.errors, [], result.format()); + }); +}); + +test('allows consumers to add an intentional page override after generation', () => { + withGeneratedTheme((target) => { + fs.mkdirSync(path.join(target, 'templates'), { recursive: true }); + fs.writeFileSync( + path.join(target, 'templates/page.twig'), + "{% extends '@emulsify-tpl/page.twig' %}\n{% block content %}{{ parent() }}
{% endblock %}\n",
+ );
+ const result = validate(target);
+ assert.deepEqual(result.errors, [], result.format());
+ });
+});
+
test('requires the generated documentation set', () => {
withGeneratedTheme((target) => {
fs.rmSync(path.join(target, 'README.md'));
@@ -127,6 +163,129 @@ test('requires the generated documentation set', () => {
});
});
+test('requires all generated AI guidance files', () => {
+ for (const file of guidanceFiles) {
+ withGeneratedTheme((target) => {
+ fs.rmSync(path.join(target, file));
+ const result = validate(target);
+ assert.match(result.format(), /FAIL AI guidance/);
+ assert.ok(result.errors.some((error) => error.includes(`missing required generated guidance file "${file}"`)), result.format());
+ });
+ }
+});
+
+test('preserves guidance bytes during generation and permits project edits after a build', () => {
+ withGeneratedTheme((target) => {
+ for (const file of guidanceFiles) {
+ assert.deepEqual(fs.readFileSync(path.join(target, file)), fs.readFileSync(path.join(starterRoot, file)));
+ fs.appendFileSync(path.join(target, file), '\nProject guidance customized by the team.\n');
+ }
+ const result = validate(target);
+ assert.match(result.format(), /FAIL AI guidance/);
+ for (const file of guidanceFiles) {
+ assert.ok(result.errors.some((error) => error.includes(`changed guidance file "${file}" during generation`)), result.format());
+ }
+ for (const directory of ['dist', 'node_modules', '.out', '.coverage']) {
+ fs.mkdirSync(path.join(target, directory));
+ }
+ const built = validate(target, { checkBuiltAssets: true });
+ assert.deepEqual(built.errors, [], built.format());
+ assert.match(built.format(), /PASS AI guidance/);
+
+ fs.mkdirSync(path.join(target, '.cli'));
+ const leftover = validate(target, { checkBuiltAssets: true });
+ assert.match(leftover.format(), /generation-only or build path "\.cli"/);
+ });
+});
+
+test('validates skill YAML after project customization with actionable errors', () => {
+ for (const [contents, expected] of [
+ ['Missing frontmatter\n', /expected YAML frontmatter/],
+ ['---\nname: [\n---\n', /invalid skill manifest/],
+ ['---\n- name: emulsify-wordpress-integration\n---\n', /name must match the skill directory/],
+ ['---\nname: another-skill\ndescription: Integration guidance\n---\n', /name must match the skill directory/],
+ ['---\nname: emulsify-wordpress-integration\ndescription: ""\n---\n', /description must be a nonempty string/],
+ ['---\nname: emulsify-wordpress-integration\ndescription: [Integration guidance]\n---\n', /description must be a nonempty string/],
+ ]) {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ fs.writeFileSync(path.join(target, guidanceFiles[2]), contents);
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.match(result.format(), /FAIL AI guidance/);
+ assert.match(result.format(), expected);
+ });
+ }
+});
+
+test('accepts a customized skill with folded YAML and local links', () => {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ fs.writeFileSync(path.join(target, guidanceFiles[2]), '---\r\nname: "emulsify-wordpress-integration"\r\ndescription: >\r\n Project integration\r\n guidance.\r\n---\r\n[Integration guide](../../../docs/wordpress-integration.md)\r\n');
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.deepEqual(result.errors, [], result.format());
+ });
+});
+
+test('validates guidance links after customization and rejects missing or escaping targets', () => {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ const skill = path.join(target, guidanceFiles[2]);
+ fs.appendFileSync(skill, '\n[Integration guide](../../../docs/wordpress-integration.md)\n');
+ assert.deepEqual(validate(target, { checkBuiltAssets: true }).errors, []);
+
+ const outside = path.join(path.dirname(target), `${machineName}-external`);
+ fs.mkdirSync(outside);
+ fs.writeFileSync(path.join(outside, 'outside.md'), 'Outside the theme.\n');
+ fs.appendFileSync(skill, `\n[Missing guide](../../../docs/missing.md)\n[Outside theme](../../../../${machineName}-external/outside.md)\n`);
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.match(result.format(), /FAIL AI guidance/);
+ assert.match(result.format(), /resolves to missing local path "docs\/missing\.md"/);
+ assert.match(result.format(), /resolves outside the generated child theme/);
+ });
+});
+
+test('checks npm commands in every generated guidance entry point', () => {
+ for (const file of guidanceFiles) {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ fs.appendFileSync(path.join(target, file), '\nRun `npm run impossible-script` for this project.\n');
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.match(result.format(), /FAIL AI guidance/);
+ assert.ok(result.errors.some((error) => error.includes(`${file}:`) && error.includes('documents npm run impossible-script')), result.format());
+ assert.match(result.format(), /has no "impossible-script" script/);
+ });
+ }
+});
+
+test('rejects guidance links through dependency symlinks outside the theme', () => {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ fs.mkdirSync(path.join(target, 'node_modules'));
+ fs.symlinkSync(path.join(target, 'docs'), path.join(target, 'node_modules', 'local-docs'), 'dir');
+ fs.appendFileSync(path.join(target, 'AGENTS.md'), '\n[Local guide](node_modules/local-docs/development.md)\n');
+ assert.deepEqual(validate(target, { checkBuiltAssets: true }).errors, []);
+ const outside = path.join(path.dirname(target), 'external-package');
+ fs.mkdirSync(outside);
+ fs.writeFileSync(path.join(outside, 'outside.md'), 'Outside the theme.\n');
+ fs.symlinkSync(outside, path.join(target, 'node_modules', 'external-package'), 'dir');
+ fs.appendFileSync(path.join(target, 'AGENTS.md'), '\n[External package](node_modules/external-package/outside.md)\n');
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.match(result.format(), /FAIL AI guidance/);
+ assert.match(result.format(), /resolves outside the generated child theme through a symbolic link/);
+ });
+});
+
+test('continues checking guidance for stale tokens and starter identity after customization', () => {
+ withGeneratedTheme((target) => {
+ fs.mkdirSync(path.join(target, 'dist'));
+ fs.appendFileSync(path.join(target, guidanceFiles[0]), '\n%%EMULSIFY_MACHINE_NAME%%\n');
+ fs.appendFileSync(path.join(target, guidanceFiles[2]), '\nnamespace: whiskHelper\n');
+ const result = validate(target, { checkBuiltAssets: true });
+ assert.match(result.format(), /stale documentation token/);
+ assert.match(result.format(), /stale starter machine name "whisk"/);
+ });
+});
+
test('reports leftover documentation tokens', () => {
withGeneratedTheme((target) => {
const readmePath = path.join(target, 'README.md');
@@ -143,11 +302,10 @@ test('reports leftover documentation tokens', () => {
test('reports a stale starter machine name', () => {
withGeneratedTheme((target) => {
- const templatePath = path.join(target, 'templates/page.twig');
- fs.writeFileSync(
- templatePath,
- fs.readFileSync(templatePath, 'utf8').replace(`${machineName}-page`, 'whisk-page'),
- );
+ const packagePath = path.join(target, 'package.json');
+ const packageJson = readJson(packagePath);
+ packageJson.name = 'whisk';
+ writeJson(packagePath, packageJson);
const result = validate(target);
assert.match(result.format(), /FAIL placeholder replacement/);
diff --git a/.github/scripts/generation-parity-harness.php b/.github/scripts/generation-parity-harness.php
index 95ed048..f188dce 100644
--- a/.github/scripts/generation-parity-harness.php
+++ b/.github/scripts/generation-parity-harness.php
@@ -51,9 +51,53 @@ function get_theme_root(): string {
}
}
+// An installed fixture may supply the real formatting.php without booting a
+// database. Standalone CI retains WordPress's text-field sanitization below,
+// including percent-octet removal; trim(strip_tags()) hid generator drift.
+if ( ! function_exists( 'apply_filters' ) ) {
+ function apply_filters( $hook, $value, ...$arguments ) {
+ return $value;
+ }
+}
+if ( ! function_exists( 'is_utf8_charset' ) ) {
+ function is_utf8_charset(): bool {
+ return true;
+ }
+}
+if ( ! function_exists( 'get_option' ) ) {
+ function get_option( string $name ) {
+ return 'blog_charset' === $name ? 'UTF-8' : false;
+ }
+}
+if ( ! function_exists( '_canonical_charset' ) ) {
+ function _canonical_charset( string $charset ): string {
+ return is_utf8_charset() ? 'UTF-8' : $charset;
+ }
+}
+$wordpress_formatting = getenv( 'EMULSIFY_WP_FORMATTING_FILE' );
+if ( is_string( $wordpress_formatting ) && '' !== $wordpress_formatting ) {
+ foreach ( array( 'compat-utf8.php', 'utf8.php', 'kses.php' ) as $dependency ) {
+ $dependency_path = dirname( $wordpress_formatting ) . '/' . $dependency;
+ if ( is_file( $dependency_path ) ) {
+ require_once $dependency_path;
+ }
+ }
+ require_once $wordpress_formatting;
+}
if ( ! function_exists( 'sanitize_text_field' ) ) {
function sanitize_text_field( string $value ): string {
- return trim( strip_tags( $value ) );
+ $value = preg_replace( '@<(script|style)\b[^>]*?>.*?@si', '', $value );
+ $value = preg_replace_callback(
+ '%<[^>]*?((?=<)|>|$)%',
+ static fn( array $matches ): string => str_contains( $matches[0], '>' ) ? $matches[0] : htmlspecialchars( $matches[0], ENT_QUOTES, 'UTF-8', false ),
+ $value
+ );
+ $value = str_replace( "<\n", "<\n", strip_tags( $value ) );
+ $value = trim( preg_replace( '/[\r\n\t ]+/', ' ', $value ) );
+ while ( preg_match( '/%[a-f0-9]{2}/i', $value, $match ) ) {
+ $value = trim( preg_replace( '/ +/', ' ', str_replace( $match[0], '', $value ) ) );
+ }
+ return $value;
}
}
diff --git a/.github/scripts/generation-parity-smoke.cjs b/.github/scripts/generation-parity-smoke.cjs
index 0f588d1..9751767 100644
--- a/.github/scripts/generation-parity-smoke.cjs
+++ b/.github/scripts/generation-parity-smoke.cjs
@@ -47,6 +47,23 @@ const scenarios = [
displayName: 'Civic Portal',
description: 'Resident services portal: forms, alerts & payments.',
},
+ {
+ machineName: 'unicode-portal',
+ inputMachineName: 'Unicode_Portal',
+ displayName: 'Café \"Portal\" / 100% site',
+ inputDisplayName: 'Café \"Portal\" / 100%20% site',
+ description: 'Quotes \" and \' / café & 100% coverage.',
+ inputDescription: 'Quotes \" and \' / café & 100%25% coverage.',
+ },
+ // WP-CLI delegates HTML stripping to WordPress; standalone init requires the
+ // resulting plain text instead of trying to emulate PHP strip_tags().
+ {
+ machineName: 'wordpress-text',
+ displayName: 'A',
+ inputWpDisplayName: 'A !excluded.has(path.basename(file)) });
+ const projectPath = path.join(theme, 'project.emulsify.json');
+ const project = JSON.parse(fs.readFileSync(projectPath, 'utf8'));
+ Object.assign(project.project, { name: 'Project Jest Fixture', machineName: 'project-jest-fixture' });
+ fs.writeFileSync(projectPath, JSON.stringify(project));
+ const generation = spawnSync(process.execPath, [path.join(theme, '.cli/init.js')], { cwd: theme, encoding: 'utf8' });
+ assert.equal(generation.status, 0, generation.stdout + generation.stderr);
+ fs.symlinkSync(modules, path.join(theme, 'node_modules'), 'junction');
+ fs.mkdirSync(results);
+ fs.cpSync(path.join(repoRoot, '.github/fixtures/whisk-a11y/ci-readiness'), component, { recursive: true });
+
+ let result = run();
+ assert.equal(result.status, 0, result.output);
+ assert.ok(result.report.testResults.some((entry) => entry.name === testFile && entry.status === 'passed'), 'Jest must execute the colocated project ESM test.');
+ const coverage = JSON.parse(fs.readFileSync(path.join(results, 'coverage-final.json'), 'utf8'));
+ assert.ok(coverage[sourceFile], 'Coverage must include executed project source.');
+ assert.ok(Object.values(coverage[sourceFile].s).some((count) => count > 0), 'Executed source must have covered statements.');
+ assert.ok(coverage[untestedFile], 'Coverage must include untested project source.');
+ assert.ok(Object.values(coverage[untestedFile].s).every((count) => count === 0), 'Untested project statements must remain uncovered.');
+ assert.ok(!Object.keys(coverage).some((file) => /\/(?:node_modules|config)\/|\.(?:test|stories)\./.test(file)), 'Coverage must exclude dependencies, configuration, tests, and stories.');
+
+ result = run('twatch', ['--watch=false']);
+ assert.equal(result.status, 0, result.output);
+ assert.ok(result.report.testResults.some((entry) => entry.name === testFile && entry.status === 'passed'), 'The watch wrapper must also execute native ESM.');
+
+ const passing = fs.readFileSync(testFile, 'utf8');
+ const failing = passing.replace('toBe(42)', 'toBe(0)');
+ assert.notEqual(failing, passing, 'The deliberate failure must change the fixture assertion.');
+ fs.writeFileSync(testFile, failing);
+ result = run();
+ assert.notEqual(result.status, 0, 'A failing project test must fail npm test.');
+ assert.ok(result.report.testResults.some((entry) => entry.name === testFile && entry.status === 'failed'), 'The deliberate failure must come from the discovered project test.');
+
+ fs.rmSync(component, { recursive: true, force: true });
+ result = run();
+ assert.notEqual(result.status, 0, 'An empty generated project must fail npm test.');
+ assert.match(result.output, /No tests found/, 'The empty project must fail because no tests exist.');
+ console.log('PASS Generated project Jest ESM, coverage, watch wrapper, failure propagation, and empty-test handling.');
+} finally {
+ fs.rmSync(work, { recursive: true, force: true });
+}
diff --git a/.github/scripts/lint-wrappers.test.cjs b/.github/scripts/lint-wrappers.test.cjs
new file mode 100644
index 0000000..f32f861
--- /dev/null
+++ b/.github/scripts/lint-wrappers.test.cjs
@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+
+const assert = require('node:assert/strict');
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { test } = require('node:test');
+
+const starterPackage = require('../../whisk/package.json');
+const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+
+for (const [wrapper, checks] of Object.entries({
+ lint: ['lint-js', 'lint-styles'],
+ 'lint-fix': ['lint-js', 'lint-styles'],
+ format: ['lint-fix', 'prettier-fix'],
+})) {
+ for (const failures of [[], [0], [1], [0, 1]]) {
+ test(`${wrapper} runs every check and propagates failures ${JSON.stringify(failures)}`, (t) => {
+ const cwd = fs.mkdtempSync(path.join(os.tmpdir(), 'emulsify-lint-'));
+ t.after(() => fs.rmSync(cwd, { recursive: true, force: true }));
+ const scripts = { [wrapper]: starterPackage.scripts[wrapper] };
+ fs.writeFileSync(path.join(cwd, 'check.cjs'), 'require("node:fs").appendFileSync("ran", process.argv[2] + "\\n"); process.exit(Number(process.argv[3]));\n');
+ checks.forEach((check, index) => {
+ scripts[check] = `node check.cjs ${check} ${failures.includes(index) ? 23 + index : 0}`;
+ });
+ fs.writeFileSync(path.join(cwd, 'package.json'), JSON.stringify({ scripts }));
+ const result = spawnSync(npm, ['run', wrapper], { cwd, encoding: 'utf8', timeout: 30000 });
+ assert.ifError(result.error);
+ assert.equal(result.status === 0, failures.length === 0, result.stdout + result.stderr);
+ assert.deepEqual(fs.readFileSync(path.join(cwd, 'ran'), 'utf8').trim().split('\n'), checks);
+ });
+ }
+}
diff --git a/.github/scripts/media-embed-browser.cjs b/.github/scripts/media-embed-browser.cjs
new file mode 100644
index 0000000..1b6c46b
--- /dev/null
+++ b/.github/scripts/media-embed-browser.cjs
@@ -0,0 +1,165 @@
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const { tooling } = require('./rendered-a11y.cjs');
+
+// Use local responses when activating players: verify browser behavior without
+// relying on provider availability, tracking, autoplay policies, or live videos.
+async function verifyMediaEmbeds({ themeDir, url, outputDir }) {
+ const { puppeteer } = tooling(themeDir);
+ const browser = await puppeteer.launch({ headless: true });
+ const evidence = [];
+ try {
+ for (const poster of ['neutral', 'provider']) {
+ for (const index of [0, 1]) {
+ const page = await browser.newPage();
+ const requests = [];
+ const thumbnails = [];
+ let activated = false;
+ try {
+ await page.setJavaScriptEnabled(false);
+ await page.setRequestInterception(true);
+ page.on('request', (request) => {
+ const target = new URL(request.url());
+ if (['www.youtube.com', 'www.youtube-nocookie.com', 'player.vimeo.com'].includes(target.hostname)) {
+ requests.push({ url: target.href, activated, referer: request.headers().referer });
+ return request.respond({ status: 200, contentType: 'text/html', body: 'Extra markup
', + '', + '', + '', + '', + '', + 'Not an iframe
', + ) as $html ) { + emulsify_media_smoke_assert( apply_filters( 'embed_oembed_html', $html, $fixtures['youtube']['url'], array(), 0 ) === $html, 'Malformed or compound HTML must pass through unchanged: ' . $html ); + } + + // Provider metadata is optional. A miss must return immediately and queue one + // bounded background lookup; cached failures must not queue on every render. + $options = array( 'click_to_load' => true, 'poster' => 'provider' ); + delete_transient( $metadata_key ); + wp_clear_scheduled_hook( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ); + $missing = apply_filters( 'embed_oembed_html', $vimeo_html, $canonical, array(), 0 ); + emulsify_media_smoke_assert( 0 === emulsify_media_smoke_document( (string) emulsify_media_smoke_attribute( $missing, 'srcdoc' ) )->getElementsByTagName( 'img' )->length, 'Missing Vimeo metadata must fall back to a neutral poster.' ); + emulsify_media_smoke_assert( false !== wp_next_scheduled( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ), 'Missing Vimeo metadata must schedule a background lookup.' ); + $first_cron = wp_next_scheduled( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ); + apply_filters( 'embed_oembed_html', $vimeo_html, $canonical, array(), 0 ); + emulsify_media_smoke_assert( $first_cron === wp_next_scheduled( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ), 'Repeated renders must not duplicate the metadata lookup.' ); + emulsify_media_smoke_assert( 0 === $http_requests, 'Rendering must never synchronously fetch provider metadata.' ); + wp_clear_scheduled_hook( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ); + set_transient( $metadata_key, array(), HOUR_IN_SECONDS ); + apply_filters( 'embed_oembed_html', $vimeo_html, $canonical, array(), 0 ); + emulsify_media_smoke_assert( false === wp_next_scheduled( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ), 'Negative metadata caches must prevent repeated lookup scheduling.' ); + delete_transient( $metadata_key ); + delete_transient( $backoff_key ); + $service->refresh_vimeo_poster( $canonical ); + emulsify_media_smoke_check( false === get_transient( $metadata_key ) && false !== get_transient( $backoff_key ), 'Failed metadata lookups must use a separate bounded backoff marker.' ); + $failed_requests = $http_requests; + $service->refresh_vimeo_poster( $canonical ); + emulsify_media_smoke_check( $failed_requests === $http_requests, 'A failed refresh must back off repeated provider requests.' ); + set_transient( $metadata_key, array( 'thumbnail_url' => $metadata->thumbnail_url, 'title' => 'Keep cached title' ), DAY_IN_SECONDS ); + $cached_before_refresh = get_transient( $metadata_key ); + delete_transient( $backoff_key ); + $service->refresh_vimeo_poster( $canonical ); + emulsify_media_smoke_check( $cached_before_refresh === get_transient( $metadata_key ), 'Failed refreshes must keep valid existing Vimeo metadata.' ); + delete_transient( $backoff_key ); + $successful_refresh = static function () use ( $metadata_key, $cached_before_refresh ) { + emulsify_media_smoke_check( $cached_before_refresh === get_transient( $metadata_key ), 'Cached metadata must remain available while a refresh fetch runs.' ); + return array( 'headers' => array(), 'body' => wp_json_encode( array( 'thumbnail_url' => 'https://i.vimeocdn.com/video/refreshed-fixture.jpg', 'title' => 'Refreshed fixture' ) ), 'response' => array( 'code' => 200, 'message' => 'OK' ) ); + }; + add_filter( 'pre_http_request', $successful_refresh, 1000 ); + try { + $service->refresh_vimeo_poster( $canonical ); + $refreshed = get_transient( $metadata_key ); + emulsify_media_smoke_check( is_array( $refreshed ) && 'Refreshed fixture' === ( $refreshed['title'] ?? '' ), 'A successful background refresh must replace old metadata.' ); + } finally { + remove_filter( 'pre_http_request', $successful_refresh, 1000 ); + } + + // Exercise WordPress's real content pipeline rather than only calling the + // filter: both a classic URL and a core/embed block must be transformed. + $provider_result = static function ( $result, string $url ) use ( $fixtures ) { + foreach ( $fixtures as $fixture ) { + if ( $url === $fixture['url'] ) { + return emulsify_media_smoke_markup( $fixture['source'] ); + } + } + return $result; + }; + add_filter( 'pre_oembed_result', $provider_result, 999, 2 ); + foreach ( $fixtures as $name => $fixture ) { + foreach ( array( 'classic', 'block' ) as $type ) { + $content = 'classic' === $type ? "\n" . $fixture['url'] . "\n" : 'Child override
'; + emulsify_media_smoke_assert( false !== file_put_contents( $override, $custom ), 'Unable to write the temporary child poster override.' ); + $options = array( 'click_to_load' => true, 'poster' => 'neutral' ); + $output = apply_filters( 'embed_oembed_html', emulsify_media_smoke_markup( $fixtures['youtube']['source'] ), $fixtures['youtube']['url'], array(), 0 ); + emulsify_media_smoke_assert( $custom === emulsify_media_smoke_attribute( $output, 'srcdoc' ), 'Child @templates poster overrides must replace the parent fallback.' ); + remove_filter( 'timber/twig', $clear_roundtrip, 999 ); + + // Invalidate the already-compiled child template after changing it in this + // request. A normal request starts with the project's template already saved. + $refresh_template = static function ( \Twig\Environment $environment ): \Twig\Environment { + $environment->removeCache( '@templates/partials/oembed-poster.twig' ); + return $environment; + }; + $diagnostics = 0; + $diagnostic = static function ( $function ) use ( &$diagnostics ): void { + if ( str_contains( $function, 'Embeds::filter_html' ) ) { + ++$diagnostics; + } + }; + $suppress_expected_notice = static function ( $trigger, $function ) { + return str_contains( $function, 'Embeds::filter_html' ) ? false : $trigger; + }; + add_action( 'doing_it_wrong_run', $diagnostic ); + add_filter( 'doing_it_wrong_trigger_error', $suppress_expected_notice, 999, 2 ); + emulsify_media_smoke_assert( false !== file_put_contents( $override, '{# Intentionally empty project override. #}' ), 'Unable to write the temporary empty poster override.' ); + add_filter( 'timber/twig', $refresh_template, 999 ); + $empty_rejected = false; + try { + apply_filters( 'embed_oembed_html', emulsify_media_smoke_markup( $fixtures['youtube']['source'] ), $fixtures['youtube']['url'], array(), 0 ); + } catch ( UnexpectedValueException $exception ) { + $empty_rejected = true; + } finally { + remove_filter( 'timber/twig', $refresh_template, 999 ); + file_put_contents( $override, $custom ); + } + emulsify_media_smoke_assert( $empty_rejected, 'An empty project poster must fail closed instead of silently loading a third-party player.' ); + + // An invalid child Twig document must rethrow in the debug fixture, too. + file_put_contents( $override, '{% if %}' ); + add_filter( 'timber/twig', $refresh_template, 999 ); + $syntax_rejected = false; + try { + apply_filters( 'embed_oembed_html', emulsify_media_smoke_markup( $fixtures['youtube']['source'] ), $fixtures['youtube']['url'], array(), 0 ); + } catch ( \Twig\Error\SyntaxError $exception ) { + $syntax_rejected = true; + } finally { + remove_filter( 'timber/twig', $refresh_template, 999 ); + file_put_contents( $override, $custom ); + } + emulsify_media_smoke_check( $syntax_rejected, 'Invalid child Twig must rethrow its original error in debug mode.' ); + emulsify_media_smoke_check( 2 === $diagnostics, 'Both debug poster failures must emit a WordPress diagnostic before rethrowing.' ); + remove_action( 'doing_it_wrong_run', $diagnostic ); + remove_filter( 'doing_it_wrong_trigger_error', $suppress_expected_notice, 999 ); + // Isolate missing Timber and the non-debug constant without changing the + // fixture's WP_DEBUG setting or unloading its real Timber classes. + foreach ( array( 'empty', 'error', 'missing' ) as $failure ) { + foreach ( array( '0', '1' ) as $debug ) { + $process = proc_open( array( PHP_BINARY, __DIR__ . '/media-embed-failure-smoke.php', get_template_directory() . '/includes/Media/Embeds.php', $failure, $debug ), array( 1 => array( 'pipe', 'w' ), 2 => array( 'pipe', 'w' ) ), $pipes ); + emulsify_media_smoke_assert( is_resource( $process ), 'Unable to launch isolated poster failure smoke.' ); + $failure_output = stream_get_contents( $pipes[1] ) . stream_get_contents( $pipes[2] ); + fclose( $pipes[1] ); + fclose( $pipes[2] ); + emulsify_media_smoke_check( 0 === proc_close( $process ), 'Isolated ' . $failure . ' poster behavior with WP_DEBUG=' . $debug . ': ' . trim( $failure_output ) ); + } + } + if ( ! empty( $GLOBALS['emulsify_media_regressions'] ) ) { + throw new RuntimeException( "Media regressions:\n" . implode( "\n", array_unique( $GLOBALS['emulsify_media_regressions'] ) ) ); + } + + echo "PASS media embeds: missing post IDs and no-post shortcodes, normalized public filter context, off defaults, raw parameter preservation, privacy, translated srcdoc posters with Arabic RTL and restored LTR locales, safe URLs, asynchronous metadata, classic/block filters, child overrides, and fail-closed poster errors.\n"; +} finally { + remove_filter( 'emulsify_theme_media_embed_options', $options_hook, 999 ); + remove_filter( 'gettext', $translation, 999 ); + remove_filter( 'pre_http_request', $block_http, 999 ); + if ( isset( $provider_result ) ) { + remove_filter( 'pre_oembed_result', $provider_result, 999 ); + } + $GLOBALS['post'] = $original_post; + $GLOBALS['wp_embed']->post_ID = $original_embed_post; + $GLOBALS['wp_embed']->last_url = $original_embed_url; + $GLOBALS['wp_embed']->last_attr = $original_embed_attr; + foreach ( $created_posts as $post_id ) { + wp_delete_post( $post_id, true ); + } + wp_clear_scheduled_hook( 'emulsify_theme_refresh_vimeo_poster', array( $canonical ) ); + if ( false === $original_data ) { + delete_transient( $metadata_key ); + } else { + set_transient( $metadata_key, $original_data, DAY_IN_SECONDS ); + } + if ( false === $original_backoff ) { + delete_transient( $backoff_key ); + } else { + set_transient( $backoff_key, $original_backoff, HOUR_IN_SECONDS ); + } + if ( isset( $diagnostic ) ) { + remove_action( 'doing_it_wrong_run', $diagnostic ); + remove_filter( 'doing_it_wrong_trigger_error', $suppress_expected_notice, 999 ); + } + if ( null !== $original_file ) { + file_put_contents( $override, $original_file ); + } elseif ( is_file( $override ) ) { + unlink( $override ); + } + foreach ( array_reverse( $created_dirs ) as $directory ) { + rmdir( $directory ); + } +} diff --git a/.github/scripts/missing-timber-smoke.php b/.github/scripts/missing-timber-smoke.php new file mode 100644 index 0000000..7f41331 --- /dev/null +++ b/.github/scripts/missing-timber-smoke.php @@ -0,0 +1,99 @@ +register(); +$failures = array(); +if ( 0 !== $GLOBALS['emulsify_missing_timber_hooks']['template_redirect'][1] ) { + $failures[] = 'The missing Timber handler must run before theme rendering.'; +} + +$cases = array( + 'theme HTML request' => array( array(), array(), true ), + 'unrelated query string' => array( array(), array( 'search' => 'sitemap', 'example' => 'feed' ), true ), + 'empty sitemap query' => array( array(), array( 'sitemap' => '', 'sitemap-stylesheet' => '' ), true ), + 'admin request' => array( array( 'admin' => true ), array(), false ), + 'AJAX request' => array( array( 'ajax' => true ), array(), false ), + 'JSON request' => array( array( 'json' => true ), array(), false ), + 'robots.txt request' => array( array( 'robots' => true ), array(), false ), + 'favicon.ico request' => array( array( 'favicon' => true ), array(), false ), + 'feed request' => array( array( 'feed' => true ), array(), false ), + 'trackback request' => array( array( 'trackback' => true ), array(), false ), + 'sitemap index request' => array( array(), array( 'sitemap' => 'index' ), false ), + 'sitemap provider request' => array( array(), array( 'sitemap' => 'posts', 'sitemap-subtype' => 'page' ), false ), + 'sitemap stylesheet request' => array( array(), array( 'sitemap-stylesheet' => 'sitemap' ), false ), + 'sitemap index stylesheet' => array( array(), array( 'sitemap-stylesheet' => 'index' ), false ), +); +foreach ( $cases as $label => list( $flags, $query, $should_die ) ) { + $GLOBALS['emulsify_missing_timber_flags'] = $flags; + $GLOBALS['emulsify_missing_timber_queries'] = $query; + $died = false; + try { + $handler->runtime_error(); + } catch ( RuntimeException $error ) { + $died = true; + if ( 500 !== $error->getCode() || ! str_contains( $error->getMessage(), 'composer require timber/timber' ) ) { + $failures[] = $label . ' did not show the actionable missing Timber error.'; + } + } + if ( $should_die !== $died ) { + $failures[] = $label . ( $should_die ? ' must stop HTML rendering.' : ' must remain available without Timber.' ); + } +} +if ( $failures ) { + fwrite( STDERR, implode( "\n", $failures ) . "\n" ); + exit( 1 ); +} +echo 'Missing Timber smoke checks passed (' . count( $cases ) . " request cases).\n"; diff --git a/.github/scripts/pattern-registry-smoke.php b/.github/scripts/pattern-registry-smoke.php index f85dbb1..ccc3206 100644 --- a/.github/scripts/pattern-registry-smoke.php +++ b/.github/scripts/pattern-registry-smoke.php @@ -14,6 +14,27 @@ $GLOBALS['emulsify_pattern_smoke_filters'] = array(); $GLOBALS['emulsify_pattern_smoke_patterns'] = array(); $GLOBALS['emulsify_pattern_smoke_categories'] = array(); +$GLOBALS['emulsify_pattern_smoke_registrations'] = array(); + +final class WP_Block_Patterns_Registry { + public static function get_instance(): self { + static $instance; + return $instance ??= new self(); + } + public function is_registered( string $name ): bool { + return isset( $GLOBALS['emulsify_pattern_smoke_patterns'][ $name ] ); + } +} + +final class WP_Block_Pattern_Categories_Registry { + public static function get_instance(): self { + static $instance; + return $instance ??= new self(); + } + public function is_registered( string $name ): bool { + return isset( $GLOBALS['emulsify_pattern_smoke_categories'][ $name ] ); + } +} if ( ! function_exists( 'add_action' ) ) { function add_action( string $hook, callable $callback, int $priority = 10, int $accepted_args = 1 ): bool { @@ -96,6 +117,7 @@ function get_template_directory(): string { if ( ! function_exists( 'register_block_pattern' ) ) { function register_block_pattern( string $name, array $args ): bool { $GLOBALS['emulsify_pattern_smoke_patterns'][ $name ] = $args; + $GLOBALS['emulsify_pattern_smoke_registrations'][] = 'pattern:' . $name; return true; } @@ -104,6 +126,7 @@ function register_block_pattern( string $name, array $args ): bool { if ( ! function_exists( 'register_block_pattern_category' ) ) { function register_block_pattern_category( string $name, array $args ): bool { $GLOBALS['emulsify_pattern_smoke_categories'][ $name ] = $args; + $GLOBALS['emulsify_pattern_smoke_registrations'][] = 'category:' . $name; return true; } @@ -366,6 +389,13 @@ static function ( array $args, array $data ): array { 'Pattern args filter should alter final registration args.' ); + $registrations = $GLOBALS['emulsify_pattern_smoke_registrations']; + $patterns->register_patterns(); + emulsify_pattern_smoke_assert( + $registrations === $GLOBALS['emulsify_pattern_smoke_registrations'], + 'Patterns and categories already in the native registries must not register twice.' + ); + echo "Pattern registry smoke checks passed.\n"; } catch ( Throwable $throwable ) { fwrite( STDERR, $throwable->getMessage() . "\n" ); diff --git a/.github/scripts/pr-validation.cjs b/.github/scripts/pr-validation.cjs index f9147ea..ae24809 100644 --- a/.github/scripts/pr-validation.cjs +++ b/.github/scripts/pr-validation.cjs @@ -24,6 +24,8 @@ function run(label, command, args) { run('Validate Composer metadata', 'composer', ['validate', '--no-check-publish', '--strict']); run('Validate documented npm commands', 'npm', ['run', 'docs:check-commands']); +run('Protect blocking readiness coverage', 'node', ['--test', '.github/scripts/readiness-matrix-contract.test.cjs']); +run('Protect committed release inputs and reject symlinks', 'node', ['--test', '.github/scripts/build-dist.test.cjs']); run('Install Composer dependencies for Twig smoke coverage', 'composer', [ 'install', '--no-interaction', @@ -31,19 +33,29 @@ run('Install Composer dependencies for Twig smoke coverage', 'composer', [ '--prefer-dist', ]); run('Run Bootstrap loader smoke test', 'npm', ['run', 'smoke:bootstrap-loader']); +run('Run missing Timber native-route smoke test', 'npm', ['run', 'smoke:missing-timber']); run('Run ACF Local JSON smoke test', 'npm', ['run', 'smoke:acf-json']); run('Run asset manifest smoke test', 'npm', ['run', 'smoke:asset-manifest']); run('Run Twig attribute helper smoke test', 'npm', ['run', 'smoke:attributes']); run('Run block scoped asset smoke test', 'npm', ['run', 'smoke:block-assets']); run('Run child theme generator smoke test', 'npm', ['run', 'smoke:child-theme-generator']); run('Run component locator smoke test', 'npm', ['run', 'smoke:component-locator']); +run('Run filesystem discovery failure smoke test', 'npm', ['run', 'smoke:file-discovery']); run('Run core block Twig renderer smoke test', 'npm', ['run', 'smoke:core-block-twig']); run('Run editor enhancements smoke test', 'npm', ['run', 'smoke:editor-enhancements']); run('Run editor policy smoke test', 'npm', ['run', 'smoke:editor-policy']); run('Run pattern registry smoke test', 'npm', ['run', 'smoke:patterns']); run('Run parent theme filter smoke test', 'npm', ['run', 'smoke:theme-filters']); run('Run Twig autoescape smoke test', 'npm', ['run', 'smoke:twig-autoescape']); +run('Run parent template extension smoke test', 'npm', ['run', 'smoke:template-extension']); +run('Run fallback navigation smoke test', 'npm', ['run', 'smoke:navigation']); run('Run Twig switch smoke test', 'npm', ['run', 'smoke:twig-switch']); run('Run Twig project namespace smoke test', 'npm', ['run', 'smoke:twig-project-namespace']); run('Install Whisk dependencies', 'npm', ['run', 'whisk:install']); +run('Compare PHP and JavaScript Twig helper contracts', 'npm', ['run', 'test:twig-helpers']); +run('Compare component resolution with Emulsify Core', 'npm', ['run', 'test:component-resolution']); +run('Count request-wide component discovery and verify cache lifecycle', 'npm', ['run', 'smoke:component-request-cache']); +run('Verify lint and format failure propagation', 'npm', ['run', 'test:lint-wrappers']); +run('Run generated project Jest smoke test', 'npm', ['run', 'smoke:jest-project']); +run('Run accessibility runner tests', 'npm', ['run', 'test:a11y-runner']); run('Run WordPress starter init smoke test', 'npm', ['run', 'smoke:starter-init']); diff --git a/.github/scripts/readiness-matrix-contract.cjs b/.github/scripts/readiness-matrix-contract.cjs new file mode 100644 index 0000000..f84a164 --- /dev/null +++ b/.github/scripts/readiness-matrix-contract.cjs @@ -0,0 +1,192 @@ +const assert = require('node:assert/strict'); +const yaml = require('js-yaml'); + +function validateReadinessMatrix(source, { minimumWordPress = '6.8', requiredPhpVersions = ['8.3', '8.4', '8.5'] } = {}) { + const workflow = yaml.load(source); + + function entriesFor(jobName, versionKey) { + const job = workflow.jobs?.[jobName]; + assert.ok(job, `theme-readiness.yml must keep the ${jobName} job.`); + assert.equal(job['continue-on-error'], '${{ matrix.experimental }}', `${jobName} must make only matrix.experimental legs advisory.`); + assert.ok(!job.strategy?.matrix?.exclude, `${jobName} must not exclude required readiness legs.`); + const entries = job.strategy?.matrix?.include; + assert.ok(Array.isArray(entries) && entries.length, `${jobName} must declare its readiness matrix with include.`); + const versions = new Set(); + for (const entry of entries) { + assert.equal(typeof entry[versionKey], 'string', `${jobName} must declare each ${versionKey} as a string.`); + assert.equal(typeof entry.experimental, 'boolean', `${jobName} must explicitly mark each leg's experimental status.`); + assert.ok(!versions.has(entry[versionKey]), `${jobName} must not duplicate ${entry[versionKey]} readiness legs.`); + versions.add(entry[versionKey]); + } + return { job, entries }; + } + + function requireLeg(entries, versionKey, version, experimental, jobName) { + assert.ok(entries.some((entry) => entry[versionKey] === version && entry.experimental === experimental), + `${jobName} must keep ${version} ${experimental ? 'advisory' : 'blocking'}.`); + } + + function requireCommand(job, command, jobName) { + const steps = (job.steps || []).filter((step) => step.run?.trim() === command); + assert.ok(steps.length, `${jobName} must run ${command}.`); + for (const step of steps) { + assert.ok(step['continue-on-error'] === undefined || step['continue-on-error'] === false, + `${jobName}: ${command} must not allow failures.`); + assert.equal(step.if, undefined, `${jobName}: ${command} must run on every matrix leg.`); + } + return steps; + } + + const practical = entriesFor('practical', 'php-version'); + for (const version of requiredPhpVersions) requireLeg(practical.entries, 'php-version', version, false, 'practical'); + requireCommand(practical.job, 'npm run pr:check', 'practical'); + requireCommand(practical.job, 'npm run release:check', 'practical'); + + const fixture = entriesFor('wordpress-fixture', 'wordpress-version'); + requireLeg(fixture.entries, 'wordpress-version', minimumWordPress, false, 'wordpress-fixture'); + requireLeg(fixture.entries, 'wordpress-version', 'latest', false, 'wordpress-fixture'); + requireLeg(fixture.entries, 'wordpress-version', 'nightly', true, 'wordpress-fixture'); + for (const step of requireCommand(fixture.job, 'npm run release:check', 'wordpress-fixture')) { + assert.equal(step.env?.WP_SMOKE_WORDPRESS_VERSION, '${{ matrix.wordpress-version }}', + 'WordPress fixture smoke must resolve its version from matrix.wordpress-version, not a hardcoded version.'); + assert.equal(step.env?.WP_SMOKE_REQUIRED, '1', 'WordPress fixture matrix must fail when smoke prerequisites are missing.'); + assert.equal(step.env?.WP_SMOKE_A11Y, '1', 'WordPress fixture matrix must audit rendered accessibility.'); + const env = { ...workflow.env, ...fixture.job.env, ...step.env }; + assert.notEqual(String(env.WP_SMOKE_SKIP), '1', 'WordPress fixture matrix must not skip its smoke test.'); + } + return { practical: practical.entries, wordpress: fixture.entries }; +} + +const extendedConditions = { + 'wordpress-fixture': "inputs.release || (github.event_name == 'pull_request' && (github.base_ref == 'main' || github.base_ref == 'release-2.x')) || github.event_name == 'push' || github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.wordpress_fixture)", + 'extended-whisk': "inputs.release || (github.event_name == 'pull_request' && (github.base_ref == 'main' || github.base_ref == 'release-2.x')) || github.event_name == 'push' || github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.extended_checks)", +}; + +function requireBlockingRun(job, command, label) { + const step = job.steps?.find((entry) => entry.run?.trim() === command); + assert.ok(step, `${label} must run ${command}.`); + assert.equal(step.if, undefined, `${label}: ${command} must not be conditional.`); + assert.ok(step['continue-on-error'] === undefined || step['continue-on-error'] === false, + `${label}: ${command} must not allow failures.`); + return step; +} + +function validateReleaseWorkflow(releaseSource, readinessSource) { + const release = yaml.load(releaseSource); + const readiness = yaml.load(readinessSource); + validateReadinessMatrix(readinessSource); + + assert.equal(readiness.on?.workflow_call?.inputs?.release?.type, 'boolean', 'Full readiness must be callable with a release input.'); + assert.equal(readiness.permissions?.contents, 'read', 'Readiness credentials must remain read-only.'); + assert.equal(readiness.concurrency?.group, 'theme-readiness-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }}', 'Reusable release readiness must not share a concurrency group with standalone runs.'); + const gate = release.jobs?.['release-readiness']; + const publisher = release.jobs?.['semantic-release']; + const state = release.jobs?.['release-state']; + assert.ok(gate && publisher && state, 'Release must keep publication state, full readiness and publishing jobs.'); + assert.equal(gate.uses, './.github/workflows/theme-readiness.yml', 'Release must reuse the full readiness workflow.'); + assert.equal(gate.with?.release, true, 'Release must force all reusable readiness jobs.'); + assert.equal(gate.needs, 'release-state', 'Full readiness must follow the publication recovery check.'); + assert.equal(publisher.needs, 'release-readiness', 'Publishing must wait for full readiness success.'); + for (const [name, job] of Object.entries(release.jobs)) { + assert.equal(job.if, undefined, `${name} must use the default success dependency condition.`); + assert.ok(job['continue-on-error'] === undefined || job['continue-on-error'] === false, `${name} must not allow failures.`); + if (!job.uses) assert.ok(Number.isInteger(job['timeout-minutes']) && job['timeout-minutes'] > 0 && job['timeout-minutes'] <= 30, `${name} must have a bounded timeout.`); + } + assert.equal(release.permissions?.contents, 'read', 'Release workflow credentials must default to read-only.'); + assert.equal(state.permissions?.contents, 'read', 'Publication recovery must use read-only credentials.'); + requireBlockingRun(state, 'node .github/scripts/semantic-release.cjs --check-publication', 'Publication recovery'); + for (const [name, job] of Object.entries(readiness.jobs)) { + assert.ok(Number.isInteger(job['timeout-minutes']) && job['timeout-minutes'] > 0 && job['timeout-minutes'] <= 30, `${name} must have a bounded timeout.`); + if (extendedConditions[name]) { + assert.equal(job.if?.replace(/\s+/g, ' ').trim(), extendedConditions[name], `${name} must run for every reusable release invocation.`); + } else { + assert.equal(job.if, undefined, `${name} must not skip required readiness.`); + } + } + const lint = readiness.jobs['php-lint']; + const whisk = readiness.jobs['extended-whisk']; + assert.ok(lint && whisk, 'Release readiness must include PHP analysis and Whisk checks.'); + for (const [name, job] of [['php-lint', lint], ['extended-whisk', whisk]]) { + assert.ok(job['continue-on-error'] === undefined || job['continue-on-error'] === false, `${name} must not allow failures.`); + } + requireBlockingRun(lint, 'npm run lint:php', 'PHP analysis'); + requireBlockingRun(readiness.jobs.practical, 'npm run test:generated-theme', 'Practical readiness'); + assert.equal(requireBlockingRun(readiness.jobs.practical, 'npm run smoke:generation-parity', 'Practical readiness').env?.EMULSIFY_PARITY_REQUIRED, '1', 'Generation parity must not skip missing prerequisites.'); + requireBlockingRun(whisk, 'npm --prefix whisk run test -- --runInBand', 'Whisk readiness'); + requireBlockingRun(whisk, 'npm --prefix whisk run a11y', 'Whisk readiness'); + + const bundleName = 'emulsify-tested-${{ github.sha }}'; + const practical = readiness.jobs.practical; + const fixture = readiness.jobs['wordpress-fixture']; + assert.equal(fixture.needs, 'practical', 'WordPress fixtures must wait for the built archive.'); + const build = practical.steps.find((step) => step.run === 'npm run build:dist'); + const checksum = practical.steps.find((step) => step.run === 'sha256sum emulsify.zip > emulsify.zip.sha256'); + const upload = practical.steps.find((step) => step.name === 'Upload tested release bundle'); + for (const step of [build, checksum, upload]) { + assert.ok(step, 'Practical readiness must build and checksum the tested release bundle.'); + assert.equal(step.if, "matrix.php-version == '8.3'", 'Only the blocking baseline PHP lane must supply the release bundle.'); + assert.ok(step['continue-on-error'] === undefined || step['continue-on-error'] === false, 'The tested archive must not allow failures.'); + } + assert.equal(checksum['working-directory'], 'dist-artifact', 'Checksum must name the release ZIP.'); + assert.match(upload.uses, /^actions\/upload-artifact@[a-f0-9]{40}$/, 'Release bundle uploads must be pinned.'); + assert.equal(upload.with?.name, bundleName, 'Release bundle must be bound to this commit.'); + assert.equal(upload.with?.path?.trim(), 'dist-artifact/emulsify.zip\ndist-artifact/emulsify.zip.sha256', 'Bundle must contain the tested ZIP and checksum.'); + assert.equal(upload.with?.['if-no-files-found'], 'error', 'Missing release files must fail readiness.'); + assert.ok(practical.steps.indexOf(build) < practical.steps.indexOf(checksum) && practical.steps.indexOf(checksum) < practical.steps.indexOf(upload), 'Build, checksum and upload must run in order.'); + + function requireTestedArchive(job, name) { + const download = job.steps.find((step) => step.name === 'Download tested release bundle'); + assert.ok(download, `${name} must download the tested ZIP.`); + assert.match(download.uses, /^actions\/download-artifact@[a-f0-9]{40}$/, 'Artifact downloads must be pinned.'); + assert.equal(download.with?.name, bundleName, `${name} must use this commit's tested ZIP.`); + assert.equal(download.with?.path, 'dist-artifact', 'Downloaded ZIP must retain its release path.'); + assert.equal(download.with?.['digest-mismatch'], 'error', 'Artifact digest mismatches must fail.'); + assert.equal(download.if, undefined, 'Tested archive download must not be conditional.'); + assert.ok(download['continue-on-error'] === undefined || download['continue-on-error'] === false, 'Tested archive downloads must not allow failures.'); + const verify = requireBlockingRun(job, 'sha256sum --check emulsify.zip.sha256', name); + assert.equal(verify['working-directory'], 'dist-artifact', 'Archive checksum must be verified in its output directory.'); + assert.ok(job.steps.indexOf(download) < job.steps.indexOf(verify), 'Archive must be downloaded before verification.'); + assert.ok(!job.steps.some((step) => /build:dist/.test(step.run || '')), `${name} must reuse the tested ZIP without rebuilding.`); + if (name === 'Publishing') assert.ok(!job.steps.some((step) => /\bcomposer\b/.test(step.run || '') || step.uses?.startsWith('shivammathur/setup-php@')), 'Publishing must not configure PHP or Composer with release credentials.'); + return verify; + } + const fixtureVerify = requireTestedArchive(fixture, 'WordPress fixtures'); + const fixtureRun = requireBlockingRun(fixture, 'npm run release:check', 'WordPress fixtures'); + assert.ok(fixture.steps.indexOf(fixtureVerify) < fixture.steps.indexOf(fixtureRun), 'WordPress must test the verified ZIP.'); + const publishVerify = requireTestedArchive(publisher, 'Publishing'); + const dryRun = requireBlockingRun(publisher, 'npm run publish-test -- --no-ci', 'Publishing'); + const publish = requireBlockingRun(publisher, 'npm run publish', 'Publishing'); + requireBlockingRun(publisher, 'npm ci --ignore-scripts', 'Publishing'); + assert.ok(publisher.steps.indexOf(publishVerify) < publisher.steps.indexOf(dryRun) && publisher.steps.indexOf(dryRun) < publisher.steps.indexOf(publish), 'Verified ZIP and dry run must precede publishing.'); + assert.equal(publisher.permissions?.contents, 'write', 'Only publishing needs repository write permission.'); + for (const scope of [release.env, publisher.env, state.env]) { + for (const key of ['GITHUB_TOKEN', 'GH_TOKEN', 'COMPOSER_AUTH', 'NODE_AUTH_TOKEN']) assert.equal(scope?.[key], undefined, 'Release credentials must be scoped to their command.'); + } + for (const job of [publisher, state, ...Object.values(readiness.jobs)]) { + const checkout = job.steps?.find((step) => step.uses?.startsWith('actions/checkout@')); + assert.equal(checkout?.with?.['persist-credentials'], false, 'Checkouts must not persist credentials for dependency or build commands.'); + } + for (const step of publisher.steps) { + for (const key of ['GITHUB_TOKEN', 'GH_TOKEN', 'COMPOSER_AUTH', 'NODE_AUTH_TOKEN']) { + if (step !== dryRun && step !== publish) assert.equal(step.env?.[key], undefined, 'Dependency and build steps must not receive release credentials.'); + } + } + assert.equal(dryRun.env?.GITHUB_TOKEN, '${{ secrets.GITHUB_TOKEN }}', 'The dry run needs its scoped push-permission check.'); + assert.equal(publish.env?.GITHUB_TOKEN, '${{ secrets.GITHUB_TOKEN }}', 'Publishing needs its scoped GitHub token.'); + + for (const name of ['practical', 'wordpress-fixture']) requireBlockingRun(readiness.jobs[name], 'composer audit --locked --no-dev', name); + const whiskInstall = requireBlockingRun(whisk, 'npm run whisk:install -- --package-lock=true', 'Whisk readiness'); + const whiskAudit = whisk.steps.find((step) => step.run === 'npm --prefix whisk audit'); + assert.ok(whiskAudit && whiskAudit['continue-on-error'] === true && whiskAudit.if === undefined, 'Whisk audit must log findings without blocking frontend checks.'); + assert.ok(whisk.steps.indexOf(whiskInstall) < whisk.steps.indexOf(whiskAudit), 'Whisk audit requires the lock emitted by its dependency install.'); + return { release, readiness }; +} + +function validateProjectsWorkflow(source) { + const workflow = yaml.load(source); + assert.equal(workflow.jobs?.['add-to-project']?.if?.replace(/\s+/g, ' ').trim(), + "github.event_name != 'pull_request' || (github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.user.login != 'dependabot[bot]')", + 'Project token must not be requested for fork or Dependabot pull requests.'); +} + +module.exports = { validateReadinessMatrix, validateReleaseWorkflow, validateProjectsWorkflow }; diff --git a/.github/scripts/readiness-matrix-contract.test.cjs b/.github/scripts/readiness-matrix-contract.test.cjs new file mode 100644 index 0000000..5cbfa5e --- /dev/null +++ b/.github/scripts/readiness-matrix-contract.test.cjs @@ -0,0 +1,257 @@ +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const test = require('node:test'); +const yaml = require('js-yaml'); +const { validateReadinessMatrix, validateReleaseWorkflow, validateProjectsWorkflow } = require('./readiness-matrix-contract.cjs'); + +function fixture() { + return { + jobs: { + practical: { + strategy: { matrix: { include: [ + { 'php-version': '8.3', experimental: false }, + { 'php-version': '8.4', experimental: false }, + { 'php-version': '8.5', experimental: false }, + ] } }, + 'continue-on-error': '${{ matrix.experimental }}', + steps: [{ run: 'npm run pr:check' }, { run: 'npm run release:check' }], + }, + 'wordpress-fixture': { + strategy: { matrix: { include: [ + { 'wordpress-version': '6.8', experimental: false }, + { 'wordpress-version': 'latest', experimental: false }, + { 'wordpress-version': 'nightly', experimental: true }, + ] } }, + 'continue-on-error': '${{ matrix.experimental }}', + steps: [{ + run: 'npm run release:check', + env: { WP_SMOKE_WORDPRESS_VERSION: '${{ matrix.wordpress-version }}', WP_SMOKE_REQUIRED: '1', WP_SMOKE_A11Y: '1' }, + }], + }, + }, + }; +} + +function validate(workflow = fixture(), options) { + return validateReadinessMatrix(yaml.dump(workflow), options); +} + +test('accepts minimum and current stable blocking, with an advisory preview', () => { + assert.equal(validate().wordpress.length, 3); +}); + +test('validates the committed workflow and declared theme minimum', () => { + const repoRoot = path.resolve(__dirname, '../..'); + const workflow = fs.readFileSync(path.join(repoRoot, '.github/workflows/theme-readiness.yml'), 'utf8'); + const minimumWordPress = fs.readFileSync(path.join(repoRoot, 'style.css'), 'utf8').match(/Requires at least:\s*(\S+)/)[1]; + validateReadinessMatrix(workflow, { minimumWordPress }); +}); + +test('rejects removed or advisory minimum, latest, and baseline PHP legs', () => { + for (const [jobName, versionKey, version] of [ + ['wordpress-fixture', 'wordpress-version', '6.8'], + ['wordpress-fixture', 'wordpress-version', 'latest'], + ['practical', 'php-version', '8.3'], + ['practical', 'php-version', '8.4'], + ['practical', 'php-version', '8.5'], + ]) { + for (const remove of [false, true]) { + const workflow = fixture(); + const entries = workflow.jobs[jobName].strategy.matrix.include; + if (remove) entries.splice(entries.findIndex((entry) => entry[versionKey] === version), 1); + else entries.find((entry) => entry[versionKey] === version).experimental = true; + assert.throws(() => validate(workflow), /must keep .* blocking/); + } + } +}); + +test('requires the nightly preview to remain advisory', () => { + const workflow = fixture(); + workflow.jobs['wordpress-fixture'].strategy.matrix.include[2].experimental = false; + assert.throws(() => validate(workflow), /must keep nightly advisory/); +}); + +test('rejects job-wide failure bypasses and matrix exclusions', () => { + for (const jobName of ['practical', 'wordpress-fixture']) { + const bypass = fixture(); + bypass.jobs[jobName]['continue-on-error'] = true; + assert.throws(() => validate(bypass), /only matrix.experimental legs advisory/); + const excluded = fixture(); + excluded.jobs[jobName].strategy.matrix.exclude = [{ experimental: false }]; + assert.throws(() => validate(excluded), /must not exclude/); + } +}); + +test('rejects string experimental flags, numeric versions, and duplicate legs', () => { + const flag = fixture(); + flag.jobs.practical.strategy.matrix.include[0].experimental = 'false'; + assert.throws(() => validate(flag), /explicitly mark/); + const numeric = fixture(); + numeric.jobs.practical.strategy.matrix.include[0]['php-version'] = 8.3; + assert.throws(() => validate(numeric), /as a string/); + const duplicate = fixture(); + duplicate.jobs.practical.strategy.matrix.include.push({ 'php-version': '8.3', experimental: true }); + assert.throws(() => validate(duplicate), /must not duplicate/); +}); + +test('rejects missing, conditional, skipped, or failure-tolerant readiness commands', () => { + for (const jobName of ['practical', 'wordpress-fixture']) { + for (const mutation of ['remove', 'if', 'continue-on-error', 'skip-smoke']) { + const workflow = fixture(); + const step = workflow.jobs[jobName].steps.find((entry) => entry.run === 'npm run release:check'); + if (mutation === 'remove') workflow.jobs[jobName].steps = []; + else if (mutation === 'skip-smoke') step.run += ' -- --skip-smoke'; + else step[mutation] = true; + assert.throws(() => validate(workflow), /must (run|not allow failures)/); + } + } +}); + +test('rejects hardcoded fixture versions or disabled fixture checks', () => { + for (const [key, value] of [['WP_SMOKE_WORDPRESS_VERSION', '6.8'], ['WP_SMOKE_REQUIRED', '0'], ['WP_SMOKE_A11Y', '0'], ['WP_SMOKE_SKIP', '1']]) { + const workflow = fixture(); + workflow.jobs['wordpress-fixture'].steps[0].env[key] = value; + assert.throws(() => validate(workflow), /WordPress fixture/); + } + for (const scope of ['workflow', 'job']) { + const workflow = fixture(); + (scope === 'workflow' ? workflow : workflow.jobs['wordpress-fixture']).env = { WP_SMOKE_SKIP: '1' }; + assert.throws(() => validate(workflow), /must not skip/); + } +}); + +test('keeps the validated PHP 8.5 lane blocking', () => { + const workflow = fixture(); + workflow.jobs.practical.strategy.matrix.include[2].experimental = true; + assert.throws(() => validate(workflow), /must keep 8.5 blocking/); +}); + +function releaseFixture() { + const repoRoot = path.resolve(__dirname, '../..'); + return { + release: yaml.load(fs.readFileSync(path.join(repoRoot, '.github/workflows/semantic-release.yml'), 'utf8')), + readiness: yaml.load(fs.readFileSync(path.join(repoRoot, '.github/workflows/theme-readiness.yml'), 'utf8')), + }; +} + +function validateRelease({ release, readiness } = releaseFixture()) { + return validateReleaseWorkflow(yaml.dump(release), yaml.dump(readiness)); +} + +test('release publishing waits for the complete callable readiness workflow', () => { + validateRelease(); +}); + +test('rejects bypassed reusable readiness or publish dependencies', () => { + for (const mutation of [ + ({ release }) => { delete release.jobs['release-readiness']; }, + ({ release }) => { release.jobs['release-readiness'].uses = './.github/workflows/other.yml'; }, + ({ release }) => { release.jobs['release-readiness'].with.release = false; }, + ({ release }) => { release.jobs['semantic-release'].needs = []; }, + ({ release }) => { release.jobs['release-readiness'].if = 'always()'; }, + ({ release }) => { release.jobs['semantic-release'].if = 'always()'; }, + ({ release }) => { release.jobs['release-readiness']['continue-on-error'] = true; }, + ({ readiness }) => { delete readiness.on.workflow_call; }, + ({ readiness }) => { readiness.concurrency.group = 'theme-readiness-${{ github.ref }}'; }, + ({ readiness }) => { readiness.jobs['wordpress-fixture'].if = 'always()'; }, + ({ readiness }) => { readiness.jobs['extended-whisk'].if = 'false'; }, + ({ readiness }) => { readiness.jobs['php-lint']['continue-on-error'] = true; }, + ({ readiness }) => { readiness.jobs.practical.if = 'false'; }, + ]) { + const workflow = releaseFixture(); + mutation(workflow); + assert.throws(() => validateRelease(workflow)); + } +}); + +test('rejects skipped required fixture, PHP, parity and Whisk release gates', () => { + for (const [jobName, command] of [ + ['wordpress-fixture', 'npm run release:check'], + ['php-lint', 'npm run lint:php'], + ['practical', 'npm run smoke:generation-parity'], + ['practical', 'npm run pr:check'], + ['extended-whisk', 'npm --prefix whisk run test -- --runInBand'], + ['extended-whisk', 'npm --prefix whisk run a11y'], + ]) { + for (const bypass of ['remove', 'if', 'continue-on-error', 'skip-smoke']) { + const workflow = releaseFixture(); + const job = workflow.readiness.jobs[jobName]; + const step = job.steps.find((entry) => entry.run === command); + if (bypass === 'remove') job.steps.splice(job.steps.indexOf(step), 1); + else if (bypass === 'skip-smoke') step.run += ' -- --skip-smoke'; + else step[bypass] = true; + assert.throws(() => validateRelease(workflow)); + } + } + for (const envKey of ['WP_SMOKE_REQUIRED', 'WP_SMOKE_A11Y']) { + const workflow = releaseFixture(); + const step = workflow.readiness.jobs['wordpress-fixture'].steps.find((entry) => entry.run === 'npm run release:check'); + delete step.env[envKey]; + assert.throws(() => validateRelease(workflow)); + } +}); + +test('rejects release credential persistence and rebuilding instead of reusing the tested ZIP', () => { + for (const mutation of [ + ({ release }) => { release.jobs['semantic-release'].steps.find((step) => step.name === 'Checkout').with['persist-credentials'] = true; }, + ({ release }) => { release.jobs['semantic-release'].steps.push({ run: 'npm run build:dist' }); }, + ({ release }) => { release.jobs['semantic-release'].env = { GITHUB_TOKEN: '${{ secrets.GITHUB_TOKEN }}' }; }, + ({ release }) => { delete release.jobs['semantic-release']['timeout-minutes']; }, + ({ release }) => { release.jobs['semantic-release'].steps.find((step) => step.name === 'Verify tested archive checksum').run = 'true'; }, + ({ release }) => { release.jobs['semantic-release'].steps.find((step) => step.name === 'Download tested release bundle').with.name = 'untested'; }, + ({ readiness }) => { readiness.jobs['wordpress-fixture'].needs = []; }, + ({ readiness }) => { readiness.jobs['wordpress-fixture'].steps.find((step) => step.name === 'Download tested release bundle').with.name = 'untested'; }, + ({ readiness }) => { delete readiness.jobs.practical['timeout-minutes']; }, + ]) { + const workflow = releaseFixture(); + mutation(workflow); + assert.throws(() => validateRelease(workflow)); + } +}); + +test('project integration skips fork and Dependabot pull requests without skipping issues or manual runs', () => { + const repoRoot = path.resolve(__dirname, '../..'); + const workflow = yaml.load(fs.readFileSync(path.join(repoRoot, '.github/workflows/addtoprojects.yml'), 'utf8')); + validateProjectsWorkflow(yaml.dump(workflow)); + for (const condition of [undefined, 'true', "github.actor != 'dependabot[bot]'"]) { + workflow.jobs['add-to-project'].if = condition; + assert.throws(() => validateProjectsWorkflow(yaml.dump(workflow))); + } +}); + +test('rejects missing or failure-tolerant shipped Composer audit and unlogged Whisk audit', () => { + for (const jobName of ['practical', 'wordpress-fixture']) { + for (const bypass of ['remove', 'continue-on-error']) { + const workflow = releaseFixture(); + const job = workflow.readiness.jobs[jobName]; + const step = job.steps.find((entry) => entry.run === 'composer audit --locked --no-dev'); + if (bypass === 'remove') job.steps.splice(job.steps.indexOf(step), 1); + else step[bypass] = true; + assert.throws(() => validateRelease(workflow)); + } + } + const workflow = releaseFixture(); + workflow.readiness.jobs['extended-whisk'].steps = workflow.readiness.jobs['extended-whisk'].steps.filter((step) => step.name !== 'Audit Whisk dependencies'); + assert.throws(() => validateRelease(workflow)); +}); + +test('Whisk audit uses the lock emitted by its existing dependency install', () => { + const job = releaseFixture().readiness.jobs['extended-whisk']; + assert.equal(job.steps.find((step) => step.name === 'Install Whisk dependencies').run, + 'npm run whisk:install -- --package-lock=true'); + assert.ok(!job.steps.some((step) => step.run?.includes('--package-lock-only')), + 'An informational audit must not add a separate dependency-resolution gate.'); +}); + +test('rejects Whisk audit without an installed lock or before its dependency install', () => { + const noLock = releaseFixture(); + noLock.readiness.jobs['extended-whisk'].steps.find((step) => step.name === 'Install Whisk dependencies').run = 'npm run whisk:install'; + assert.throws(() => validateRelease(noLock)); + + const reordered = releaseFixture(); + const steps = reordered.readiness.jobs['extended-whisk'].steps; + const auditIndex = steps.findIndex((step) => step.name === 'Audit Whisk dependencies'); + steps.unshift(...steps.splice(auditIndex, 1)); + assert.throws(() => validateRelease(reordered)); +}); diff --git a/.github/scripts/release-check.cjs b/.github/scripts/release-check.cjs index 4cf3b52..9156540 100644 --- a/.github/scripts/release-check.cjs +++ b/.github/scripts/release-check.cjs @@ -7,8 +7,13 @@ const fs = require('fs'); const path = require('path'); const childProcess = require('child_process'); +const yaml = require('js-yaml'); +const { validateReleaseVersionContract } = require('./release-version-contract.cjs'); +const { validateReadinessMatrix, validateReleaseWorkflow, validateProjectsWorkflow } = require('./readiness-matrix-contract.cjs'); +const { validateThemeJsonStyles } = require('./theme-json-style-contract.cjs'); const repoRoot = path.resolve(__dirname, '../..'); +const skipSmoke = process.argv.slice(2).includes('--skip-smoke'); const results = []; function addResult(status, name, detail) { @@ -33,6 +38,16 @@ function semver(value) { return /^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/.test(String(value)); } +function wordpressVersionAtLeast(version, minimum) { + const actualParts = version.split('.').map(Number); + const minimumParts = minimum.split('.').map(Number); + for (let index = 0; index < Math.max(actualParts.length, minimumParts.length); index += 1) { + const difference = (actualParts[index] || 0) - (minimumParts[index] || 0); + if (difference !== 0) return difference > 0; + } + return true; +} + function runStaticCheck(name, callback) { // Static checks intentionally inspect files as text. They catch packaging and // documentation regressions without needing a full WordPress install. @@ -46,8 +61,8 @@ function runStaticCheck(name, callback) { } function runCommandCheck(name, command, args) { - // Command checks are reserved for smoke paths that already know how to skip - // when local prerequisites such as WP-CLI or MySQL are absent. + // Focused contract tests always run. Runtime smoke commands can also report + // missing local prerequisites such as WP-CLI or MySQL as an explicit skip. const result = childProcess.spawnSync(command, args, { cwd: repoRoot, encoding: 'utf8', @@ -299,33 +314,21 @@ function runStaticChecks() { const license = readFile('LICENSE'); const issueTemplate = readFile('.github/ISSUE_TEMPLATE.md'); const pullRequestTemplate = readFile('.github/PULL_REQUEST_TEMPLATE.md'); - const releaseGuardRejectContext = { - branch: { name: 'main' }, - lastRelease: { version: '1.0.0' }, - nextRelease: { version: '1.1.0' }, - }; - const releaseGuardAcceptContext = { - branch: { name: 'main' }, - lastRelease: { version: '1.0.0' }, - nextRelease: { version: '2.0.0' }, - }; - const releaseGuardFutureContext = { - branch: { name: 'main' }, - lastRelease: { version: '2.0.0' }, - nextRelease: { version: '2.0.1' }, - }; - const releaseAnalyzerAlphaContext = { - branch: { name: 'main' }, - lastRelease: { version: '1.0.0-alpha.5' }, - }; - const releaseAnalyzerNoStableContext = { - branch: { name: 'main' }, - lastRelease: {}, - }; - runStaticCheck('Required files', () => { const requiredFiles = [ '.github/scripts/release-check.cjs', + '.github/scripts/release-version-contract.cjs', + '.github/scripts/release-version-contract.test.cjs', + '.github/scripts/readiness-matrix-contract.cjs', + '.github/scripts/readiness-matrix-contract.test.cjs', + '.github/scripts/theme-json-style-contract.cjs', + '.github/scripts/theme-json-style-contract.test.cjs', + '.github/scripts/semantic-release.test.cjs', + '.github/scripts/fallback-navigation-smoke.php', + '.github/scripts/rendered-a11y.cjs', + '.github/scripts/rendered-a11y.test.cjs', + '.github/scripts/media-embed-smoke.php', + '.github/scripts/media-embed-browser.cjs', '.github/scripts/docs-command-check.cjs', '.github/scripts/pr-validation.cjs', '.github/scripts/semantic-release.cjs', @@ -336,10 +339,12 @@ function runStaticChecks() { '.github/workflows/theme-readiness.yml', '.gitignore', '.nvmrc', + 'AGENTS.md', 'README.md', 'UPGRADE.md', 'docs/README.md', 'docs/acf-local-json.md', + 'docs/accessibility.md', 'docs/acf-twig-blocks.md', 'docs/asset-loading.md', 'docs/block-patterns.md', @@ -402,9 +407,15 @@ function runStaticChecks() { 'templates/search.twig', 'templates/single-password.twig', 'templates/single.twig', + 'docs/template-extension.md', + '.github/scripts/template-extension-smoke.php', + '.github/fixtures/template-extension/README.md', '.github/scripts/acf-local-json-smoke.php', '.github/scripts/asset-manifest-smoke.php', '.github/scripts/attribute-helper-smoke.php', + '.github/scripts/twig-helper-contract.cjs', + '.github/scripts/twig-helper-contract.php', + '.github/fixtures/twig-helper-contract.json', '.github/scripts/block-scoped-assets-smoke.php', '.github/scripts/bootstrap-loader-smoke.php', '.github/scripts/child-theme-generator-smoke.php', @@ -413,6 +424,9 @@ function runStaticChecks() { '.github/scripts/editor-policy-smoke.php', '.github/scripts/pattern-registry-smoke.php', '.github/scripts/wordpress-starter-init-smoke.cjs', + '.github/scripts/lint-wrappers.test.cjs', + '.github/scripts/jest-project-smoke.cjs', + '.github/scripts/a11y-runner.test.cjs', '.github/scripts/theme-filters-smoke.php', '.github/scripts/twig-autoescape-smoke.php', '.github/scripts/twig-project-namespace-smoke.php', @@ -421,6 +435,9 @@ function runStaticChecks() { 'whisk/.cli/init.js', 'whisk/.gitignore', 'whisk/.nvmrc', + 'whisk/AGENTS.md', + 'whisk/docs/wordpress-integration.md', + 'whisk/.agents/skills/emulsify-wordpress-integration/SKILL.md', 'whisk/config/emulsify-core/a11y.config.js', 'whisk/config/emulsify-core/run-a11y.js', 'whisk/config/jest.config.js', @@ -431,17 +448,23 @@ function runStaticChecks() { 'whisk/config/acf-json/.gitkeep', 'whisk/patterns/.gitkeep', 'whisk/src/components/.gitkeep', - 'whisk/templates/page.twig', ]; const missingFiles = requiredFiles.filter((file) => !fs.existsSync(path.join(repoRoot, file))); ensure(missingFiles.length === 0, `Missing required files: ${missingFiles.join(', ')}.`); return `Found ${requiredFiles.length} required release files.`; }); + runStaticCheck('Release version contract', () => { + const { errors, packageVersion, latestStableTag, releasePrepared } = validateReleaseVersionContract({ repoRoot }); + ensure(errors.length === 0, errors.join('\n')); + return releasePrepared + ? `Prepared version ${packageVersion} follows latest stable tag ${latestStableTag}.` + : `Package version ${packageVersion} matches latest stable tag ${latestStableTag}; no release is prepared.`; + }); + runStaticCheck('Root release metadata', () => { ensure(rootPackage.name === 'emulsify-wordpress', 'package.json name should be emulsify-wordpress.'); ensure(semver(rootPackage.version), 'package.json version must be a valid semver string.'); - ensure(rootPackage.version === releaseConfig.expectedStableRelease, `package.json version should prepare the ${releaseConfig.expectedStableRelease} release.`); ensure(rootPackage.description, 'package.json description is required.'); ensureParentThemeLanguage('package.json description', rootPackage.description); ensureNoTitleCaseBuildPhrase('package.json description', rootPackage.description); @@ -452,6 +475,9 @@ function runStaticChecks() { ensure(rootPackage.scripts['pr:check'] === 'node .github/scripts/pr-validation.cjs', 'package.json should expose npm run pr:check.'); ensure(rootPackage.scripts['release:check'] === 'node .github/scripts/release-check.cjs', 'package.json should expose npm run release:check.'); ensure(rootPackage.scripts['docs:check-commands'] === 'node .github/scripts/docs-command-check.cjs', 'package.json should expose npm run docs:check-commands.'); + ensure(rootPackage.scripts['test:lint-wrappers'] === 'node --test .github/scripts/lint-wrappers.test.cjs', 'package.json should expose the lint wrapper regression tests.'); + ensure(rootPackage.scripts['smoke:jest-project'] === 'node .github/scripts/jest-project-smoke.cjs', 'package.json should expose generated project ESM/coverage smoke coverage.'); + ensure(rootPackage.scripts['test:a11y-runner'] === 'node --test .github/scripts/a11y-runner.test.cjs', 'package.json should expose the Core accessibility wrapper tests.'); ensure(rootPackage.scripts['build:dist'] === 'bash scripts/build-dist.sh', 'package.json should expose npm run build:dist.'); ensure(rootPackage.scripts['lint:php'].includes('vendor/bin/phpcs -q'), 'package.json lint:php should run PHPCS.'); ensure(rootPackage.scripts['lint:php'].includes('vendor/bin/phpstan analyse --no-progress'), 'package.json lint:php should run PHPStan.'); @@ -470,6 +496,7 @@ function runStaticChecks() { ensure(rootPackage.scripts['smoke:theme-filters'] === 'php .github/scripts/theme-filters-smoke.php', 'package.json should expose npm run smoke:theme-filters.'); ensure(rootPackage.scripts['smoke:twig-switch'] === 'php .github/scripts/twig-switch-smoke.php', 'package.json should expose npm run smoke:twig-switch.'); ensure(rootPackage.scripts['smoke:twig-project-namespace'] === 'php .github/scripts/twig-project-namespace-smoke.php', 'package.json should expose npm run smoke:twig-project-namespace.'); + ensure(rootPackage.scripts['smoke:template-extension'] === 'php .github/scripts/template-extension-smoke.php', 'package.json should expose the exact-byte template extension smoke.'); ensure(rootPackage.scripts['whisk:install'], 'package.json should expose npm run whisk:install.'); ensure(rootPackage.scripts['whisk:build'] === 'npm --prefix whisk run build', 'package.json should expose npm run whisk:build.'); ensure(!rootPackage.devDependencies['@semantic-release/changelog'], 'package.json should not declare unused @semantic-release/changelog tooling.'); @@ -503,8 +530,6 @@ function runStaticChecks() { ensure(rootThemeHeader.Version === releaseVersion, `style.css Version should match the ${releaseVersion} release line.`); ensure(rootThemeHeader.License === 'GPL-2.0-only', 'style.css License should be GPL-2.0-only.'); ensure(rootThemeHeader['License URI'] === 'https://www.gnu.org/licenses/old-licenses/gpl-2.0.html', 'style.css License URI should point to GPLv2.'); - ensure(rootThemeHeader['Requires at least'] === '6.7', 'style.css Requires at least should stay aligned to the WordPress baseline.'); - ensure(rootThemeHeader['Tested up to'] === '6.7', 'style.css Tested up to should stay aligned to the WordPress baseline.'); ensure(rootThemeHeader['Requires PHP'] === '8.3', 'style.css Requires PHP should stay aligned to the release baseline.'); ensureParentThemeLanguage('style.css Description', rootThemeHeader.Description); ensure(whiskThemeHeader['Theme Name'] === 'Whisk', 'whisk/style.css Theme Name should be Whisk.'); @@ -518,6 +543,25 @@ function runStaticChecks() { return 'Parent and Whisk WordPress theme headers are coherent with package metadata.'; }); + runStaticCheck('WordPress minimum compatibility', () => { + const minimum = rootThemeHeader['Requires at least']; + ensure(minimum === '6.8', 'style.css Requires at least must be 6.8 for this release.'); + const timberPath = 'vendor/timber/timber/src/Timber.php'; + ensure(fs.existsSync(path.join(repoRoot, timberPath)), 'Installed Timber source is required to verify its WordPress minimum; run composer install.'); + const timberMinimum = readFile(timberPath).match(/\bMINIMUM_WP_VERSION\s*=\s*['"](\d+\.\d+(?:\.\d+)?)['"]/); + ensure(timberMinimum, 'Unable to read installed Timber MINIMUM_WP_VERSION; run composer install and review Timber compatibility.'); + ensure(wordpressVersionAtLeast(minimum, timberMinimum[1]), `style.css Requires at least (${minimum}) is below installed Timber MINIMUM_WP_VERSION (${timberMinimum[1]}); raise the theme minimum before releasing.`); + return `Theme minimum ${minimum} supports installed Timber's WordPress minimum ${timberMinimum[1]}.`; + }); + + runStaticCheck('WordPress tested compatibility', () => { + const tested = rootThemeHeader['Tested up to']; + const minimum = rootThemeHeader['Requires at least']; + ensure(/^\d+\.\d+(?:\.\d+)?$/.test(tested), 'style.css Tested up to must name a stable WordPress version verified by the blocking fixture.'); + ensure(wordpressVersionAtLeast(tested, minimum), 'style.css Tested up to must not be lower than Requires at least.'); + return `Tested up to ${tested} covers theme minimum ${minimum}; the current stable WordPress fixture is blocking.`; + }); + runStaticCheck('PHP analysis scope', () => { const phpcsConfig = readFile('phpcs.xml.dist'); const phpstanConfig = readFile('phpstan.neon.dist'); @@ -562,6 +606,16 @@ function runStaticChecks() { return 'Attribute helper runtime and smoke fixture are wired.'; }); + runStaticCheck('Twig helper characterization', () => { + ensure(rootPackage.scripts['test:twig-helpers'] === 'node .github/scripts/twig-helper-contract.cjs', 'Root package should expose the PHP/JavaScript Twig helper characterization.'); + const prValidation = readFile('.github/scripts/pr-validation.cjs'); + const install = prValidation.indexOf("run('Install Whisk dependencies'"); + const compare = prValidation.indexOf("['run', 'test:twig-helpers']"); + ensure(install >= 0 && compare > install, 'PR validation must compare both helper runtimes after installing Whisk/Core.'); + ensure(docs.twig.includes('## Helper characterization'), 'Twig authoring docs must explain the characterization and recorded differences.'); + return 'The PR gate compares exact PHP and installed Core helper output against one explicit-difference corpus.'; + }); + runStaticCheck('Twig HTML autoescaping', () => { const twig = readFile('includes/Runtime/Twig.php'); const smoke = readFile('.github/scripts/twig-autoescape-smoke.php'); @@ -570,7 +624,7 @@ function runStaticChecks() { ensure(twig.includes("$options['autoescape'] = 'html'"), 'Timber integration should enable HTML autoescaping.'); ensure(smoke.includes('{{ fields.heading }}'), 'Twig autoescape smoke should render a field value.'); ensure(smoke.includes(''), 'Twig autoescape smoke should use a hostile script fixture.'); - ensure(smoke.includes("$definition['is_safe']"), 'Twig autoescape smoke should register helper safety metadata.'); + ensure(smoke.includes("$definition['options']"), 'Twig autoescape smoke should register the same helper options as Timber.'); return 'Twig HTML autoescaping is registered and covered by a behavioral smoke test.'; }); @@ -616,12 +670,12 @@ function runStaticChecks() { ensure(cli.includes("replace_theme_header( $contents, 'Theme Name'"), 'Child theme generator should update Theme Name explicitly.'); ensure(cli.includes("replace_theme_header( $contents, 'Text Domain'"), 'Child theme generator should update Text Domain explicitly.'); ensure(cli.includes("replace_theme_header( $contents, 'Template'"), 'Child theme generator should update Template explicitly.'); - ensure(cli.includes("data['project']['name']"), 'Child theme generator should update project.emulsify.json project.name.'); - ensure(cli.includes("data['project']['machineName']"), 'Child theme generator should update project.emulsify.json project.machineName.'); - ensure(cli.includes("data['project']['generatedFrom']"), 'Child theme generator should update project.emulsify.json generatedFrom.'); - ensure(cli.includes("data['project']['generatedFromVersion']"), 'Child theme generator should update project.emulsify.json generatedFromVersion.'); + ensure(/\$data->project->name\s*=\s*\$theme_label/.test(cli), 'Child theme generator should update project.emulsify.json project.name.'); + ensure(/\$data->project->machineName\s*=\s*\$machine_name/.test(cli), 'Child theme generator should update project.emulsify.json project.machineName.'); + ensure(/\$data->project->generatedFrom\s*=\s*self::GENERATED_FROM/.test(cli), 'Child theme generator should update project.emulsify.json generatedFrom.'); + ensure(/\$data->project->generatedFromVersion\s*=\s*\$version/.test(cli), 'Child theme generator should update project.emulsify.json generatedFromVersion.'); ensure(cli.includes("$this->join_path( dirname( $source ), 'style.css' ), 'Version'"), 'Child theme generator should read release lineage from installed WordPress theme metadata.'); - ensure(cli.includes("data['name'] = $machine_name"), 'Child theme generator should update package.json name.'); + ensure(/\$data->name\s*=\s*\$machine_name/.test(cli), 'Child theme generator should update package.json name.'); ensure(cli.includes('collect_pattern_updates'), 'Child theme generator should update starter pattern namespaces.'); ensure(cli.includes('sanitize_label_for_source'), 'Child theme generator should sanitize human labels before writing source comments.'); ensure(cli.includes("replace_theme_header( $contents, 'Theme Name', $source_label )"), 'Child theme generator should use a source-safe label in style.css.'); @@ -671,6 +725,7 @@ function runStaticChecks() { const locator = readFile('includes/Blocks/ComponentLocator.php'); const fileDiscovery = readFile('includes/Support/FileDiscovery.php'); const registry = readFile('includes/Blocks/Registry.php'); + const bootstrap = readFile('includes/Bootstrap.php'); const acfBlocks = readFile('includes/Blocks/AcfBlocks.php'); const nativeBlocks = readFile('includes/Blocks/NativeBlocks.php'); const smoke = readFile('.github/scripts/component-locator-smoke.php'); @@ -691,7 +746,15 @@ function runStaticChecks() { ensure(locator.includes('clear_discovery_cache') && locator.includes('delete_transient'), 'Component locator should provide a clear method for the active discovery cache key.'); ensure(locator.includes('stylesheet_version') && locator.includes('template_version') && locator.includes('manifest_file_signature'), 'Component locator cache key should include theme versions and manifest filemtime.'); ensure(locator.includes('wp_get_environment_type') && locator.includes('WP_DEBUG'), 'Component locator should keep active development uncached unless explicitly enabled.'); - ensure(registry.includes('$components = new ComponentLocator()'), 'Block registry should share one ComponentLocator instance.'); + ensure( + /\$components\s*=\s*new Blocks\\ComponentLocator\(\)/.test(bootstrap) + && bootstrap.includes('new Assets( $asset_manifest, $components )') + && bootstrap.includes('new Blocks\\Registry( $asset_manifest, $components )') + && registry.includes('$this->components = $components ?? new ComponentLocator()') + && registry.includes('new AcfBlocks( $this->components, $this->manifest )') + && registry.includes('new NativeBlocks( $this->components )'), + 'Bootstrap should share one ComponentLocator across runtime assets and ACF/Twig/native block registration.' + ); ensure(acfBlocks.includes('$this->components->acf_components()'), 'ACF/Twig block discovery should use ComponentLocator.'); ensure(!acfBlocks.includes("$args['data']['twig_template'] ="), 'ACF/Twig block registration should not persist template paths in editor block data.'); ensure( @@ -812,6 +875,7 @@ function runStaticChecks() { ensure(editorPolicySmoke.includes('Editor policy smoke checks passed'), 'Editor policy smoke should have a clear success message.'); ensure(patternSmoke.includes('Pattern registry smoke checks passed'), 'Pattern registry smoke should have a clear success message.'); ensure(fileDiscovery.includes('function theme_roots'), 'File discovery helper should create child-first theme roots.'); + ensure(fileDiscovery.includes('function filtered_theme_roots') && fileDiscovery.includes('self::theme_roots( $directory, true )') && fileDiscovery.includes('apply_filters( $hook, $roots, $directory )'), 'Asset root discovery should preserve child-first roots and service-specific directory filters.'); ensure(fileDiscovery.includes('function normalize_roots'), 'File discovery helper should normalize readable unique roots.'); ensure(fileDiscovery.includes('function file_records'), 'File discovery helper should create file records for service-specific filtering.'); ensure(fileDiscovery.includes('function recursive_files'), 'File discovery helper should support recursive scans.'); @@ -821,10 +885,10 @@ function runStaticChecks() { ensure(assetManifest.includes('dist/emulsify-assets.json'), 'Asset manifest helper should default to dist/emulsify-assets.json.'); ensure(assetManifest.includes('emulsify_theme_asset_manifest_path') && assetManifest.includes('emulsify_theme_asset_manifest_data'), 'Asset manifest helper should expose path and parsed data filters.'); ensure(assets.includes("'global'") && editorEnhancements.includes("'editor'") && assetManifest.includes("'components'") && assetManifest.includes("'blocks'"), 'Asset manifest support should cover global, editor, component, and block-specific sections.'); - ensure(assets.includes('FileDiscovery::theme_roots') && assets.includes('FileDiscovery::file_records'), 'Runtime assets should use shared filesystem discovery helpers.'); + ensure(assets.includes("FileDiscovery::filtered_theme_roots( $directory, 'emulsify_theme_asset_directories' )") && assets.includes('FileDiscovery::file_records') && assets.includes('AssetRecord::from_discovered_files'), 'Runtime assets should use shared root discovery and asset record helpers.'); ensure(assets.includes('AssetManifest') && assets.includes('manifest_asset_files') && assets.includes("enqueue_scripts( 'emulsify-global', 'dist/global' )"), 'Runtime assets should support manifest-backed global and component assets.'); - ensure(assets.includes('is_scoped_component_asset') && assets.includes('*.component.json'), 'Runtime assets should skip component files declared as block-scoped metadata.'); - ensure(editorEnhancements.includes('FileDiscovery::theme_roots') && editorEnhancements.includes('FileDiscovery::file_records'), 'Editor assets should use shared filesystem discovery helpers.'); + ensure(assets.includes('is_scoped_component_asset') && assets.includes('$this->components->component_metadata_files()') && assets.includes('metadata_asset_paths'), 'Runtime assets should skip component files declared as block-scoped metadata.'); + ensure(editorEnhancements.includes("FileDiscovery::filtered_theme_roots( $directory, 'emulsify_theme_editor_asset_directories' )") && editorEnhancements.includes('FileDiscovery::file_records') && editorEnhancements.includes('AssetRecord::from_discovered_files'), 'Editor assets should use shared root discovery and asset record helpers.'); ensure(editorEnhancements.includes('AssetManifest') && editorEnhancements.includes("asset_records( 'editor'"), 'Editor assets should support manifest-backed editor assets.'); ensure(acfBlocks.includes('scoped_asset_records') && acfBlocks.includes('enqueue_assets') && acfBlocks.includes('emulsify_theme_acf_block_asset_records'), 'ACF/Twig blocks should support metadata-driven scoped assets.'); ensure(nativeBlocks.includes("register_block_type( (string) $component['path'] )"), 'Native blocks should delegate block.json asset fields to WordPress register_block_type().'); @@ -869,8 +933,10 @@ function runStaticChecks() { ensure(fs.existsSync(path.join(repoRoot, 'whisk/.nvmrc')), 'Whisk should use .nvmrc for Node version tooling.'); ensure(!fs.existsSync(path.join(repoRoot, 'whisk/.nvm')), 'Whisk should not use the legacy .nvm filename.'); ensure(fs.existsSync(path.join(repoRoot, 'whisk/config/jest.config.js')), 'Whisk should provide the Jest config referenced by package scripts.'); - ensure(scripts.test === 'jest --coverage --passWithNoTests --config ./config/jest.config.js', 'whisk/package.json test script should point at the checked-in Jest config.'); + ensure(scripts.test === 'node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --config ./config/jest.config.js', 'whisk/package.json test should execute native project ESM and fail when no tests exist.'); + ensure(scripts.twatch === 'node --experimental-vm-modules node_modules/jest/bin/jest.js --no-coverage --watch --verbose --config ./config/jest.config.js', 'whisk/package.json twatch should use the same native ESM runner.'); ensure(jestConfig.includes("testEnvironment: 'node'"), 'whisk/config/jest.config.js should define a node test environment.'); + ensure(jestConfig.includes('transform: {}') && jestConfig.includes("coverageProvider: 'v8'") && jestConfig.includes('collectCoverageFrom'), 'Whisk Jest config should execute ESM directly and collect project coverage.'); ensure(initHook.includes('sanitizeLabelForSource'), 'Whisk init hook should sanitize human labels before writing source comments.'); ensure(initHook.includes("replaceThemeHeader(contents, 'Theme Name', sourceLabel)"), 'Whisk init hook should update style.css with a source-safe Theme Name.'); ensure(initHook.includes("replaceThemeHeader(contents, 'Text Domain', machineName)"), 'Whisk init hook should update style.css Text Domain.'); @@ -889,7 +955,7 @@ function runStaticChecks() { ensure(starterInitSmoke.includes("style.Template === 'emulsify'"), 'Starter init smoke should validate Template: emulsify.'); ensure(starterInitSmoke.includes('*/ echo 1; /*'), 'Starter init smoke should cover hostile source-comment labels.'); ensure(starterInitSmoke.includes('node_modules') && starterInitSmoke.includes('dist'), 'Starter init smoke should validate copied build and dependency output is absent.'); - ensure(starterInitSmoke.includes("['--prefix', 'whisk', 'run', 'test']"), 'Starter init smoke should verify the starter npm test script works after Whisk dependencies are installed.'); + ensure(starterInitSmoke.includes('No tests found'), 'Starter init smoke should verify an empty starter fails its npm test script.'); ensure(starterInitSmoke.includes("['run', 'inspect:components', '--', '--json']"), 'Starter init smoke should run the component inspector JSON command from the generated theme root.'); ensure(starterInitSmoke.includes('JSON.parse') && starterInitSmoke.includes('Array.isArray(report.components)'), 'Starter init smoke should validate the component inspector JSON report, including an empty components array.'); ensure(fs.existsSync(path.join(repoRoot, 'whisk/src/components/.gitkeep')), 'whisk/src/components should remain as an empty optional component placeholder.'); @@ -907,14 +973,14 @@ function runStaticChecks() { ensure(!fs.existsSync(path.join(repoRoot, 'whisk/whisk.info.yml')), 'Whisk should not add Drupal-style .info.yml metadata.'); ensure(!fs.existsSync(path.join(repoRoot, 'whisk/scripts/vite-if-inputs.mjs')), 'Whisk should not wrap Emulsify Core Vite build errors.'); ensure(whiskPackage.dependencies && whiskPackage.dependencies['@emulsify/core'], 'whisk/package.json must declare @emulsify/core.'); - // Accept any caret range on Core 4 at or above the component-inspector - // minimum, so a patch or minor Core bump does not require editing this file. + // Accept any caret range at or above Core 4.5, so a patch or minor Core + // bump does not require editing this file. const coreRange = whiskPackage.dependencies['@emulsify/core']; const coreRangeMatch = /^\^4\.(\d+)\.(\d+)$/.exec(coreRange); ensure(coreRangeMatch, `whisk/package.json should target a caret range within Emulsify Core 4; found ${coreRange}.`); ensure( - Number(coreRangeMatch[1]) > 3 || (Number(coreRangeMatch[1]) === 3 && Number(coreRangeMatch[2]) >= 0), - `whisk/package.json should target Emulsify Core ^4.3.0 or newer within Core 4; found ${coreRange}.`, + Number(coreRangeMatch[1]) >= 5, + `whisk/package.json should target Emulsify Core ^4.5.0 or newer within Core 4; found ${coreRange}.`, ); ensure(scripts['inspect:components'] === 'emulsify-inspect-components', 'whisk/package.json should expose the published Emulsify Core component inspector binary.'); ensure(!scripts['inspect:components'].includes('node_modules/'), 'whisk/package.json should not deep-link to the component inspector implementation.'); @@ -924,9 +990,10 @@ function runStaticChecks() { ensure(whiskA11yConfig.includes("storybookBuildDir: '.out'"), 'Whisk accessibility config should target the generated theme Storybook output relative to the consuming project root.'); ensure(whiskA11yConfig.includes('wait: 1000'), 'Whisk accessibility config should wait for the selected Storybook story to mount.'); ensure(whiskA11yRunner.includes('resolvePa11yStoryIds') && whiskA11yRunner.includes('storyIds.length === 0'), 'Whisk accessibility runner should discover stories and reject an empty audit.'); - ensure(whiskA11yRunner.includes('http.createServer') && whiskA11yRunner.includes('await pa11y') && whiskA11yRunner.includes('logReport'), 'Whisk accessibility runner should serve the static build over HTTP and report real Pa11y results.'); - ensure(whiskA11yRunner.includes("process.env.CI === 'true' && process.platform === 'linux'") && whiskA11yRunner.includes('pa11yOptions.chromeLaunchConfig') && whiskA11yRunner.includes("'--no-sandbox'") && whiskA11yRunner.includes("'--disable-setuid-sandbox'"), 'Whisk accessibility runner should launch Chrome without its unavailable sandbox on isolated Linux CI runners.'); - ensure(whiskA11yRunner.includes('if (hasIssues)') && whiskA11yRunner.includes('process.exitCode = 1'), 'Whisk accessibility runner should fail when Pa11y reports a non-ignored violation.'); + ensure(whiskA11yRunner.includes('resolveProjectA11yConfig') && whiskA11yRunner.includes('applyProjectA11yConfig'), 'Whisk accessibility wrapper should load the consuming project config through Core.'); + ensure(whiskA11yRunner.includes('startStorybookServer') && whiskA11yRunner.includes('lintReportAndExit') && whiskA11yRunner.includes('finally'), 'Whisk accessibility wrapper should delegate HTTP serving, bounded checks, failure reporting, and cleanup to Core.'); + ensure(!whiskA11yRunner.includes('http.createServer') && !whiskA11yRunner.includes('await pa11y'), 'Whisk should not ship a copied accessibility engine.'); + ensure(!whiskA11yRunner.includes('--no-sandbox') && !whiskA11yRunner.includes('--disable-setuid-sandbox'), 'Whisk accessibility code must keep Chrome sandboxing enabled.'); ensure(!scriptText.includes('vite-if-inputs'), 'whisk/package.json scripts should not wrap missing-input build errors.'); ensure(scripts.develop && scripts.develop.includes('npm:vite'), 'whisk/package.json develop script should run the Vite watcher.'); ensure(!scripts.webpack, 'whisk/package.json should not expose a webpack script.'); @@ -946,7 +1013,6 @@ function runStaticChecks() { const projectComponentLoader = readFile('includes/Twig/ProjectComponentLoader.php'); const twigNamespaceSmoke = readFile('.github/scripts/twig-project-namespace-smoke.php'); const childFunctions = readFile('whisk/functions.php'); - const childPageTemplate = readFile('whisk/templates/page.twig'); const parentTemplateFiles = listFilesRecursive('templates', (file) => file.endsWith('.twig')).sort(); const childTemplateFiles = listFilesRecursive('whisk/templates', (file) => file.endsWith('.twig')).sort(); const expectedParentFallbacks = [ @@ -959,26 +1025,18 @@ function runStaticChecks() { 'templates/single-password.twig', 'templates/single.twig', ]; - const unexpectedChildTemplates = childTemplateFiles.filter((file) => file !== 'whisk/templates/page.twig'); - const duplicateChildTemplates = childTemplateFiles.filter((file) => { - const parentFile = file.replace(/^whisk\//, ''); - const parentPath = path.join(repoRoot, parentFile); - return fs.existsSync(parentPath) && readFile(file) === readFile(parentFile); - }); const childTemplatePathIndex = twigIntegration.indexOf("'path' => get_stylesheet_directory() . '/templates'"); const parentTemplatePathIndex = twigIntegration.indexOf("'path' => get_template_directory() . '/templates'"); - const childComponentSrcPathIndex = twigIntegration.indexOf("'path' => get_stylesheet_directory() . '/src/components'"); - const childComponentLegacyPathIndex = twigIntegration.indexOf("'path' => get_stylesheet_directory() . '/components'"); - const parentComponentSrcPathIndex = twigIntegration.indexOf("'path' => get_template_directory() . '/src/components'"); - const parentComponentLegacyPathIndex = twigIntegration.indexOf("'path' => get_template_directory() . '/components'"); + const childComponentSrcPathIndex = twigIntegration.indexOf("get_stylesheet_directory() . '/src/components'"); + const childComponentLegacyPathIndex = twigIntegration.indexOf("get_stylesheet_directory() . '/components'"); + const parentComponentSrcPathIndex = twigIntegration.indexOf("get_template_directory() . '/src/components'"); + const parentComponentLegacyPathIndex = twigIntegration.indexOf("get_template_directory() . '/components'"); for (const fallback of expectedParentFallbacks) { ensure(parentTemplateFiles.includes(fallback), `${fallback} should exist as a parent fallback.`); } - ensure(unexpectedChildTemplates.length === 0, `Whisk should not duplicate parent fallback templates: ${unexpectedChildTemplates.join(', ')}.`); - ensure(duplicateChildTemplates.length === 0, `Whisk templates should not be byte-identical parent copies: ${duplicateChildTemplates.join(', ')}.`); - ensure(childPageTemplate.includes("{% extends '@emulsify-tpl/page.twig' %}"), 'whisk/templates/page.twig should extend the parent-only page fallback.'); - ensure(childPageTemplate.includes('{{ parent() }}'), 'whisk/templates/page.twig should demonstrate wrapping parent fallback output.'); + ensure(childTemplateFiles.length === 0, `Whisk ships no Twig templates; remove ${childTemplateFiles.join(', ')} and see docs/template-extension.md for intentional child overrides.`); + ensure(!fs.existsSync(path.join(repoRoot, 'whisk/templates')), 'Whisk should omit the templates directory; see docs/template-extension.md before adding project overrides.'); ensure(childTemplatePathIndex !== -1, 'Twig integration should register child @templates path.'); ensure(parentTemplatePathIndex !== -1, 'Twig integration should register parent @templates path.'); ensure(childTemplatePathIndex < parentTemplatePathIndex, 'Twig integration should register child @templates before parent @templates.'); @@ -994,8 +1052,8 @@ function runStaticChecks() { ensure(twigIntegration.includes('project_structure_namespaces') && twigIntegration.includes('structureImplementations'), 'Twig integration should honor Emulsify Core structureImplementations for configured namespaces.'); ensure(twigIntegration.includes('emulsify_theme_project_component_roots'), 'Twig integration should expose a focused project component roots filter.'); ensure(twigIntegration.includes('new ProjectComponentLoader') && projectComponentLoader.includes('implements \\Twig\\Loader\\LoaderInterface'), 'Twig integration should wrap the loader for machineName:component references.'); - ensure(twigIntegration.includes('machineName:component'), 'Twig integration should document the project component reference intent in code comments.'); - ensure(twigNamespaceSmoke.includes('@custom/teaser.twig') && twigNamespaceSmoke.includes('variant.structureImplementations'), 'Twig namespace smoke should verify configured Core structure namespaces.'); + ensure(twigIntegration.includes('component_root_records') && twigIntegration.includes("$loader->getPaths( 'components' )"), 'Twig component aliases should use the selected, filtered component namespace roots.'); + ensure(twigNamespaceSmoke.includes('@custom/teaser.twig') && twigNamespaceSmoke.includes('structureImplementations'), 'Twig namespace smoke should verify configured Core structure namespaces.'); ensure(!fs.existsSync(path.join(repoRoot, 'whisk/includes/twig-namespaces.php')), 'Whisk should rely on the parent Twig namespace integration by default.'); ensure(!childFunctions.includes('twig-namespaces.php'), 'whisk/functions.php should not require a duplicate Twig namespace file.'); ensure(childFunctions.includes('project_machine_name:component_name') && childFunctions.includes('@components for compatible component libraries'), 'whisk/functions.php should document generic project machine-name component references while preserving @components compatibility.'); @@ -1016,13 +1074,45 @@ function runStaticChecks() { ensure(wordpressFixtureSmoke.includes('assertGeneratedChildTheme'), 'WordPress fixture smoke should validate generated child theme metadata and copied Whisk files.'); ensure(wordpressFixtureSmoke.includes("project.project?.generatedFrom !== 'emulsify-wordpress'"), 'WordPress fixture smoke should validate generatedFrom metadata.'); ensure(wordpressFixtureSmoke.includes('project.project?.generatedFromVersion !== expectedGeneratedFromVersion'), 'WordPress fixture smoke should derive the expected generatedFromVersion from root package metadata instead of a literal.'); - ensure(wordpressFixtureSmoke.includes('${themeSlug}-page'), 'WordPress fixture smoke should prove the generated child page template renders through Timber.'); + ensure(wordpressFixtureSmoke.includes('Generated child theme should not include Twig templates by default.') && wordpressFixtureSmoke.includes('entry__content'), 'WordPress fixture smoke should prove parent page rendering without a generated child Twig override.'); + ensure(wordpressFixtureSmoke.includes('Child block extension must preserve every surrounding byte.') && wordpressFixtureSmoke.includes("{% extends '@emulsify-tpl/page.twig' %}") && wordpressFixtureSmoke.includes('finally'), 'WordPress fixture smoke should prove one-block child inheritance and restore the temporary override; see docs/template-extension.md.'); ensure(wordpressFixtureSmoke.includes('checkGeneratedAssets'), 'WordPress fixture smoke should fetch generated child theme built assets.'); ensure(wordpressFixtureSmoke.includes('runAcfDiscoveryWithoutAcf'), 'WordPress fixture smoke should check ACF/Twig discovery when ACF is absent.'); ensure(wordpressFixtureSmoke.includes('installAcfStub'), 'WordPress fixture smoke should provide a fixture-only ACF stub.'); ensure(wordpressFixtureSmoke.includes('runAcfDiscoveryWithStub'), 'WordPress fixture smoke should check ACF/Twig registration with the ACF stub.'); ensure(wordpressFixtureSmoke.includes('emulsify/smoke-native'), 'WordPress fixture smoke should check native block.json discovery and registration.'); - return 'Parent owns route fallbacks and default Twig namespaces; Whisk ships only the page override example.'; + return 'Parent owns route fallbacks and default Twig namespaces; Whisk ships no Twig templates.'; + }); + + runStaticCheck('Template extension contract', () => { + const base = readFile('templates/layouts/base.twig'); + const extensionDocs = readFile('docs/template-extension.md'); + for (const block of ['head', 'header', 'content', 'footer', 'site_header', 'main', 'page_title']) { + ensure(base.includes(`{% block ${block} %}`) && extensionDocs.includes('`' + block + '`'), `Preserve the public ${block} block and boundary documented in docs/template-extension.md.`); + } + const goldens = listFilesRecursive('.github/fixtures/template-extension', (file) => file.endsWith('.html')); + ensure(goldens.length >= 10, 'Keep the pre-extension output captures; see docs/template-extension.md.'); + ensure(readFile('.github/scripts/pr-validation.cjs').includes('smoke:template-extension'), 'PR validation should compare exact template bytes and child extension boundaries.'); + for (const file of ['README.md', 'docs/README.md', 'docs/timber-and-twig-authoring.md']) { + ensure(readFile(file).includes('template-extension.md'), `${file} should link to the public template extension contract.`); + } + return 'Seven public layout blocks retain ten golden outputs, tested child inheritance, and documented boundaries.'; + }); + + runStaticCheck('Rendered WordPress accessibility', () => { + const { wcagTags, disabledRules } = require('./rendered-a11y.cjs'); + ensure(JSON.stringify(wcagTags) === JSON.stringify(['wcag2a', 'wcag2aa', 'wcag21a', 'wcag21aa', 'wcag22aa']), 'Rendered WordPress axe audit must select all five WCAG tags.'); + ensure(JSON.stringify(disabledRules) === JSON.stringify(['target-size']), 'Only target-size may be disabled for the unstyled parent fixture.'); + const fixtureJob = themeReadinessWorkflow.slice(themeReadinessWorkflow.indexOf(' wordpress-fixture:'), themeReadinessWorkflow.indexOf(' extended-whisk:')); + ensure(fixtureJob.includes('Select and verify runner Chrome') && fixtureJob.includes('--headless --dump-dom about:blank'), 'WordPress fixture job must verify sandboxed runner Chrome.'); + ensure(fixtureJob.includes("WP_SMOKE_A11Y: '1'") && fixtureJob.includes('WP_SMOKE_A11Y_OUTPUT:'), 'WordPress fixture job must enable the rendered browser audit and retain its reports.'); + ensure(fixtureJob.includes('wordpress-rendered-a11y-') && fixtureJob.includes('if: always()'), 'WordPress accessibility reports must upload on success and failure.'); + ensure(wordpressFixtureSmoke.includes('Verify rendered accessibility failure gates'), 'WordPress fixture must exercise the browser audit negative controls.'); + ensure(wordpressFixtureSmoke.includes('archiveCount < 12') && wordpressFixtureSmoke.includes("['option', 'update', 'posts_per_page', '1']"), 'Rendered archive audit needs at least 12 posts and one post per page.'); + const guide = readFile('docs/accessibility.md'); + ensure(guide.includes('target-size') && guide.includes('screen-reader-text') && guide.includes('focus'), 'Accessibility guide must document the sole rule exception and project styling responsibilities.'); + ensure(wordpressFixtureSmoke.includes("name: 'media-embeds'") && wordpressFixtureSmoke.includes('media-embed-smoke.php') && wordpressFixtureSmoke.includes('verifyMediaEmbeds'), 'The fixture must test media transforms and audit the rendered YouTube/Vimeo posters.'); + return 'Seven rendered routes use sandboxed Chrome, full WCAG tags, strict navigation/media assertions, and retained HTML/axe reports; only target-size is excluded.'; }); runStaticCheck('Generated child theme documentation', () => { @@ -1139,6 +1229,30 @@ function runStaticChecks() { return 'Generated docs cover project ownership, frontend workflows, upgrades, and sanitized support collection.'; }); + runStaticCheck('Generated AI guidance', () => { + const guidancePaths = [ + 'AGENTS.md', + 'docs/wordpress-integration.md', + '.agents/skills/emulsify-wordpress-integration/SKILL.md', + ]; + for (const relativePath of guidancePaths) { + const sourcePath = `whisk/${relativePath}`; + const contents = readFile(sourcePath); + ensure(!/%%EMULSIFY_[A-Z_]+%%|whisk/i.test(contents), `${sourcePath} must be token-free and contain no starter identity so generators copy it unchanged.`); + ensure(generatedThemeContract.includes(`'${relativePath}'`), `Generated theme contract should require ${relativePath}.`); + ensure(docsCommandCheck.includes(`'${relativePath}'`), `Documentation command checks should cover ${relativePath}.`); + ensure(distBuilder.includes(`"${sourcePath}"`), `Distribution build should require staged ${sourcePath}.`); + } + + const attributes = childProcess.spawnSync('git', [ + 'check-attr', 'export-ignore', '--', + 'AGENTS.md', ...guidancePaths.map((file) => `whisk/${file}`), + ], { cwd: repoRoot, encoding: 'utf8' }); + ensure(attributes.status === 0, `Unable to check guidance Git distribution attributes: ${attributes.stderr}`); + ensure(!/: export-ignore: (?:set|true)\s*$/m.test(attributes.stdout), 'Git distributions must retain contributor and generated AI guidance, including hidden skills.'); + return 'Portable guidance is required, copied without replacement, command-checked, and retained in ZIP/Git distributions.'; + }); + runStaticCheck('Generated child theme contract', () => { ensure(rootPackage.scripts['test:generated-theme'] === 'node --test .github/scripts/generated-theme-contract.test.cjs', 'package.json should expose the focused generated child theme contract tests.'); ensure(rootPackage.scripts['smoke:generation-parity'] === 'node .github/scripts/generation-parity-smoke.cjs', 'package.json should expose the generation parity smoke.'); @@ -1208,65 +1322,26 @@ function runStaticChecks() { const analyzerOptions = getReleasePluginOptions(releaseConfig, '@semantic-release/commit-analyzer'); const notesOptions = getReleasePluginOptions(releaseConfig, '@semantic-release/release-notes-generator'); const githubOptions = getReleasePluginOptions(releaseConfig, '@semantic-release/github'); - const releaseAnalyzer = releaseConfig.plugins.find((plugin) => plugin && typeof plugin.analyzeCommits === 'function'); const releaseGuard = releaseConfig.plugins.find((plugin) => plugin && typeof plugin.verifyRelease === 'function'); - const readinessJobStart = semanticReleaseWorkflow.indexOf(' release-readiness:'); - const releaseJobStart = semanticReleaseWorkflow.indexOf(' semantic-release:'); - const readinessJob = semanticReleaseWorkflow.slice(readinessJobStart, releaseJobStart); - const releaseJob = semanticReleaseWorkflow.slice(releaseJobStart); - const buildStep = releaseJob.indexOf('npm run build:dist'); - const publishStep = releaseJob.indexOf('npm run publish'); const releaseAsset = Array.isArray(githubOptions.assets) ? githubOptions.assets.find((asset) => asset.path === 'dist-artifact/emulsify.zip') : null; - ensure(releaseConfig.expectedStableRelease === '2.0.0', 'release.config.js should declare 2.0.0 as the expected stable release.'); - ensure(releaseConfig.initialStableBaseline === '1.0.0', 'release.config.js should declare the temporary 1.0.0 stable baseline.'); ensure(releaseConfig.tagFormat === '${version}', 'release.config.js should emit non-prefixed semver tags.'); ensure(releaseConfig.repositoryUrl === 'git@github.com:emulsify-ds/emulsify-wordpress.git', 'release.config.js should publish against emulsify-wordpress.'); ensure(Array.isArray(releaseConfig.branches), 'release.config.js branches must be an array.'); ensure(releaseConfig.branches.length === 1 && releaseConfig.branches[0] === 'main', 'release.config.js should publish only from main.'); - ensure(releaseAnalyzer, 'release.config.js should force the first stable release to a major release type.'); - ensure(releaseGuard, 'release.config.js should guard the first stable release version.'); + ensure(!releaseConfig.plugins.some((plugin) => ['@semantic-release/npm', '@semantic-release/git'].includes(Array.isArray(plugin) ? plugin[0] : plugin)), 'release.config.js must not rewrite committed versions through @semantic-release/npm or @semantic-release/git.'); + ensure(releaseGuard, 'release.config.js should require the computed release version to match the prepared package version.'); ensure(rootPackage.scripts.publish.startsWith('node .github/scripts/semantic-release.cjs '), 'The publish script should prepare semantic-release through the guarded runner.'); ensure(rootPackage.scripts['publish-test'].startsWith('node .github/scripts/semantic-release.cjs '), 'The publish-test script should use the same guarded semantic-release runner.'); - ensure(semanticReleaseRunner.includes("git(['tag', initialStableBaseline, sourceSha])"), 'The semantic-release runner should expose the latest prerelease commit as a temporary stable baseline.'); - ensure(semanticReleaseRunner.includes('finally') && semanticReleaseRunner.includes('removeStableBaseline(temporaryBaseline)'), 'The semantic-release runner should always clean up its temporary baseline tag.'); - ensure(releaseGuard.verifyRelease.toString().includes('removeSyntheticBaseline'), 'The stable release guard should remove the temporary baseline before semantic-release pushes tags.'); - ensure(typeof notesOptions.writerOpts?.finalizeContext === 'function', 'Release notes should suppress the inaugural compare link to the temporary baseline tag.'); ensure(releaseAsset, 'release.config.js should attach dist-artifact/emulsify.zip to GitHub releases.'); ensure(releaseAsset.label === 'Emulsify WordPress theme (with dependencies)', 'release.config.js should give the installable ZIP a clear release label.'); ensureBreakingParser('@semantic-release/commit-analyzer', analyzerOptions.parserOpts); ensureBreakingParser('@semantic-release/release-notes-generator', notesOptions.parserOpts); - ensure(readinessJobStart >= 0, 'semantic-release.yml should run release-readiness before publishing.'); - ensure(semanticReleaseWorkflow.includes('needs: release-readiness'), 'semantic-release.yml release job should wait for release readiness.'); - ensure(semanticReleaseWorkflow.includes('contents: write'), 'semantic-release.yml should grant GitHub release permissions explicitly.'); - ensure(semanticReleaseWorkflow.includes('id: semantic'), 'semantic-release.yml should expose the semantic-release step as steps.semantic.'); - ensure(semanticReleaseWorkflow.includes('npm run release:check'), 'semantic-release.yml should run local release readiness checks.'); - ensure(semanticReleaseWorkflow.includes('wp-cli'), 'semantic-release.yml should install WP-CLI for the WordPress smoke fixture.'); - ensure(semanticReleaseWorkflow.includes('mysql:'), 'semantic-release.yml should provide a MySQL service for the WordPress smoke fixture.'); - ensure(semanticReleaseWorkflow.includes('WP_SMOKE_DB_HOST'), 'semantic-release.yml should pass WordPress smoke database settings.'); - ensure(readinessJob.includes('- name: Build tested installable theme archive') && readinessJob.includes('run: npm run build:dist'), 'Release readiness should build the archive before the WordPress fixture.'); - ensure(readinessJob.includes('WP_SMOKE_THEME_ARCHIVE: dist-artifact/emulsify.zip'), 'Release readiness should test the built archive in WordPress.'); - ensure(releaseJobStart >= 0, 'semantic-release.yml should define the semantic-release job.'); - ensure(releaseJob.includes("php-version: '8.3'"), 'semantic-release.yml release job should set up PHP 8.3.'); - ensure(releaseJob.includes('tools: composer:v2'), 'semantic-release.yml release job should install Composer.'); - ensure(buildStep >= 0, 'semantic-release.yml release job should build the installable theme archive.'); - ensure(publishStep >= 0 && buildStep < publishStep, 'semantic-release.yml should build the installable theme archive before publishing.'); - try { - releaseGuard.verifyRelease({}, releaseGuardRejectContext); - throw new Error('release.config.js release guard should reject pre-2.0.0 releases.'); - } - catch (error) { - const expectedMessage = error.message.includes('Expected semantic-release to prepare 2.0.0'); - ensure(expectedMessage, 'release.config.js release guard should explain the expected 2.0.0 release.'); - } - releaseGuard.verifyRelease({}, releaseGuardAcceptContext); - releaseGuard.verifyRelease({}, releaseGuardFutureContext); - ensure(releaseAnalyzer.analyzeCommits({}, releaseAnalyzerAlphaContext) === 'major', 'release.config.js should force a major release from the latest alpha tag.'); - ensure(releaseAnalyzer.analyzeCommits({}, releaseAnalyzerNoStableContext) === 'major', 'release.config.js should force a major release when semantic-release finds no previous stable release.'); - ensure(releaseAnalyzer.analyzeCommits({}, releaseGuardRejectContext) === 'major', 'release.config.js should force a major release before 2.0.0 exists.'); - ensure(releaseAnalyzer.analyzeCommits({}, releaseGuardFutureContext) === null, 'release.config.js should use normal commit analysis after 2.0.0 exists.'); - return 'Semantic release is configured for non-prefixed tags, main-only publishing, a forced 2.0.0 stable release, and the installable ZIP asset.'; + validateReleaseWorkflow(semanticReleaseWorkflow, themeReadinessWorkflow); + validateProjectsWorkflow(readFile('.github/workflows/addtoprojects.yml')); + ensure(semanticReleaseRunner.includes('Refusing to publish local-only stable tag(s)'), 'The guarded runner should refuse to push unpublished local stable tags.'); + return 'Semantic release requires a prepared package version, non-prefixed tags, main-only publishing, and the tested installable ZIP asset.'; }); runStaticCheck('Installable release artifact', () => { @@ -1279,7 +1354,7 @@ function runStaticChecks() { ensure(distBuilder.includes('"docs"') && distBuilder.includes('"includes"') && distBuilder.includes('"templates"') && distBuilder.includes('"src"'), 'Distribution build should include user documentation and parent runtime directories.'); ensure(distBuilder.includes('"UPGRADE.md"') && distBuilder.includes('"docs/wp-cli-child-theme-generation.md"'), 'Distribution build should retain the documentation linked from its README.'); ensure(distBuilder.includes('"functions.php"') && distBuilder.includes('"style.css"') && distBuilder.includes('"theme.json"'), 'Distribution build should include required WordPress theme files.'); - ensure(distBuilder.includes('copy_tracked_directory "whisk"'), 'Distribution build should include the tracked Whisk generator payload.'); + ensure(distBuilder.includes('copy_committed_directory "whisk"'), 'Distribution build should include the committed Whisk generator payload.'); ensure(distBuilder.includes('"whisk/project.emulsify.json"') && distBuilder.includes('"whisk/style.css"'), 'Distribution build should verify required Whisk generator files.'); ensure(distBuilder.includes('"whisk/.cache"') && distBuilder.includes('"whisk/.cli"') && distBuilder.includes('"whisk/node_modules"'), 'Distribution build should reject Whisk caches, generation tooling, and dependencies.'); ensure(distBuilder.includes('find emulsify -type f -print') && distBuilder.includes('zip -X'), 'Distribution build should archive the staged emulsify/ tree reproducibly.'); @@ -1321,8 +1396,11 @@ function runStaticChecks() { ensure(themeReadinessWorkflow.includes('npm run lint:php'), 'theme-readiness.yml should run PHP lint.'); ensure(themeReadinessWorkflow.includes('npm run pr:check'), 'theme-readiness.yml should delegate project smoke checks to npm run pr:check.'); ensure(themeReadinessWorkflow.includes('npm run release:check'), 'theme-readiness.yml should run release readiness checks.'); + ensure(practicalJob.includes('fetch-depth: 0') && wordpressFixtureJob.includes('fetch-depth: 0'), 'Readiness jobs running the release version contract should fetch full history and tags.'); ensure(practicalJob.includes("- name: Build installable theme archive\n if: matrix.php-version == '8.3'\n run: npm run build:dist"), 'The PHP 8.3 practical lane should build the client-testable release archive.'); - ensure(practicalJob.includes("- name: Upload installable theme archive\n if: matrix.php-version == '8.3'\n uses: actions/upload-artifact@v7"), 'The PHP 8.3 practical lane should use direct-file artifact upload.'); + const readinessJobs = yaml.load(themeReadinessWorkflow).jobs; + const archiveUpload = readinessJobs.practical.steps.find((step) => step.name === 'Upload installable theme archive'); + ensure(archiveUpload?.if === "matrix.php-version == '8.3'" && /^actions\/upload-artifact@[a-f0-9]{40}$/.test(archiveUpload.uses), 'The PHP 8.3 practical lane should use a pinned artifact upload.'); ensure(practicalJob.includes('path: dist-artifact/emulsify.zip') && practicalJob.includes('archive: false') && practicalJob.includes('overwrite: true'), 'Theme readiness should upload the installable ZIP directly and support workflow reruns.'); ensure(practicalJob.includes('if-no-files-found: error') && practicalJob.includes('retention-days: 14'), 'The client-testable artifact should be required and retained for 14 days.'); ensure(practicalStart >= 0 && phpLintStart > practicalStart && wordpressFixtureStart > phpLintStart && extendedWhiskStart > wordpressFixtureStart, 'theme-readiness.yml should define practical, PHP, WordPress fixture, and Whisk accessibility jobs.'); @@ -1335,22 +1413,29 @@ function runStaticChecks() { ensure(wordpressFixtureJob.includes('mysql:'), 'WordPress fixture job should provide MySQL.'); ensure(wordpressFixtureJob.includes('wp-cli'), 'WordPress fixture job should install WP-CLI.'); ensure(wordpressFixtureJob.includes("WP_SMOKE_REQUIRED: '1'"), 'WordPress fixture job should require the fixture instead of allowing a skip.'); - ensure(wordpressFixtureJob.includes('- name: Build installable theme archive') && wordpressFixtureJob.includes('run: npm run build:dist'), 'WordPress fixture job should build the installable archive.'); + ensure(wordpressFixtureJob.includes('- name: Download tested release bundle') && !wordpressFixtureJob.includes('run: npm run build:dist'), 'WordPress fixture job should use the archive built by practical readiness.'); ensure(wordpressFixtureJob.includes('WP_SMOKE_THEME_ARCHIVE: dist-artifact/emulsify.zip'), 'WordPress fixture job should test the built archive instead of the source tree.'); + ensure(wordpressFixtureSmoke.includes("['core', 'version']") && wordpressFixtureSmoke.includes('WordPress version: requested') && wordpressFixtureSmoke.includes('resolved ${resolvedWordpressVersion}'), 'WordPress fixture smoke should log the actual downloaded core version, including latest and nightly resolution.'); + ensure(wordpressFixtureSmoke.includes('log(`WordPress ${resolvedWordpressVersion} (requested ${wordpressVersion}): Generated'), 'The fixture success summary must expose resolved WordPress versions in captured CI output.'); ensure(themeReadinessWorkflow.includes('extended_checks'), 'theme-readiness.yml should expose optional extended checks.'); ensure(extendedWhiskJob.includes(releaseTargetedPrGate), 'Whisk accessibility job should run on release-targeted pull requests.'); ensure(extendedWhiskJob.includes("github.event_name == 'schedule'"), 'Whisk accessibility job should run on the schedule.'); ensure(extendedWhiskJob.includes("(github.event_name == 'workflow_dispatch' && inputs.extended_checks)"), 'Whisk accessibility job should honor its manual input.'); ensure(extendedWhiskJob.includes('cp -R .github/fixtures/whisk-a11y/. whisk/src/components/'), 'Whisk accessibility job should seed the CI-only component fixture.'); - ensure(extendedWhiskJob.includes('id: setup-chrome') && extendedWhiskJob.includes('uses: browser-actions/setup-chrome@v2'), 'Whisk accessibility job should install Chrome explicitly.'); - ensure(extendedWhiskJob.includes('PUPPETEER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }}'), 'Whisk accessibility job should use the Chrome path provided by setup-chrome.'); + ensure(extendedWhiskJob.includes('Select and verify runner Chrome') && extendedWhiskJob.includes('command -v google-chrome'), 'Whisk accessibility job should use the runner-installed Chrome.'); + ensure(extendedWhiskJob.includes('"$chrome_path" --version') && extendedWhiskJob.includes('"$chrome_path" --headless --dump-dom about:blank') && extendedWhiskJob.includes('PUPPETEER_EXECUTABLE_PATH=%s') && extendedWhiskJob.includes('"$GITHUB_ENV"'), 'Whisk accessibility job should verify a sandboxed Chrome launch and export its path.'); + ensure(!extendedWhiskJob.includes('browser-actions/setup-chrome') && !extendedWhiskJob.includes('--no-sandbox') && !extendedWhiskJob.includes('--disable-setuid-sandbox'), 'Whisk accessibility CI must preserve the installed browser sandbox.'); + ensure(extendedWhiskJob.includes("PUPPETEER_SKIP_DOWNLOAD: 'true'"), 'Whisk CI should skip redundant Puppeteer browser downloads.'); + ensure(extendedWhiskJob.includes('npm --prefix whisk run test -- --runInBand'), 'Whisk CI should execute real seeded project tests before the accessibility audit.'); ensure(extendedWhiskJob.includes('npm --prefix whisk run a11y'), 'Whisk accessibility job should build Storybook and run the real audit.'); - ensure(!extendedWhiskJob.includes('continue-on-error: true'), 'Whisk accessibility violations should fail the job.'); ensure(whiskA11yEntry.includes('ciReadinessFixture'), 'CI-only Whisk fixture should provide a Vite entry.'); ensure(whiskA11yStory.includes("title: 'CI/Readiness fixture'") && whiskA11yStory.includes("import template from './ci-readiness.twig'"), 'CI-only Whisk fixture should provide a discoverable Twig story.'); ensure(whiskA11yTemplate.includes('Fixture ready
Expected content
+ +
'),
+ '/bad-pagination': clean.replace('', ''),
+ '/bad-menu': clean.replace('- ', ''), + }; + const server = http.createServer((request, response) => { + response.writeHead(request.url === '/http-error' ? 500 : 200, { 'Content-Type': 'text/html; charset=utf-8' }); + response.end(pages[request.url] || clean); + }); + await new Promise((resolve, reject) => { + server.once('error', reject); + server.listen(0, '127.0.0.1', resolve); + }); + const baseUrl = `http://127.0.0.1:${server.address().port}`; + try { + const routes = Object.keys(pages).map((url) => ({ + name: url.slice(1), + url: baseUrl + url, + expectedText: ['Fixture ready', 'Expected content'], + paginationPage: 2, + currentMenuHref: `${baseUrl}/clean`, + })); + await assert.rejects(auditRenderedPages({ themeDir, routes, outputDir }), (error) => { + assert(error instanceof AggregateError); + assert.equal(error.errors.length, 6, 'Every failing route must be reported, including routes after the first failure.'); + return true; + }); + const reports = Object.fromEntries(routes.map(({ name }) => { + assert(fs.readFileSync(path.join(outputDir, `${name}.html`), 'utf8').includes('Fixture ready')); + return [name, JSON.parse(fs.readFileSync(path.join(outputDir, `${name}.axe.json`), 'utf8'))]; + })); + assert.equal(reports.clean.error, undefined); + assert.equal(reports.clean.axe.violations.length, 0); + assert.deepEqual(reports.clean.wcagTags, wcagTags); + assert.deepEqual(disabledRules, ['target-size']); + assert.deepEqual(reports.clean.disabledRules, ['target-size']); + assert.equal(reports.clean.rendered.screenReaderText[0].position, 'static', 'Evidence must reflect actual computed styles without injecting screen-reader CSS.'); + assert.match(reports['http-error'].error, /HTTP 500/); + assert.match(reports['missing-content'].error, /missing expected rendered content/); + assert(reports['axe-violation'].axe.violations.some(({ id }) => id === 'image-alt')); + assert(reports['bad-media'].axe.violations.some(({ id }) => id === 'image-alt'), 'Axe must audit the document inside srcdoc too.'); + assert.match(reports['axe-violation'].error, /accessibility violations: image-alt/); + assert.match(reports['bad-pagination'].error, /exactly one current pagination item/); + assert.match(reports['bad-menu'].error, /exactly one current primary-menu item/); + } finally { + await new Promise((resolve) => server.close(resolve)); + fs.rmSync(outputDir, { recursive: true, force: true }); + } +}); diff --git a/.github/scripts/semantic-release.cjs b/.github/scripts/semantic-release.cjs index ac3926d..e46eeab 100644 --- a/.github/scripts/semantic-release.cjs +++ b/.github/scripts/semantic-release.cjs @@ -1,162 +1,169 @@ #!/usr/bin/env node -const { execFileSync, spawnSync } = require('node:child_process'); +const { execFileSync } = require('node:child_process'); const path = require('node:path'); +const { parseArgs } = require('node:util'); +const { validateReleaseVersionContract } = require('./release-version-contract.cjs'); -const repoRoot = path.resolve(__dirname, '..', '..'); -const { - expectedStableRelease, - initialStableBaseline, -} = require(path.join(repoRoot, 'release.config.js')); -const syntheticBaselineEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE'; -const syntheticBaselineShaEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SHA'; -const syntheticBaselineSourceEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SOURCE'; - -function git(args, options = {}) { - const output = execFileSync('git', args, { - cwd: repoRoot, - encoding: 'utf8', - ...options, - }); - - return typeof output === 'string' ? output.trim() : ''; -} - -function mergedTags() { - const output = git(['tag', '--merged', 'HEAD', '--sort=-version:refname']); - - return output === '' ? [] : output.split(/\r?\n/); +function git(repoRoot, args) { + return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' }).trim(); } -function publishedTags() { - const output = git(['ls-remote', '--tags', 'origin']); - const tags = new Set(); +function assertPublishedStableTags(repoRoot) { + const stableTags = git(repoRoot, ['tag', '--list']) + .split(/\r?\n/).filter((tag) => /^\d+\.\d+\.\d+$/.test(tag)); + const remoteTags = new Set(git(repoRoot, ['ls-remote', '--tags', 'origin']) + .split(/\r?\n/).map((line) => (line.split(/\s+/)[1] || '') + .replace(/^refs\/tags\//, '').replace(/\^\{\}$/, ''))); + const localOnlyTags = stableTags.filter((tag) => !remoteTags.has(tag)); - for (const line of output.split(/\r?\n/)) { - const ref = line.trim().split(/\s+/)[1] || ''; - if (ref.startsWith('refs/tags/')) { - tags.add(ref.slice('refs/tags/'.length).replace(/\^\{\}$/, '')); - } + if (localOnlyTags.length > 0) { + throw new Error( + `Refusing to publish local-only stable tag(s): ${localOnlyTags.join(', ')}. Remove them or publish them intentionally first.`, + ); } - - return tags; } -function tagCommit(tag) { +function assertCurrentMain(repoRoot) { + const head = git(repoRoot, ['rev-parse', 'HEAD']); + let remoteMain; try { - return git(['rev-parse', '--verify', `${tag}^{commit}`]); + remoteMain = git(repoRoot, ['ls-remote', 'origin', 'refs/heads/main']).split(/\s+/)[0]; + } catch (error) { + throw new Error(`Unable to verify origin/main before releasing; check origin connectivity and retry. ${error.message}`); } - catch { - return null; + if (!remoteMain) { + throw new Error('Unable to verify origin/main before releasing: origin has no refs/heads/main.'); + } + if (head !== remoteMain) { + throw new Error( + `Main moved during the release: HEAD ${head} differs from origin/main ${remoteMain}. The Semantic release job is stale. Start a new workflow_dispatch run of WordPress Release (semantic-release.yml) on main instead of re-running the old job.`, + ); } } -function prepareStableBaseline() { - const branch = process.env.GITHUB_REF_NAME || git(['branch', '--show-current']); - - if (branch !== 'main') { - return null; +async function assertPublishedRelease(tag, env, fetchRelease) { + const token = env.GITHUB_TOKEN || env.GH_TOKEN; + const repository = env.GITHUB_REPOSITORY; + if (!token) throw new Error('GITHUB_TOKEN is required in CI to verify the tagged GitHub release and emulsify.zip.'); + if (!/^[\w.-]+\/[\w.-]+$/.test(repository || '')) { + throw new Error('GITHUB_REPOSITORY must identify owner/repo to verify the tagged GitHub release in CI.'); } - - const tags = mergedTags(); - const stableTags = tags.filter((tag) => /^\d+\.\d+\.\d+$/.test(tag)); - - if (stableTags.length > 0) { - const remoteTags = publishedTags(); - const localOnlyTags = stableTags.filter((tag) => !remoteTags.has(tag)); - - if (localOnlyTags.length > 0) { - throw new Error( - `Refusing to publish local-only stable tag(s): ${localOnlyTags.join(', ')}. Remove them or publish them intentionally first.` - ); - } - - return null; + const api = (env.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, ''); + const upload = `gh release upload ${tag} dist-artifact/emulsify.zip --repo ${repository} --clobber`; + const publish = `gh release edit ${tag} --repo ${repository} --draft=false --prerelease=false`; + let response; + let release; + try { + response = await fetchRelease(`${api}/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`, { + headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' }, + redirect: 'error', + signal: AbortSignal.timeout(15000), + }); + if (response.ok) release = await response.json(); + } catch (error) { + throw new Error(`Unable to verify GitHub release ${tag}: ${error.message}. Restore API connectivity and rerun the release workflow.`); } - - const prereleaseTag = tags.find((tag) => tag.startsWith(`${initialStableBaseline}-`)); - - if (!prereleaseTag) { + if (response.status === 404) { + // The tag endpoint exposes published releases; read-only callers may not + // see a remaining draft. Keep recovery conditional instead of adding writes. throw new Error( - `Cannot prepare ${expectedStableRelease}: no stable tag or merged ${initialStableBaseline} prerelease tag was found.` + `Published GitHub release ${tag} is missing or still a draft. With a maintainer token, inspect: gh release view ${tag} --repo ${repository}. If no release exists, create a draft from the tag's tested ZIP: gh release create ${tag} dist-artifact/emulsify.zip --repo ${repository} --verify-tag --draft --title ${tag} --generate-notes. If a draft already exists, restore its ZIP instead: ${upload}. Review the release notes, then publish: ${publish}`, ); } - - const sourceSha = tagCommit(prereleaseTag); - if (!sourceSha) { - throw new Error(`Cannot resolve ${prereleaseTag} to a commit for the temporary stable baseline.`); + if (!response.ok) throw new Error(`Unable to verify GitHub release ${tag}: HTTP ${response.status}. Check GITHUB_TOKEN repository permissions and GitHub API availability, then rerun the release workflow.`); + if (!release || typeof release !== 'object' || Array.isArray(release) || !Array.isArray(release.assets)) { + throw new Error(`Unable to verify GitHub release ${tag}: invalid GitHub API response. Rerun after checking API availability.`); } + const zip = release.assets.find((asset) => asset?.name === 'emulsify.zip' && asset.state === 'uploaded' && typeof asset.size === 'number' && asset.size > 0); + const unpublished = release.draft !== false || release.prerelease !== false || !release.published_at; + if (!zip || unpublished) { + const commands = [!zip && upload, unpublished && publish].filter(Boolean).join('; '); + throw new Error(`Tagged release ${tag} is incomplete: ${!zip ? 'emulsify.zip is missing, empty, or not uploaded' : 'the GitHub release is not published as stable'}. Recover using the tag's tested ZIP and review the release notes before publishing: ${commands}`); + } + console.log(`Verified published GitHub release ${tag} with emulsify.zip.`); +} - git(['tag', initialStableBaseline, sourceSha]); +function releaseOptions(args) { + const { values } = parseArgs({ + args, + allowNegative: true, + options: { + 'tag-format': { type: 'string', short: 't' }, + 'dry-run': { type: 'boolean', short: 'd' }, + debug: { type: 'boolean' }, + ci: { type: 'boolean' }, + 'check-publication': { type: 'boolean' }, + }, + }); return { - sha: sourceSha, - source: prereleaseTag, - tag: initialStableBaseline, + ...(values['tag-format'] !== undefined && { tagFormat: values['tag-format'] }), + ...(values['dry-run'] !== undefined && { dryRun: values['dry-run'] }), + ...(values.ci !== undefined && { ci: values.ci }), + ...(values.debug !== undefined && { debug: values.debug }), + ...(values['check-publication'] !== undefined && { checkPublication: values['check-publication'] }), }; } -function removeStableBaseline(baseline) { - if (!baseline) { - return; +async function runSemanticRelease(options, context) { + if (options.debug) { + (await import('debug')).default.enable('semantic-release:*'); } + return (await import('semantic-release')).default(options, context); +} - const existingSha = tagCommit(baseline.tag); - if (!existingSha) { - return; +async function main({ + repoRoot = path.resolve(__dirname, '../..'), + args = process.argv.slice(2), + runRelease = runSemanticRelease, + env = process.env, + fetchRelease = globalThis.fetch, +} = {}) { + const { checkPublication = false, ...options } = releaseOptions(args); + const isCI = Boolean(env.CI) && env.CI !== 'false'; + const contract = validateReleaseVersionContract({ repoRoot }); + if (!contract.latestStableTag || !Object.hasOwn(contract, 'packageVersion')) { + throw new Error(contract.errors.join('\n')); } - if (existingSha !== baseline.sha) { - throw new Error( - `Refusing to delete ${baseline.tag}: it no longer points to the temporary baseline commit ${baseline.sha}.` - ); + // Check before skipping too: semantic-release must never push an unpublished + // stable tag from a developer's checkout. + assertPublishedStableTags(repoRoot); + // Diagnose a partial tag-first release before stale draft metadata masks it. + if (isCI && contract.packageVersion === contract.latestStableTag) { + await assertPublishedRelease(contract.latestStableTag, env, fetchRelease); + } + // The early workflow preflight is read-only. Full readiness and the normal + // runner still enforce all document and version rules before publishing. + if (checkPublication) return 0; + if (contract.errors.length > 0) throw new Error(contract.errors.join('\n')); + if (!contract.releasePrepared) { + console.log(`No release prepared: package.json matches latest stable tag ${contract.latestStableTag}. Skipping publishing.`); + return 0; } - git(['tag', '--delete', baseline.tag], { stdio: 'ignore' }); -} - -function main() { - let temporaryBaseline = null; - - try { - temporaryBaseline = prepareStableBaseline(); - - const cli = require.resolve('semantic-release/bin/semantic-release.js'); - const result = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { - cwd: repoRoot, - env: { - ...process.env, - [syntheticBaselineEnvironment]: temporaryBaseline?.tag || '', - [syntheticBaselineShaEnvironment]: temporaryBaseline?.sha || '', - [syntheticBaselineSourceEnvironment]: temporaryBaseline?.source || '', - }, - stdio: 'inherit', - }); - - if (result.error) { - throw result.error; - } - - if ( - result.status === 0 - && temporaryBaseline - && tagCommit(temporaryBaseline.tag) - ) { - throw new Error( - `Semantic-release completed without removing the temporary ${temporaryBaseline.tag} baseline tag.` - ); - } + if (isCI) assertCurrentMain(repoRoot); - return Number.isInteger(result.status) ? result.status : 1; + // A release PR can verify its version before merging to main. This override + // is only for an explicit local dry run, which cannot tag or publish. + if (!isCI && options.dryRun && options.ci === false) { + options.branches = [git(repoRoot, ['branch', '--show-current'])]; } - finally { - removeStableBaseline(temporaryBaseline); + + const result = await runRelease(options, { cwd: repoRoot }); + if (result?.nextRelease?.version !== contract.packageVersion) { + throw new Error( + `Prepared package.json version ${contract.packageVersion}, but semantic-release ${result?.nextRelease ? `computed ${result.nextRelease.version}` : 'did not compute a release'}. Run on main with releasable Conventional Commits matching the prepared version, then rerun npm run release:check.`, + ); } + return 0; } -try { - process.exitCode = main(); -} -catch (error) { - console.error(`Semantic release runner failed: ${error.message}`); - process.exitCode = 1; +if (require.main === module) { + main().then((status) => { process.exitCode = status; }).catch((error) => { + console.error(`Semantic release runner failed: ${error.message}`); + process.exitCode = 1; + }); } + +module.exports = { assertPublishedStableTags, main, releaseOptions }; diff --git a/.github/scripts/semantic-release.test.cjs b/.github/scripts/semantic-release.test.cjs new file mode 100644 index 0000000..dd7fd8e --- /dev/null +++ b/.github/scripts/semantic-release.test.cjs @@ -0,0 +1,292 @@ +const assert = require('node:assert/strict'); +const { execFileSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { test } = require('node:test'); +const { assertPublishedStableTags, main, releaseOptions } = require('./semantic-release.cjs'); +const releaseConfig = require('../../release.config.js'); +const guard = releaseConfig.plugins.find((plugin) => typeof plugin.verifyRelease === 'function'); + +const githubEnv = { + CI: 'true', + GITHUB_TOKEN: 'fixture-token', + GITHUB_REPOSITORY: 'emulsify-ds/emulsify-wordpress', +}; + +function publishedRelease(overrides = {}) { + return { + draft: false, + prerelease: false, + published_at: '2026-10-28T12:00:00Z', + assets: [{ name: 'emulsify.zip', state: 'uploaded', size: 42 }], + ...overrides, + }; +} + +function releaseResponse(status = 200, release = publishedRelease()) { + return { ok: status >= 200 && status < 300, status, json: async () => release }; +} + +function fixture(t, version = '2.1.0') { + const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'emulsify-publish-contract-')); + t.after(() => fs.rmSync(workRoot, { recursive: true, force: true })); + const repoRoot = path.join(workRoot, 'checkout'); + const remote = path.join(workRoot, 'origin.git'); + fs.mkdirSync(repoRoot); + const git = (...args) => execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', ...args], { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); + // Keep remote HEAD valid even when the runner defaults to another branch. + git('-c', 'init.defaultBranch=legacy', 'init', '--bare', '-b', 'main', remote); + git('init', '-b', 'main'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'chore: initial release'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'tag', '-a', '2.0.0', '-m', '2.0.0'); + git('remote', 'add', 'origin', remote); + git('push', 'origin', 'main', '--tags'); + fs.mkdirSync(path.join(repoRoot, 'docs')); + for (const file of ['README.md', 'docs/release-process.md', 'docs/release-notes-next.md']) { + fs.writeFileSync(path.join(repoRoot, file), ''); + } + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ name: 'release-contract', version })); + fs.mkdirSync(path.join(repoRoot, 'dist-artifact')); + fs.writeFileSync(path.join(repoRoot, 'dist-artifact/emulsify.zip'), 'fixture release archive'); + return { repoRoot, remote, git }; +} + +test('publish guard accepts the exact prepared version on every subsequent release', (t) => { + const { repoRoot } = fixture(t); + guard.verifyRelease({}, { cwd: repoRoot, nextRelease: { version: '2.1.0' } }); + assert.throws(() => guard.verifyRelease({}, { cwd: repoRoot, nextRelease: { version: '2.0.1' } }), /Prepared package.json version 2\.1\.0.*computed 2\.0\.1.*release PR/); + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ version: '3.0.0' })); + assert.throws(() => guard.verifyRelease({}, { cwd: repoRoot, lastRelease: { version: '2.1.0' }, nextRelease: { version: '2.2.0' } }), /Prepared package.json version 3\.0\.0.*computed 2\.2\.0/); +}); + +test('skips publishing successfully when package.json equals the latest tag', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + const status = await main({ repoRoot, env: {}, args: ['--dry-run', '--debug', '--no-ci'], runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.') }); + assert.equal(status, 0); +}); + +test('prepared release accepts a matching semantic-release result and forwards documented flags', async (t) => { + const { repoRoot } = fixture(t); + const status = await main({ repoRoot, env: {}, args: ['--tag-format', '${version}', '--dry-run', '--debug', '--no-ci'], runRelease: async (options, context) => { + assert.equal(context.cwd, repoRoot); + assert.equal(options.tagFormat, '${version}'); + assert.equal(options.dryRun, true); + assert.equal(options.debug, true); + assert.equal(options.ci, false); + guard.verifyRelease({}, { ...context, nextRelease: { version: '2.1.0' } }); + return { nextRelease: { version: '2.1.0' } }; + } }); + assert.equal(status, 0); +}); + +test('prepared release rejects mismatched or absent semantic-release results', async (t) => { + const { repoRoot } = fixture(t); + for (const result of [false, { nextRelease: { version: '2.0.1' } }]) { + await assert.rejects(main({ repoRoot, env: {}, args: [], runRelease: async () => result }), /Prepared package.json version 2\.1\.0.*(?:computed 2\.0\.1|did not compute a release).*Conventional Commits/); + } +}); + +test('refuses local-only stable tags before any publishing or skip', async (t) => { + const { repoRoot, git } = fixture(t, '2.0.1'); + assert.doesNotThrow(() => assertPublishedStableTags(repoRoot)); + git('tag', '2.0.1'); + assert.throws(() => assertPublishedStableTags(repoRoot), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); + await assert.rejects(main({ repoRoot, env: {}, args: [], runRelease: () => assert.fail('Local-only stable tags must block semantic-release.') }), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); +}); + +test('also refuses local-only stable tags on unmerged branches', (t) => { + const { repoRoot, git } = fixture(t); + git('switch', '-c', 'unmerged'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'chore: unmerged work'); + git('tag', '2.0.1'); + git('switch', 'main'); + assert.equal(git('tag', '--merged', 'HEAD'), '2.0.0'); + assert.throws(() => assertPublishedStableTags(repoRoot), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); +}); + +function advanceRemoteMain({ repoRoot, remote }) { + const otherCheckout = path.join(path.dirname(repoRoot), 'main-mover'); + execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', 'clone', '--quiet', remote, otherCheckout], { stdio: 'pipe' }); + const git = (...args) => execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', ...args], { cwd: otherCheckout, encoding: 'utf8', stdio: 'pipe' }).trim(); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'docs: update contributors'); + git('push', 'origin', 'main'); + return git('rev-parse', 'HEAD'); +} + +test('CI refuses a moved remote main before semantic-release, even with --no-ci and a stale tracking ref', async (t) => { + const repository = fixture(t); + const { repoRoot, git } = repository; + const checkedOut = git('rev-parse', 'HEAD'); + const remoteHead = advanceRemoteMain(repository); + assert.notEqual(remoteHead, checkedOut); + assert.equal(git('rev-parse', 'origin/main'), checkedOut, 'The regression must not refresh the stale tracking ref.'); + let released = false; + await assert.rejects(main({ + repoRoot, env: { CI: 'true' }, args: ['--dry-run', '--no-ci'], + runRelease: async () => { released = true; return { nextRelease: { version: '2.1.0' } }; }, + }), /main moved.*Semantic release.*workflow_dispatch.*main/i); + assert.equal(released, false, 'The preflight must stop before semantic-release can run.'); +}); + +test('CI accepts current main and a fresh detached workflow_dispatch after main moved', async (t) => { + const repository = fixture(t); + const { repoRoot, git } = repository; + const runRelease = async (options) => { + assert.equal(options.branches, undefined, 'CI must keep the configured main branch even with --no-ci.'); + return { nextRelease: { version: '2.1.0' } }; + }; + assert.equal(await main({ repoRoot, env: { CI: 'true' }, args: [], runRelease }), 0); + const currentMain = advanceRemoteMain(repository); + git('fetch', 'origin', 'main'); + git('switch', '--detach', 'origin/main'); + assert.equal(git('rev-parse', 'HEAD'), currentMain); + assert.equal(await main({ + repoRoot, env: { CI: 'true', GITHUB_EVENT_NAME: 'workflow_dispatch', GITHUB_REF: 'refs/heads/main' }, + args: ['--dry-run', '--no-ci'], runRelease, + }), 0); +}); + +test('local dry runs on a release branch do not require HEAD to equal remote main', async (t) => { + const { repoRoot, git } = fixture(t); + git('switch', '-c', 'release-2.1.x'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'feat: prepare the next release'); + for (const env of [{}, { CI: 'false' }]) { + assert.equal(await main({ + repoRoot, env, args: ['--dry-run', '--no-ci'], + runRelease: async (options) => { + assert.deepEqual(options.branches, ['release-2.1.x']); + return { nextRelease: { version: '2.1.0' } }; + }, + }), 0); + } +}); + +test('CI still skips a valid unprepared release without invoking semantic-release', async (t) => { + const repository = fixture(t, '2.0.0'); + advanceRemoteMain(repository); + let checked = 0; + assert.equal(await main({ + repoRoot: repository.repoRoot, env: githubEnv, args: [], + fetchRelease: async (url, options) => { + checked += 1; + assert.equal(url, 'https://api.github.com/repos/emulsify-ds/emulsify-wordpress/releases/tags/2.0.0'); + assert.equal(options.headers.Authorization, 'Bearer fixture-token'); + assert.equal(options.redirect, 'error', 'Release credentials must not follow redirects.'); + return releaseResponse(); + }, + runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.'), + }), 0); + assert.equal(checked, 1, 'CI must verify publication health before treating the tagged version as a successful skip.'); +}); + +test('CI refuses a missing GitHub release for a tag and reports safe recovery commands', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + await assert.rejects(main({ + repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(404), + runRelease: () => assert.fail('A partial release must never invoke semantic-release.'), + }), /release 2\.0\.0.*missing or still a draft.*gh release view 2\.0\.0.*gh release create 2\.0\.0.*--verify-tag.*--draft[\s\S]*gh release upload 2\.0\.0[\s\S]*gh release edit 2\.0\.0.*--draft=false/i); +}); + +test('CI refuses unpublished releases and missing or incomplete release ZIP assets', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + for (const release of [ + publishedRelease({ draft: true, published_at: null }), + publishedRelease({ prerelease: true }), + publishedRelease({ published_at: null }), + publishedRelease({ assets: [] }), + publishedRelease({ assets: [{ name: 'source.zip', state: 'uploaded', size: 42 }] }), + publishedRelease({ assets: [{ name: 'emulsify.zip', state: 'starter', size: 42 }] }), + publishedRelease({ assets: [{ name: 'emulsify.zip', state: 'uploaded', size: 0 }] }), + ]) { + await assert.rejects(main({ + repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(200, release), + runRelease: () => assert.fail('A partial release must never invoke semantic-release.'), + }), /gh release (?:upload|edit) 2\.0\.0/); + } +}); + +test('CI recovery check fails closed on absent credentials, API failures, and invalid release responses', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + for (const env of [{ CI: 'true' }, { CI: 'true', GITHUB_TOKEN: 'fixture-token' }]) { + await assert.rejects(main({ + repoRoot, env, args: [], fetchRelease: () => assert.fail('Missing CI configuration must fail before requesting GitHub.'), + }), /GITHUB_TOKEN|GITHUB_REPOSITORY/); + } + for (const status of [401, 403, 500]) { + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(status) }), new RegExp(`HTTP ${status}`)); + } + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => { throw new Error('network unavailable'); } }), /Unable to verify GitHub release.*network unavailable/); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(200, null) }), /Unable to verify GitHub release/); +}); + +test('CI diagnoses partial tagged releases before stale-draft errors but keeps the draft contract strict', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + fs.writeFileSync(path.join(repoRoot, 'docs/release-notes-next.md'), '# 2.0.0 Release Notes Draft'); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(404) }), /gh release create 2\.0\.0/); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse() }), /already-tagged release 2\.0\.0/); +}); + +test('local unprepared runs remain tokenless and do not query GitHub', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + assert.equal(await main({ + repoRoot, env: {}, args: ['--dry-run', '--no-ci'], + fetchRelease: () => assert.fail('Local skips do not require GitHub API access.'), + runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.'), + }), 0); +}); + +test('publication preflight never invokes semantic-release and leaves draft validation to readiness', async (t) => { + const { repoRoot } = fixture(t); + fs.writeFileSync(path.join(repoRoot, 'README.md'), 'Latest release: 1.9.9'); + assert.equal(await main({ + repoRoot, env: githubEnv, args: ['--check-publication'], + fetchRelease: () => assert.fail('An upcoming untagged release has no GitHub release to check.'), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), 0); + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ version: '2.0.0' })); + await assert.rejects(main({ + repoRoot, env: githubEnv, args: ['--check-publication'], fetchRelease: async () => releaseResponse(404), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), /gh release create 2\.0\.0/); + assert.equal(await main({ + repoRoot, env: githubEnv, args: ['--check-publication'], fetchRelease: async () => releaseResponse(), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), 0); +}); + +test('parses the existing publish and publish-test command options', () => { + assert.deepEqual(releaseOptions(['--tag-format', '${version}', '--dry-run', '--debug', '--no-ci']), { tagFormat: '${version}', dryRun: true, debug: true, ci: false }); + assert.deepEqual(releaseOptions(['-t', '${version}', '-d']), { tagFormat: '${version}', dryRun: true }); + assert.deepEqual(releaseOptions(['--check-publication']), { checkPublication: true }); +}); + +test('real semantic-release dry run analyzes a pushed release PR branch and blocks mismatches before tagging', (t) => { + const { repoRoot, remote, git } = fixture(t); + fs.symlinkSync(path.resolve(__dirname, '../../node_modules'), path.join(repoRoot, 'node_modules'), 'dir'); + git('switch', '-c', 'release-2.1.x'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'feat: add a project capability'); + git('push', 'origin', 'release-2.1.x'); + // semantic-release hooks stdout, so run it outside node:test's event stream. + const script = ` + const assert = require('node:assert/strict'); + const fs = require('node:fs'); + const { main } = require(${JSON.stringify(path.join(__dirname, 'semantic-release.cjs'))}); + const config = require(${JSON.stringify(path.resolve(__dirname, '../../release.config.js'))}); + (async () => { + const { default: semanticRelease } = await import(${JSON.stringify(require.resolve('semantic-release'))}); + const guard = config.plugins.find((plugin) => typeof plugin.verifyRelease === 'function'); + const runRelease = (options, context) => semanticRelease({ + ...config, ...options, repositoryUrl: ${JSON.stringify(remote)}, plugins: [config.plugins[0], guard], + }, context); + const options = { repoRoot: process.cwd(), env: {}, args: ['--dry-run', '--no-ci'], runRelease }; + assert.equal(await main(options), 0); + fs.writeFileSync('package.json', JSON.stringify({ version: '2.0.1' })); + await assert.rejects(main(options), /Prepared package.json version 2\\.0\\.1.*computed 2\\.1\\.0/); + })().catch((error) => { console.error(error); process.exitCode = 1; }); + `; + // CI provider branch variables and node:test IPC belong to the outer repo. + const env = { PATH: process.env.PATH, HOME: process.env.HOME }; + execFileSync(process.execPath, ['-e', script], { cwd: repoRoot, env, stdio: 'pipe' }); + assert.equal(git('tag', '--list'), '2.0.0'); +}); diff --git a/.github/scripts/template-extension-smoke.php b/.github/scripts/template-extension-smoke.php new file mode 100644 index 0000000..299cd55 --- /dev/null +++ b/.github/scripts/template-extension-smoke.php @@ -0,0 +1,412 @@ +'; +} + +function get_the_title( $post = 0 ): string { + $GLOBALS['emulsify_extension_title_posts'][] = $post; + return 'Protected: Secret
& fixture'; +} + +function do_action( string $hook, ...$arguments ): void { + $GLOBALS['emulsify_extension_hooks'][] = $hook; + echo '<!-- action:' . $hook . ' -->'; +} + +function wp_head(): void { + $GLOBALS['emulsify_extension_hooks'][] = 'wp_head'; + echo '<!-- wp_head -->'; +} + +function wp_body_open(): void { + $GLOBALS['emulsify_extension_hooks'][] = 'wp_body_open'; + echo '<!-- wp_body_open -->'; +} + +function wp_footer(): void { + $GLOBALS['emulsify_extension_hooks'][] = 'wp_footer'; + echo '<!-- wp_footer -->'; +} + +/** + * Builds deterministic data with fresh attribute helpers for every render. + * + * @param bool $has_title Whether the document has a title. + * @param bool $has_menu Whether primary menu items exist. + * @param bool $has_content Whether the fixture content exists. + * @return array Template context. + */ +function emulsify_extension_context( bool $has_title, bool $has_menu, bool $has_content ): array { + $items = array( + array( + 'title' => 'Current <link> & fixture', + 'link' => '/current/?first=1&second=2', + 'classes' => array( 'fixture-menu-item' ), + 'current' => true, + 'children' => array( + array( 'title' => 'Nested & fixture', 'link' => '/nested/', 'target' => '_blank' ), + ), + ), + array( 'title' => 'Other & fixture', 'link' => '/other/' ), + ); + $context = array( + 'site' => array( + 'url' => 'https://example.test/?first=1&second=2', + 'name' => 'Fixture <site> & WordPress', + 'charset' => 'UTF-8', + 'language_attributes' => 'lang="en" dir="ltr"', + ), + 'body_class' => 'fixture-body route-page', + 'menu' => $has_menu ? array( 'get_items' => $items ) : null, + 'fixture_content' => $has_content ? '<p>Content & fixture</p>' : '', + ); + + if ( $has_title ) { + $context['title'] = 'Page <title> & fixture'; + } + + return $context; +} + +/** + * Captures explicitly or compares every output byte against a committed file. + * + * @param string $name Golden name. + * @param string $output Rendered output. + * @param bool $capture Whether to update the golden deliberately. + * @return void + */ +function emulsify_extension_golden( string $name, string $output, bool $capture ): void { + $file = __DIR__ . '/../fixtures/template-extension/' . $name . '.html'; + + if ( $capture ) { + if ( false === file_put_contents( $file, $output ) ) { + throw new RuntimeException( 'Could not capture ' . $file ); + } + } elseif ( ! is_file( $file ) || file_get_contents( $file ) !== $output ) { + throw new RuntimeException( $name . ': rendered bytes differ from the pre-extension golden file.' ); + } + + echo ( $capture ? 'CAPTURE ' : 'PASS ' ) . $name . ' (' . strlen( $output ) . " bytes)\n"; +} + +/** + * Collects independent extension failures in one run. + * + * @param bool $condition Assertion result. + * @param string $message Failure explanation. + * @param array $errors Collected failures. + * @return void + */ +function emulsify_extension_expect( bool $condition, string $message, array &$errors ): void { + if ( ! $condition ) { + $errors[] = $message; + } +} + +$capture = array_slice( $argv, 1 ) === array( '--update-goldens' ); +$exit_code = 0; + +if ( count( $argv ) > 1 && ! $capture ) { + fwrite( STDERR, "Only --update-goldens is supported; ordinary runs never rewrite fixtures.\n" ); + exit( 1 ); +} + +try { + if ( ! mkdir( get_stylesheet_directory() . '/templates', 0777, true ) ) { + throw new RuntimeException( 'Could not create the disposable child theme.' ); + } + $integration = new Twig(); + $filesystem = $integration->loader_paths( new \Twig\Loader\FilesystemLoader() ); + $fixtures = new \Twig\Loader\ArrayLoader( + array( + 'content-fixture.twig' => '{% extends "@emulsify-tpl/layouts/base.twig" %}{% block content %}{{ fixture_content|raw }}{% endblock %}', + ) + ); + $environment = new \Twig\Environment( + new \Twig\Loader\ChainLoader( array( $fixtures, $filesystem ) ), + $integration->environment_options( array( 'cache' => false ) ) + ); + + foreach ( $integration->functions( array() ) as $name => $definition ) { + $environment->addFunction( new \Twig\TwigFunction( $name, $definition['callable'], $definition['options'] ?? array() ) ); + } + $environment->addFunction( new \Twig\TwigFunction( 'function', array( new \Timber\Twig(), 'exec_function' ) ) ); + $environment->addFunction( new \Twig\TwigFunction( 'action', 'do_action' ) ); + emulsify_register_wordpress_text_test_filters( $environment ); + $environment->addFilter( new \Twig\TwigFilter( 'resize', static function ( $value ) { return $value; } ) ); + $environment->addFilter( new \Twig\TwigFilter( 'wpautop', static function ( $value ) { return $value; }, array( 'is_safe' => array( 'html' ) ) ) ); + $integration->extensions( $environment ); + $core = $environment->getExtension( \Twig\Extension\CoreExtension::class ); + $core->setTimezone( 'UTC' ); + $environment->addFilter( + new \Twig\TwigFilter( + 'date', + static function ( $date, $format = null, $timezone = null ) use ( $core ): string { + return $core->formatDate( 'now' === $date ? new DateTimeImmutable( '2026-10-22T12:00:00Z' ) : $date, $format, $timezone ); + } + ) + ); + + foreach ( array( false, true ) as $has_title ) { + foreach ( array( false, true ) as $has_menu ) { + $suffix = ( $has_title ? 'title' : 'no-title' ) . '-' . ( $has_menu ? 'menu' : 'no-menu' ); + + foreach ( array( false, true ) as $has_content ) { + $template = $has_content ? 'content-fixture.twig' : '@emulsify-tpl/layouts/base.twig'; + $output = $environment->render( $template, emulsify_extension_context( $has_title, $has_menu, $has_content ) ); + if ( ! $has_content && $environment->render( 'content-fixture.twig', emulsify_extension_context( $has_title, $has_menu, false ) ) !== $output ) { + throw new RuntimeException( 'An empty child content block must preserve the direct base output.' ); + } + emulsify_extension_golden( 'content-' . $suffix . '-' . ( $has_content ? 'populated' : 'empty' ), $output, $capture ); + } + } + } + + foreach ( array( false, true ) as $has_post ) { + $context = emulsify_extension_context( false, true, $has_post ); + $context['post'] = $has_post ? array( 'id' => 42, 'type' => 'page', 'title' => 'Post <title> & fixture', 'content' => $context['fixture_content'] ) : null; + emulsify_extension_golden( $has_post ? 'page-post' : 'page-no-post', $environment->render( '@emulsify-tpl/page.twig', $context ), $capture ); + } + + $errors = array(); + // These supplied entities model WordPress output; real texturize/KSES lives in the WordPress fixture. + $formatted_title = 'Don’t “panic” & relax'; + $visible_title = 'Don’t “panic” & relax'; + $text_context = emulsify_extension_context( true, true, false ); + $text_context['site']['name'] = 'Ben & Jerry's'; + $text_context['title'] = 'Search results for Tom & Jerry "live"'; + $text_context['menu']['get_items'][0]['title'] = $formatted_title; + $text_context['post'] = array( + 'id' => 42, + 'title' => $formatted_title, + 'content' => '', + 'link' => '/formatted/', + 'author' => array( 'name' => 'Rock 'n' Roll & Blues', 'path' => '/author/' ), + 'thumbnail' => array( 'src' => '/thumbnail.jpg', 'alt' => '' ), + 'comments' => array( array( 'id' => 1, 'author' => array( 'name' => 'Ben & Jerry's' ) ) ), + ); + $dom = static function ( string $html ): DOMXPath { + $document = new DOMDocument(); + $previous = libxml_use_internal_errors( true ); + $document->loadHTML( '<!doctype html><html><head><meta charset="UTF-8"></head><body>' . $html . '</body></html>' ); + libxml_clear_errors(); + libxml_use_internal_errors( $previous ); + return new DOMXPath( $document ); + }; + foreach ( array( 'page.twig', 'single.twig', 'partials/tease.twig' ) as $text_template ) { + $text_output = $environment->render( '@emulsify-tpl/' . $text_template, $text_context ); + $text_dom = $dom( $text_output ); + $post_titles = $text_dom->query( '//h1[contains(@class, "entry__title")]|//h2[contains(@class, "teaser__title")]/a' ); + emulsify_extension_expect( 1 === $post_titles->length && $visible_title === trim( $post_titles->item( 0 )->textContent ), $text_template . ' must show WordPress-formatted post titles as visible characters once.', $errors ); + if ( 'page.twig' !== $text_template ) { + $image = $text_dom->query( '//img' )->item( 0 ); + emulsify_extension_expect( null !== $image && $visible_title === $image->getAttribute( 'alt' ), $text_template . ' must use the post title as an alt fallback without literal entities.', $errors ); + } + if ( 'single.twig' === $text_template ) { + $author = $text_dom->query( '//span[contains(@class, "entry__author")]/a' )->item( 0 ); + emulsify_extension_expect( null !== $author && "Rock 'n' Roll & Blues" === trim( $author->textContent ), 'Post author names must show visible punctuation and ampersands once.', $errors ); + $comment_author = $text_dom->query( '//h3[contains(@class, "comment__author")]' )->item( 0 ); + emulsify_extension_expect( null !== $comment_author && "Ben & Jerry's" === trim( $comment_author->textContent ), 'Comment author names must show visible punctuation and ampersands once.', $errors ); + } + } + $text_dom = $dom( $environment->render( 'content-fixture.twig', $text_context ) ); + foreach ( array( '//a[contains(@class, "site-header__brand")]' => "Ben & Jerry's", '//footer//p' => "© 2026 Ben & Jerry's", '//h1[contains(@class, "page-header__title")]' => 'Search results for Tom & Jerry "live"', '//nav//a[@aria-current="page"]' => $visible_title ) as $query => $visible ) { + $node = $text_dom->query( $query )->item( 0 ); + emulsify_extension_expect( null !== $node && $visible === trim( $node->textContent ), 'WordPress-formatted text must remain readable in ' . $query . '.', $errors ); + } + foreach ( array( '<em>Raw</em> & "alt"' => 'Raw & "alt"', '<em>Encoded</em> & "alt"' => '<em>Encoded</em> & "alt"', '<strong>Helpful</strong><script>alert(1)</script><img src=x onerror=alert(1)> & "quoted"' => 'Helpful & "quoted"' ) as $alt => $plain_alt ) { + $text_context['post']['thumbnail']['alt'] = $alt; + foreach ( array( 'single.twig', 'partials/tease.twig' ) as $text_template ) { + $image_dom = $dom( $environment->render( '@emulsify-tpl/' . $text_template, $text_context ) ); + $image = $image_dom->query( '//img' )->item( 0 ); + emulsify_extension_expect( null !== $image && $plain_alt === $image->getAttribute( 'alt' ), $text_template . ' must strip literal alt markup, keep encoded markup inert, and show entities once.', $errors ); + emulsify_extension_expect( 1 === $image_dom->query( '//img' )->length && 0 === $image_dom->query( '//script|//*[@onerror]' )->length, $text_template . ' alt text must never introduce elements or event-handler attributes.', $errors ); + } + } + foreach ( array( 'tease.twig', 'tease-post.twig' ) as $teaser_template ) { + foreach ( array( 'manual', 'automatic' ) as $excerpt_source ) { + foreach ( array( false, true ) as $protected ) { + $secret = 'protected-' . $excerpt_source . '-excerpt-secret'; + $post = new class( $protected, $secret ) { + public $password_required; + public $excerpt_reads = 0; + private $summary; + + public function __construct( bool $protected, string $summary ) { + $this->password_required = $protected; + $this->summary = $summary; + } + + public function excerpt( array $options = array() ): string { + ++$this->excerpt_reads; + return $this->summary; + } + }; + $teaser = $environment->render( '@emulsify-tpl/partials/' . $teaser_template, array( 'post' => $post ) ); + emulsify_extension_expect( $protected ? false === strpos( $teaser, $secret ) && 0 === $post->excerpt_reads : false !== strpos( $teaser, $secret ) && $post->excerpt_reads > 0, $teaser_template . ' must skip ' . $excerpt_source . ' excerpts entirely while a password is required and retain them after unlock.', $errors ); + } + } + } + + $password_context = emulsify_extension_context( false, true, false ); + $password_context['site']['link'] = 'https://example.test'; + $password_context['post'] = array( 'id' => 73, 'password_required' => true, 'content' => 'protected-content-secret', 'excerpt' => 'protected-excerpt-secret' ); + $GLOBALS['emulsify_extension_password_form_posts'] = array(); + $GLOBALS['emulsify_extension_title_posts'] = array(); + $GLOBALS['emulsify_extension_hooks'] = array(); + $password_output = $environment->render( '@emulsify-tpl/single-password.twig', $password_context ); + emulsify_extension_expect( array( 73 ) === $GLOBALS['emulsify_extension_password_form_posts'], 'The password template must request WordPress\'s form for the current post ID.', $errors ); + emulsify_extension_expect( array( 73 ) === $GLOBALS['emulsify_extension_title_posts'] && false !== strpos( $password_output, '>Protected: Secret <title> & fixture</h1>' ), 'The password template must display WordPress\'s protected title while preserving title autoescaping.', $errors ); + emulsify_extension_expect( false !== strpos( $password_output, '<form class="post-password-form" data-filtered-password-form="true" action="https://example.test/wordpress/wp-login.php?action=postpass"' ) && false === strpos( $password_output, '<form'), 'The password template must preserve trusted core/plugin form markup and the site URL instead of building a home-URL action.', $errors ); + emulsify_extension_expect( false === strpos( $password_output, 'protected-content-secret' ) && false === strpos( $password_output, 'protected-excerpt-secret' ), 'The password template must never print protected content or excerpts.', $errors ); + emulsify_extension_expect( array( 'get_header', 'wp_head', 'wp_body_open', 'get_footer', 'wp_footer' ) === $GLOBALS['emulsify_extension_hooks'], 'The password template must preserve structural WordPress hooks and their order.', $errors ); + emulsify_extension_expect( strpos( $password_output, '<!-- action:get_footer -->' ) < strpos( $password_output, '<footer ' ) && strpos( $password_output, '<footer ' ) < strpos( $password_output, '<!-- wp_footer -->' ), 'get_footer must run before rendering footer markup, and wp_footer must run afterward.', $errors ); + $password_marker = '<!-- child password content -->'; + $fixtures->setTemplate( 'child-password-content.twig', '{% extends "@emulsify-tpl/single-password.twig" %}{% block content %}' . $password_marker . '{{ parent() }}{% endblock %}' ); + $password_child = $environment->render( 'child-password-content.twig', $password_context ); + emulsify_extension_expect( 1 === substr_count( $password_child, $password_marker ) && str_replace( $password_marker, '', $password_child ) === $password_output, 'Child password templates must retain the public content block and surrounding parent markup.', $errors ); + + $rtl_context = emulsify_extension_context( true, true, true ); + $rtl_context['site']['language_attributes'] = 'lang="ar" dir="rtl"'; + $rtl_output = $environment->render( 'content-fixture.twig', $rtl_context ); + emulsify_extension_expect( false !== strpos( $rtl_output, '<html lang="ar" dir="rtl">' ), 'Plain WordPress language attributes must preserve the language and RTL direction without escaping their quotes.', $errors ); + emulsify_extension_expect( false !== strpos( $rtl_output, 'Fixture <site> & WordPress' ) && false !== strpos( $rtl_output, 'Page <title> & fixture' ), 'Trusting the core language attribute fragment must preserve autoescaping for site names and page titles.', $errors ); + $page_expected = file_get_contents( __DIR__ . '/../fixtures/template-extension/page-post.html' ); + $child_template = get_stylesheet_directory() . '/templates/page.twig'; + $child_before = '<!-- child page namespace start -->'; + $child_after = '<!-- child page namespace end -->'; + $context = emulsify_extension_context( false, true, true ); + $context['post'] = array( 'id' => 42, 'type' => 'page', 'title' => 'Post <title> & fixture', 'content' => $context['fixture_content'] ); + + try { + if ( false === file_put_contents( $child_template, '{% extends "@emulsify-tpl/page.twig" %}{% block content %}' . $child_before . '{{ parent() }}' . $child_after . '{% endblock %}' ) ) { + throw new RuntimeException( 'Could not write the disposable child page template.' ); + } + $output = $environment->render( '@templates/page.twig', $context ); + emulsify_extension_expect( 1 === substr_count( $output, $child_before ) && 1 === substr_count( $output, $child_after ), 'The child-first namespace must select the physical child page override exactly once.', $errors ); + emulsify_extension_expect( str_replace( array( $child_before, $child_after ), '', $output ) === $page_expected, 'The physical child page override must preserve every surrounding parent-page byte.', $errors ); + } finally { + if ( is_file( $child_template ) ) { + unlink( $child_template ); + } + // Refresh filesystem lookup caches after removing the temporary override. + $environment->setLoader( new \Twig\Loader\ChainLoader( array( $fixtures, $integration->loader_paths( new \Twig\Loader\FilesystemLoader() ) ) ) ); + } + emulsify_extension_expect( $environment->render( '@templates/page.twig', $context ) === $page_expected, 'Removing the physical child page override must restore every parent-page byte.', $errors ); + + foreach ( array( 'head', 'header', 'content', 'footer', 'site_header', 'main', 'page_title' ) as $block ) { + $name = 'child-page-' . $block . '.twig'; + $marker = '<!-- child:' . $block . ' -->'; + $fixtures->setTemplate( $name, '{% extends "@emulsify-tpl/page.twig" %}{% block ' . $block . ' %}' . $marker . '{{ parent() }}{% endblock %}' ); + $context = emulsify_extension_context( false, true, true ); + $context['post'] = array( 'id' => 42, 'type' => 'page', 'title' => 'Post <title> & fixture', 'content' => $context['fixture_content'] ); + $output = $environment->render( $name, $context ); + emulsify_extension_expect( 1 === substr_count( $output, $marker ), 'A child page must override the ' . $block . ' block exactly once.', $errors ); + emulsify_extension_expect( str_replace( $marker, '', $output ) === $page_expected, 'The ' . $block . ' override with parent() must preserve every surrounding parent-page byte.', $errors ); + } + + $replacement_cases = array( + 'site_header' => array( 'absent' => array( '<header class="site-header"', '<nav ' ), 'present' => array( '<main class="site-main"', '<header class="page-header"', '<p>Content & fixture</p>', '<footer ' ) ), + 'main' => array( 'absent' => array( '<main ', '<header class="page-header"', '<p>Content & fixture</p>' ), 'present' => array( '<header class="site-header"', '<footer ', 'href="#content"' ) ), + 'page_title' => array( 'absent' => array( '<header class="page-header"' ), 'present' => array( '<header class="site-header"', '<main class="site-main"', '<p>Content & fixture</p>', '<footer ' ) ), + 'footer' => array( 'absent' => array( '<footer ' ), 'present' => array( '<header class="site-header"', '<main class="site-main"', '<p>Content & fixture</p>' ) ), + ); + $hooks_expected = array( 'get_header', 'wp_head', 'wp_body_open', 'get_footer', 'wp_footer' ); + + foreach ( $replacement_cases as $block => $fragments ) { + $name = 'replace-' . $block . '.twig'; + $marker = '<!-- replacement:' . $block . ' -->'; + $fixtures->setTemplate( $name, '{% extends "content-fixture.twig" %}{% block ' . $block . ' %}' . $marker . '{% endblock %}' ); + $GLOBALS['emulsify_extension_hooks'] = array(); + $output = $environment->render( $name, emulsify_extension_context( true, true, true ) ); + emulsify_extension_expect( 1 === substr_count( $output, $marker ), 'Replacing ' . $block . ' must render the child block.', $errors ); + foreach ( $fragments['absent'] as $fragment ) { + emulsify_extension_expect( false === strpos( $output, $fragment ), 'Replacing ' . $block . ' must remove its complete wrapper/content: ' . $fragment, $errors ); + } + foreach ( $fragments['present'] as $fragment ) { + emulsify_extension_expect( false !== strpos( $output, $fragment ), 'Replacing ' . $block . ' must preserve its surrounding markup: ' . $fragment, $errors ); + } + emulsify_extension_expect( $hooks_expected === $GLOBALS['emulsify_extension_hooks'], 'Replacing ' . $block . ' must preserve the structural WordPress hooks and their order.', $errors ); + if ( 'footer' === $block ) { + emulsify_extension_expect( strpos( $output, '<!-- action:get_footer -->' ) < strpos( $output, $marker ) && strpos( $output, $marker ) < strpos( $output, '<!-- wp_footer -->' ), 'Replacing the footer block must retain get_footer before the child markup and wp_footer afterward.', $errors ); + } + emulsify_extension_expect( 1 === substr_count( $output, 'href="#content"' ), 'Replacing ' . $block . ' must preserve the skip link outside the block.', $errors ); + } + + foreach ( array( 'site_header' => 'header', 'main' => 'page_title' ) as $outer => $inner ) { + $name = 'nested-' . $outer . '.twig'; + $outer_marker = '<!-- outer:' . $outer . ' -->'; + $inner_marker = '<!-- inner:' . $inner . ' -->'; + $fixtures->setTemplate( $name, '{% extends "content-fixture.twig" %}{% block ' . $outer . ' %}' . $outer_marker . '{% endblock %}{% block ' . $inner . ' %}' . $inner_marker . '{% endblock %}' ); + $output = $environment->render( $name, emulsify_extension_context( true, true, true ) ); + emulsify_extension_expect( 1 === substr_count( $output, $outer_marker ) && false === strpos( $output, $inner_marker ), $inner . ' must remain nested inside ' . $outer . ' and disappear when the enclosing block is replaced.', $errors ); + } + + if ( $errors ) { + throw new RuntimeException( implode( "\n", $errors ) ); + } + echo "PASS protected teaser excerpts, native password forms and child inheritance, plain language attributes, RTL, other field autoescaping, physical child page lookup and restoration, child page inheritance, seven block names, replacement boundaries, nested blocks, and structural WordPress hooks.\n"; +} catch ( Throwable $throwable ) { + fwrite( STDERR, $throwable->getMessage() . "\n" ); + $exit_code = 1; +} finally { + if ( is_dir( get_stylesheet_directory() . '/templates' ) ) { + rmdir( get_stylesheet_directory() . '/templates' ); + } + if ( is_dir( get_stylesheet_directory() ) ) { + rmdir( get_stylesheet_directory() ); + } +} + +if ( 0 === $exit_code ) { + // Controller stubs need their own process, separate from real Timber/Twig. + passthru( escapeshellarg( PHP_BINARY ) . ' ' . escapeshellarg( __DIR__ . '/template-routing-smoke.php' ), $exit_code ); +} + +exit( $exit_code ); diff --git a/.github/scripts/template-routing-smoke.php b/.github/scripts/template-routing-smoke.php new file mode 100644 index 0000000..f74b514 --- /dev/null +++ b/.github/scripts/template-routing-smoke.php @@ -0,0 +1,114 @@ +<?php +/** + * Exercises PHP route controllers without depending on the main query's posts. + * + * @package Emulsify + */ + +namespace Timber { + final class Timber { + public static array $context = array(); + public static array $rendered = array(); + + public static function context( array $extra = array() ): array { + return array_merge( self::$context, $extra ); + } + + public static function render( $templates, array $context ): void { + self::$rendered = array( 'templates' => (array) $templates, 'context' => $context ); + } + } +} + +namespace { + if ( PHP_SAPI !== 'cli' ) { + fwrite( STDERR, "This script must be run from the command line.\n" ); + exit( 1 ); + } + + define( 'ABSPATH', __DIR__ ); + $GLOBALS['emulsify_route_state'] = array(); + $failures = array(); + + function is_home(): bool { return ! empty( $GLOBALS['emulsify_route_state']['home'] ); } + function is_front_page(): bool { return ! empty( $GLOBALS['emulsify_route_state']['front'] ); } + function is_day(): bool { return ! empty( $GLOBALS['emulsify_route_state']['day'] ); } + function is_month(): bool { return ! empty( $GLOBALS['emulsify_route_state']['month'] ); } + function is_year(): bool { return ! empty( $GLOBALS['emulsify_route_state']['year'] ); } + function is_tag(): bool { return false; } + function is_category(): bool { return false; } + function is_post_type_archive(): bool { return ! empty( $GLOBALS['emulsify_route_state']['post_type_archive'] ); } + function post_password_required( $post ): bool { + $GLOBALS['emulsify_route_state']['password_checked'][] = $post; + return ! empty( $GLOBALS['emulsify_route_state']['protected'] ); + } + function __( string $text, string $domain ): string { return $text; } + function post_type_archive_title( string $prefix = '', bool $display = true ): string { return 'Books'; } + function get_post_type() { return $GLOBALS['emulsify_route_state']['current_post_type'] ?? false; } + function get_query_var( string $key, $default = '' ) { return $GLOBALS['emulsify_route_state']['query'][ $key ] ?? $default; } + function get_option( string $key ) { return $GLOBALS['emulsify_route_state']['options'][ $key ] ?? ''; } + function get_the_date( string $format = '' ): string { + $GLOBALS['emulsify_route_state']['date_calls'][] = $format; + return gmdate( $format ?: 'F j, Y', gmmktime( 12, 0, 0, 10, 29, 2026 ) ); + } + + function routing_render( string $controller, array $state = array() ): array { + $GLOBALS['emulsify_route_state'] = $state; + \Timber\Timber::$context = array( 'post' => $state['post'] ?? null, 'fixture' => 'preserved' ); + \Timber\Timber::$rendered = array(); + require dirname( __DIR__, 2 ) . '/' . $controller; + return \Timber\Timber::$rendered; + } + + function routing_expect( bool $condition, string $message ): void { + global $failures; + if ( ! $condition ) { + $failures[] = $message; + } + } + + // Front-page hierarchy is independent of whether the route contains posts. + $post = (object) array( 'ID' => 42 ); + $front_posts = routing_render( 'index.php', array( 'front' => true, 'home' => true ) ); + routing_expect( array( '@templates/front-page.twig', '@templates/home.twig', '@templates/index.twig' ) === $front_posts['templates'], 'A posts front page must prefer front-page, home, then index.' ); + $posts_page = routing_render( 'index.php', array( 'front' => false, 'home' => true ) ); + routing_expect( array( '@templates/home.twig', '@templates/index.twig' ) === $posts_page['templates'], 'A separate posts page must never choose front-page.twig.' ); + $generic = routing_render( 'index.php' ); + routing_expect( array( '@templates/index.twig' ) === $generic['templates'], 'Other index routes must keep their generic fallback.' ); + $front_page = routing_render( 'page.php', array( 'front' => true, 'post' => $post ) ); + routing_expect( array( '@templates/front-page.twig', '@templates/page.twig' ) === $front_page['templates'], 'A static front page must prefer front-page.twig over page.twig.' ); + $ordinary_page = routing_render( 'page.php', array( 'post' => $post ) ); + routing_expect( array( '@templates/page.twig' ) === $ordinary_page['templates'], 'An ordinary page must keep page.twig.' ); + foreach ( array( false, true ) as $front ) { + $protected = routing_render( 'page.php', array( 'front' => $front, 'protected' => true, 'post' => $post ) ); + routing_expect( array( '@templates/single-password.twig' ) === $protected['templates'], 'A protected page must bypass all normal/front-page templates.' ); + routing_expect( array( 42 ) === $GLOBALS['emulsify_route_state']['password_checked'], 'Page routing must check the current post password.' ); + } + routing_expect( 'preserved' === $front_page['context']['fixture'] && $post === $front_page['context']['post'], 'Route selection must preserve Timber context.' ); + + // Archive routing must use the query, including when no current post exists. + foreach ( array( 'book', array( 'book' ), array( '', 'book' ) ) as $post_type ) { + $archive = routing_render( 'archive.php', array( 'post_type_archive' => true, 'query' => array( 'post_type' => $post_type ) ) ); + routing_expect( array( '@templates/archive-book.twig', '@templates/archive.twig', '@templates/index.twig' ) === $archive['templates'], 'An empty single-type archive must choose archive-book.twig from its query.' ); + routing_expect( 'Books' === $archive['context']['title'], 'Custom post type archive titles must stay intact.' ); + } + foreach ( array( '', array(), array( 'book', 'film' ) ) as $post_type ) { + $archive = routing_render( 'archive.php', array( 'post_type_archive' => true, 'query' => array( 'post_type' => $post_type ) ) ); + routing_expect( array( '@templates/archive.twig', '@templates/index.twig' ) === $archive['templates'], 'Absent or multiple post types must use generic archive fallbacks, matching WordPress.' ); + } + $archive = routing_render( 'archive.php', array( 'post_type_archive' => true, 'current_post_type' => 'film', 'query' => array( 'post_type' => 'book' ) ) ); + routing_expect( '@templates/archive-book.twig' === $archive['templates'][0], 'The queried post type must win over a stray global post.' ); + $day = routing_render( 'archive.php', array( 'day' => true, 'options' => array( 'date_format' => 'd/m/Y' ) ) ); + routing_expect( 'Archive: 29/10/2026' === $day['context']['title'], 'Day archive titles must use the configured date format, including the day of the month.' ); + routing_expect( array( 'd/m/Y' ) === $GLOBALS['emulsify_route_state']['date_calls'], 'Day archives must pass the site date format to WordPress.' ); + $month = routing_render( 'archive.php', array( 'month' => true ) ); + routing_expect( 'Archive: Oct 2026' === $month['context']['title'], 'Month archive formatting must remain unchanged.' ); + $year = routing_render( 'archive.php', array( 'year' => true ) ); + routing_expect( 'Archive: 2026' === $year['context']['title'], 'Year archive formatting must remain unchanged.' ); + + if ( $failures ) { + fwrite( STDERR, implode( "\n", $failures ) . "\n" ); + exit( 1 ); + } + echo "Template routing smoke checks passed.\n"; +} diff --git a/.github/scripts/theme-filters-smoke.php b/.github/scripts/theme-filters-smoke.php index 240f72f..a19008c 100644 --- a/.github/scripts/theme-filters-smoke.php +++ b/.github/scripts/theme-filters-smoke.php @@ -140,6 +140,7 @@ public function parent() { if ( ! function_exists( 'get_body_class' ) ) { function get_body_class(): array { + $GLOBALS['emulsify_filter_body_calls'] = ( $GLOBALS['emulsify_filter_body_calls'] ?? 0 ) + 1; return array( 'filter-smoke' ); } } @@ -176,6 +177,7 @@ function wp_login_url(): string { if ( ! function_exists( 'wp_logout_url' ) ) { function wp_logout_url(): string { + $GLOBALS['emulsify_filter_logout_calls'] = ( $GLOBALS['emulsify_filter_logout_calls'] ?? 0 ) + 1; return 'https://example.test/wp-login.php?action=logout'; } } @@ -313,6 +315,7 @@ function emulsify_filter_smoke_remove( string $path ): void { require_once $repo_root . '/includes/Support/AssetManifest.php'; require_once $repo_root . '/includes/Support/ProjectConfig.php'; require_once $repo_root . '/includes/Runtime/Assets.php'; + require_once $repo_root . '/includes/Support/LogoutUrl.php'; require_once $repo_root . '/includes/Runtime/Context.php'; require_once $repo_root . '/includes/Runtime/Setup.php'; require_once $repo_root . '/includes/Runtime/Twig.php'; @@ -479,8 +482,25 @@ public function addPath( string $path, string $namespace ): void { 'Twig namespace filter should add a project namespace.' ); + $GLOBALS['emulsify_filter_body_calls'] = 0; + $GLOBALS['emulsify_filter_logout_calls'] = 0; $context = ( new Emulsify\Theme\Runtime\Context() )->add( array() ); + emulsify_filter_smoke_assert( 1 === $GLOBALS['emulsify_filter_body_calls'], 'Global context must compute body classes only once.' ); + emulsify_filter_smoke_assert( 0 === $GLOBALS['emulsify_filter_logout_calls'], 'Unused logout URLs must not create a nonce.' ); + emulsify_filter_smoke_assert( 'filter-smoke' === $context['body_class'] && 'filter-smoke' === $context['wp']['body_class'], 'Both body-class context keys must remain available.' ); + $restored_url = unserialize( serialize( $context['wp']['logout_url'] ) ); + emulsify_filter_smoke_assert( 0 === $GLOBALS['emulsify_filter_logout_calls'], 'Serializing unused context must not force nonce creation.' ); + emulsify_filter_smoke_assert( 'https://example.test/wp-login.php?action=logout' === (string) $restored_url, 'PHP context caches must retain a usable logout URL.' ); + $GLOBALS['emulsify_filter_logout_calls'] = 0; + $custom_context = ( new Emulsify\Theme\Runtime\Context() )->add( array( 'body_class' => 'project-body' ) ); + emulsify_filter_smoke_assert( 'project-body' === $custom_context['body_class'] && 'filter-smoke' === $custom_context['wp']['body_class'], 'An inherited body class must not replace the native WordPress helper value.' ); + require_once $repo_root . '/vendor/autoload.php'; + $twig = new \Twig\Environment( new \Twig\Loader\ArrayLoader( array( 'logout' => '{{ wp.logout_url }}|{{ wp.logout_url }}' ) ), array( 'autoescape' => 'html' ) ); + emulsify_filter_smoke_assert( 'https://example.test/wp-login.php?action=logout|https://example.test/wp-login.php?action=logout' === $twig->render( 'logout', $context ), 'Twig must render the lazy logout URL as text.' ); + emulsify_filter_smoke_assert( 1 === $GLOBALS['emulsify_filter_logout_calls'], 'Repeated logout URL reads must compute its nonce only once.' ); + emulsify_filter_smoke_assert( 'https://example.test/wp-login.php?action=logout' === json_decode( json_encode( $context['wp']['logout_url'] ), true ), 'JSON consumers must receive the logout URL text.' ); + emulsify_filter_smoke_assert( true === $context['project_flag'], 'Context filter should add project context values.' diff --git a/.github/scripts/theme-json-style-contract.cjs b/.github/scripts/theme-json-style-contract.cjs new file mode 100644 index 0000000..6cb2adc --- /dev/null +++ b/.github/scripts/theme-json-style-contract.cjs @@ -0,0 +1,82 @@ +const fs = require('node:fs'); +const path = require('node:path'); + +const PRESET_PATHS = { + color: ['color', 'palette'], + 'font-size': ['typography', 'fontSizes'], + 'font-family': ['typography', 'fontFamilies'], + spacing: ['spacing', 'spacingSizes'], + gradient: ['color', 'gradients'], + shadow: ['shadow', 'presets'], + 'aspect-ratio': ['dimensions', 'aspectRatios'], +}; + +// Scalar leaves from WordPress 6.8 WP_Theme_JSON's style property mappings. +// Radius, spacing, block gap and background image also accept nested objects. +const SCALAR_PATHS = [ + 'background.backgroundPosition', 'background.backgroundRepeat', + 'background.backgroundSize', 'background.backgroundAttachment', + 'background.backgroundImage.url', + 'color.background', 'color.text', 'color.gradient', + 'dimensions.aspectRatio', 'dimensions.minHeight', 'filter.duotone', + 'layout.contentSize', 'layout.wideSize', + ...['color', 'style', 'width'].flatMap((property) => [ + `border.${property}`, + ...['top', 'right', 'bottom', 'left'].map((side) => `border.${side}.${property}`), + ]), + ...['topLeft', 'topRight', 'bottomLeft', 'bottomRight'].map((corner) => `border.radius.${corner}`), + ...['color', 'offset', 'style', 'width'].map((property) => `outline.${property}`), + ...['margin', 'padding'].flatMap((property) => + ['top', 'right', 'bottom', 'left'].map((side) => `spacing.${property}.${side}`)), + 'spacing.blockGap.top', 'spacing.blockGap.left', 'shadow', + ...['fontFamily', 'fontSize', 'fontStyle', 'fontWeight', 'letterSpacing', + 'lineHeight', 'textAlign', 'textColumns', 'textDecoration', 'textTransform', + 'writingMode'].map((property) => `typography.${property}`), +]; + +function validateThemeJsonStyles(theme) { + const errors = []; + + function visit(value, segments, settings, stylePath = []) { + const location = segments.join('.'); + if (value !== null && typeof value === 'object') { + if (SCALAR_PATHS.includes(stylePath.join('.'))) { + errors.push(`${location} must be a single style value, not an object or array.`); + } + for (const [key, child] of Object.entries(value)) { + const childSettings = segments.at(-1) === 'blocks' + ? [theme.settings?.blocks?.[key], ...settings] + : settings; + const startsStyle = ['blocks', 'elements', 'variations'].includes(stylePath.at(-1)) || key.startsWith(':'); + visit(child, [...segments, key], childSettings, startsStyle ? [] : [...stylePath, key]); + } + return; + } + if (typeof value !== 'string') return; + if (value.includes('---wp')) errors.push(`${location} uses the malformed ---wp custom-property prefix.`); + for (const match of value.matchAll(/var\(\s*--wp--preset--([a-z-]+?)--([A-Za-z0-9_-]+)/g)) { + const [, type, slug] = match; + const presetPath = PRESET_PATHS[type]; + const defined = presetPath && settings.some((scope) => { + const presets = presetPath.reduce((entry, key) => entry?.[key], scope); + return Array.isArray(presets) && presets.some((preset) => String(preset.slug) === slug); + }); + if (!defined) errors.push(`${location} references undefined preset --wp--preset--${type}--${slug}.`); + } + } + + visit(theme.styles || {}, ['styles'], [theme.settings]); + return errors; +} + +if (require.main === module) { + const filename = path.resolve(process.argv[2] || path.join(__dirname, '../../theme.json')); + const errors = validateThemeJsonStyles(JSON.parse(fs.readFileSync(filename, 'utf8'))); + if (errors.length) { + console.error(errors.join('\n')); + process.exitCode = 1; + } + else console.log('theme.json style values and preset references are valid.'); +} + +module.exports = { validateThemeJsonStyles }; diff --git a/.github/scripts/theme-json-style-contract.test.cjs b/.github/scripts/theme-json-style-contract.test.cjs new file mode 100644 index 0000000..473e4f9 --- /dev/null +++ b/.github/scripts/theme-json-style-contract.test.cjs @@ -0,0 +1,97 @@ +const assert = require('node:assert/strict'); +const test = require('node:test'); +const { validateThemeJsonStyles } = require('./theme-json-style-contract.cjs'); + +function fixture() { + return { + settings: { + color: { palette: [{ slug: 'brand', color: '#123456' }] }, + typography: { + fontSizes: [{ slug: 'large', size: '2rem' }], + fontFamilies: [{ slug: 'primary', fontFamily: 'sans-serif' }], + }, + spacing: { spacingSizes: [{ slug: '4', size: '1rem' }] }, + }, + styles: { + color: { text: 'var(--wp--preset--color--brand)' }, + typography: { + fontSize: 'var(--wp--preset--font-size--large)', + fontFamily: 'var(--wp--preset--font-family--primary)', + }, + spacing: { padding: { top: 'var(--wp--preset--spacing--4)' } }, + }, + }; +} + +test('accepts defined color, font size, font family and spacing presets', () => { + assert.deepEqual(validateThemeJsonStyles(fixture()), []); +}); + +test('rejects undefined references for every required preset type', () => { + for (const type of ['color', 'font-size', 'font-family', 'spacing']) { + const theme = fixture(); + theme.styles.elements = { link: { ':hover': { color: { text: `var(--wp--preset--${type}--missing)` } } } }; + assert.deepEqual(validateThemeJsonStyles(theme), [ + `styles.elements.link.:hover.color.text references undefined preset --wp--preset--${type}--missing.`, + ]); + } +}); + +test('checks every reference in composite CSS values, including fallback values', () => { + const theme = fixture(); + theme.styles.spacing.margin = 'calc(var( --wp--preset--spacing--4) + var(--wp--preset--spacing--missing, var(--wp--preset--spacing--absent)))'; + assert.equal(validateThemeJsonStyles(theme).length, 2); +}); + +test('rejects malformed WordPress custom-property prefixes', () => { + const theme = fixture(); + theme.styles.color.text = 'var(---wp--preset--color--brand)'; + assert.match(validateThemeJsonStyles(theme)[0], /malformed ---wp/); +}); + +test('rejects objects and arrays in scalar style properties at every nesting level', () => { + for (const invalid of [{ text: '#fff' }, []]) { + const theme = fixture(); + theme.styles.blocks = { + 'core/button': { border: { color: invalid } }, + 'core/quote': { + elements: { cite: { typography: { fontSize: invalid } } }, + border: { bottom: { width: invalid } }, + spacing: { margin: { top: invalid } }, + }, + }; + const errors = validateThemeJsonStyles(theme); + assert.equal(errors.length, 4); + assert.ok(errors.every((error) => error.includes('must be a single style value'))); + } +}); + +test('accepts legitimate nested border, spacing, background and element containers', () => { + const theme = fixture(); + theme.styles.blocks = { + 'core/button': { + border: { color: '#fff', top: { color: '#000', width: '1px', style: 'solid' }, radius: { topLeft: '2px', bottomRight: '3px' } }, + background: { backgroundImage: { url: 'https://example.org/image.png', source: 'file' } }, + spacing: { margin: { bottom: '0' }, padding: '1rem', blockGap: { top: '1rem', left: '2rem' } }, + elements: { link: { ':focus': { outline: { color: '#000', width: '2px' } } } }, + variations: { shadow: { shadow: '0 1px 2px #000', color: { text: '#000' } } }, + }, + }; + assert.deepEqual(validateThemeJsonStyles(theme), []); +}); + +test('accepts block-specific presets only in their block scope', () => { + const theme = fixture(); + theme.settings.blocks = { 'core/button': { color: { palette: [{ slug: 'button', color: '#000' }] } } }; + theme.styles.blocks = { 'core/button': { color: { text: 'var(--wp--preset--color--button)' } } }; + assert.deepEqual(validateThemeJsonStyles(theme), []); + theme.styles.color.text = 'var(--wp--preset--color--button)'; + assert.equal(validateThemeJsonStyles(theme).length, 1); +}); + +test('leaves settings metadata and custom variables outside the style-value contract', () => { + const theme = fixture(); + theme.settings.custom = { example: 'var(--wp--preset--color--missing)' }; + theme.styles.color.background = 'var(--project-background, #fff)'; + assert.deepEqual(validateThemeJsonStyles(theme), []); +}); diff --git a/.github/scripts/twig-autoescape-smoke.php b/.github/scripts/twig-autoescape-smoke.php index 4d55ac9..c21d43d 100644 --- a/.github/scripts/twig-autoescape-smoke.php +++ b/.github/scripts/twig-autoescape-smoke.php @@ -20,6 +20,7 @@ require_once $autoload; use Emulsify\Theme\Runtime\Twig; +use Emulsify\Theme\Blocks\CoreBlockTwigRenderer; /** * Fails the smoke test with a useful message. @@ -58,10 +59,7 @@ function emulsify_twig_autoescape_fail( string $message ): void { new \Twig\TwigFunction( $name, $definition['callable'], - array( - 'is_safe' => $definition['is_safe'] ?? array(), - 'needs_context' => $definition['needs_context'] ?? false, - ) + $definition['options'] ?? array() ) ); } @@ -93,4 +91,89 @@ function emulsify_twig_autoescape_fail( string $message ): void { emulsify_twig_autoescape_fail( 'Twig rendered a literal script element from a hostile field value.' ); } -echo "Twig autoescape smoke checks passed; field values were escaped and attribute helpers remained safe HTML.\n"; +/** + * Minimal Timber adapter delegating mapped compilation to the real Twig engine. + */ +final class Emulsify_Autoescape_Timber { + /** @var \Twig\Environment Real Twig environment with the parent's helpers. */ + public static $environment; + + /** @return array Inherited Timber context. */ + public static function context_global(): array { + return array( 'attributes' => array( 'data-global' => 'must not leak' ) ); + } + + /** @return null No post is needed by this attribute-safety fixture. */ + public static function get_post( $post = false ) { + return null; + } + + /** + * @param string $template Mapped template. + * @param array $context Renderer context. + * @return string Actual Twig output. + */ + public static function compile( string $template, array $context ): string { + return self::$environment->render( $template, $context ); + } +} + +class_alias( Emulsify_Autoescape_Timber::class, 'Timber\\Timber' ); + +/** @return string Temporary child theme root. */ +function get_stylesheet_directory(): string { + return $GLOBALS['emulsify_autoescape_block_root']; +} + +/** @return string Parent theme root. */ +function get_template_directory(): string { + return dirname( __DIR__, 2 ); +} + +/** + * Supplies a project map without replacing the renderer or helper implementation. + * + * @param string $hook Filter name. + * @param mixed $value Filter value. + * @return mixed Filtered value. + */ +function apply_filters( string $hook, $value ) { + return 'emulsify_theme_core_block_twig_template_map' === $hook ? array( 'core/paragraph' => 'mapped.twig' ) : $value; +} + +$mapped_root = sys_get_temp_dir() . '/emulsify-autoescape-block-' . uniqid( '', true ); +mkdir( $mapped_root ); +$GLOBALS['emulsify_autoescape_block_root'] = $mapped_root; +file_put_contents( $mapped_root . '/mapped.twig', '{% include "mapped-component.twig" %}' ); +file_put_contents( $mapped_root . '/mapped-component.twig', '<div {{ bem("text") }}><section {{ add_attributes({class: "inner"}) }}>{{ content|raw }}</section></div>' ); +$environment->setLoader( new \Twig\Loader\ChainLoader( array( $environment->getLoader(), new \Twig\Loader\FilesystemLoader( $mapped_root ) ) ) ); +Emulsify_Autoescape_Timber::$environment = $environment; + +try { + $renderer = new CoreBlockTwigRenderer(); + $mapped = $renderer->render_block( + '<p id="saved-anchor" class="intro">Hello</p>', + array( + 'blockName' => 'core/paragraph', + 'attrs' => array( + 'onmouseover' => 'alert(document.domain)', + 'level' => 2, + 'className' => 'intro', + 'anchor' => 'saved-anchor', + 'textAlign' => 'center', + ), + ) + ); +} finally { + unlink( $mapped_root . '/mapped.twig' ); + unlink( $mapped_root . '/mapped-component.twig' ); + rmdir( $mapped_root ); + unset( $GLOBALS['emulsify_autoescape_block_root'] ); +} + +$expected_mapped = '<div class="text"><section class="inner"><p id="saved-anchor" class="intro">Hello</p></section></div>'; +if ( $expected_mapped !== $mapped ) { + emulsify_twig_autoescape_fail( "Mapped block data leaked through helper context.\nExpected: " . $expected_mapped . "\nActual: " . $mapped ); +} + +echo "Twig autoescape smoke checks passed; fields were escaped, helper HTML remained safe, and mapped block data did not become HTML attributes.\n"; diff --git a/.github/scripts/twig-helper-contract.cjs b/.github/scripts/twig-helper-contract.cjs new file mode 100644 index 0000000..a60a8f7 --- /dev/null +++ b/.github/scripts/twig-helper-contract.cjs @@ -0,0 +1,60 @@ +#!/usr/bin/env node + +// Characterization only: differing expectations require an explicit reason. +const assert = require('node:assert/strict'); +const fs = require('node:fs'); +const path = require('node:path'); +const { createRequire } = require('node:module'); +const { spawnSync } = require('node:child_process'); +const { pathToFileURL } = require('node:url'); +const { isDeepStrictEqual } = require('node:util'); + +async function main() { + assert.ok(process.argv.length <= 3, 'Usage: node twig-helper-contract.cjs [installed-theme-directory]'); + const project = path.resolve(process.argv[2] || path.join(__dirname, '../../whisk')); + const requireProject = createRequire(path.join(project, 'package.json')); + const core = requireProject('@emulsify/core/package.json'); + const version = core.version.match(/^(\d+)\.(\d+)\.(\d+)$/); + assert.ok(version && (Number(version[1]) > 4 || Number(version[1]) === 4 && Number(version[2]) >= 5), `Core ${core.version} is below the 4.5.0 helper baseline.`); + const { bemAttributes, addAttributes } = await import(pathToFileURL(requireProject.resolve('@emulsify/core/extensions/twig'))); + const corpus = JSON.parse(fs.readFileSync(path.join(__dirname, '../fixtures/twig-helper-contract.json'), 'utf8')); + assert.equal(corpus.schemaVersion, 1, 'Unsupported Twig helper fixture schema.'); + assert.ok(Array.isArray(corpus.cases) && corpus.cases.length > 0, 'Twig helper cases must be a nonempty array.'); + const ids = new Set(); + + for (const fixture of corpus.cases) { + assert.ok(fixture.id && !ids.has(fixture.id), `Duplicate or missing fixture ID: ${fixture.id}`); + ids.add(fixture.id); + assert.ok(['bem', 'add_attributes'].includes(fixture.helper), `${fixture.id}: unknown helper`); + assert.ok(Array.isArray(fixture.args), `${fixture.id}: helper arguments must be an array.`); + const differences = fixture.differences || []; + for (const field of ['attributes', 'html', 'contextAfter']) { + const notes = differences.filter((entry) => entry.field === field); + const same = isDeepStrictEqual(fixture.php[field], fixture.js[field]); + assert.equal(notes.length, same ? 0 : 1, `${fixture.id}: ${field} needs exactly one reason when different, and none when equal.`); + assert.ok(notes.every((entry) => typeof entry.reason === 'string' && entry.reason.trim()), `${fixture.id}: empty difference reason`); + } + assert.ok(differences.every((entry) => ['attributes', 'html', 'contextAfter'].includes(entry.field)), `${fixture.id}: unknown difference field`); + + const values = structuredClone(fixture.context || {}); + const invocation = { context: { ...fixture.contextVars, attributes: fixture.contextKind === 'bag' ? addAttributes(values) : values } }; + const args = fixture.args; + const html = []; + let attributes; + for (let index = 0; index < (fixture.repeat || 1); index += 1) { + attributes = fixture.helper === 'bem' + ? bemAttributes(args[0], args[1], args[2], args[3], args[4], invocation) + : addAttributes(args[0], invocation); + html.push(String(attributes)); + } + const result = { attributes: attributes.toObject(), html: html.join('|'), contextAfter: invocation.context.attributes }; + assert.deepEqual(result, fixture.js, `${fixture.id}: Core helper output changed; review the exact attributes, HTML, and remaining context.`); + } + console.log(`PASS ${corpus.cases.length} JavaScript Twig helper cases on Core ${core.version}.`); + + const php = spawnSync('php', [path.join(__dirname, 'twig-helper-contract.php')], { stdio: 'inherit' }); + if (php.error) throw php.error; + assert.equal(php.status, 0, 'PHP Twig helper contract failed.'); +} + +main().catch((error) => { console.error(error); process.exitCode = 1; }); diff --git a/.github/scripts/twig-helper-contract.php b/.github/scripts/twig-helper-contract.php new file mode 100644 index 0000000..a1eeaf6 --- /dev/null +++ b/.github/scripts/twig-helper-contract.php @@ -0,0 +1,81 @@ +<?php +/** + * Characterizes actual parent helpers and their autoescaped Twig registration. + * + * @package Emulsify + */ + +use Emulsify\Theme\Runtime\Twig; +use Emulsify\Theme\Support\AttributeBag; + +$autoload = __DIR__ . '/../../vendor/autoload.php'; + +if ( PHP_SAPI !== 'cli' || ! is_readable( $autoload ) ) { + fwrite( STDERR, "Run this CLI check after composer install.\n" ); + exit( 1 ); +} + +require_once $autoload; +require_once __DIR__ . '/wordpress-attribute-test-adapter.php'; + +try { + $corpus = json_decode( file_get_contents( __DIR__ . '/../fixtures/twig-helper-contract.json' ), true, 512, JSON_THROW_ON_ERROR ); + if ( 1 !== ( $corpus['schemaVersion'] ?? null ) || ! is_array( $corpus['cases'] ?? null ) || empty( $corpus['cases'] ) ) { + throw new RuntimeException( 'Twig helper schema 1 requires a nonempty cases array.' ); + } + $integration = new Twig(); + $functions = $integration->functions( array() ); + $environment = new \Twig\Environment( new \Twig\Loader\ArrayLoader(), $integration->environment_options( array( 'cache' => false ) ) ); + + foreach ( $functions as $name => $definition ) { + $environment->addFunction( new \Twig\TwigFunction( $name, $definition['callable'], $definition['options'] ?? array() ) ); + } + + foreach ( $corpus['cases'] as $fixture ) { + if ( ! is_array( $fixture['args'] ?? null ) ) { + throw new RuntimeException( $fixture['id'] . ': helper arguments must be an array.' ); + } + $values = $fixture['context'] ?? array(); + $context = array_merge( $fixture['contextVars'] ?? array(), array( 'attributes' => 'bag' === ( $fixture['contextKind'] ?? '' ) ? new AttributeBag( $values ) : $values ) ); + $args = $fixture['args']; + if ( 'object' === ( $fixture['argumentKind'] ?? '' ) ) { + $args[0] = (object) $args[0]; + } + $html = array(); + for ( $index = 0; $index < ( $fixture['repeat'] ?? 1 ); ++$index ) { + $bag = call_user_func_array( $functions[ $fixture['helper'] ]['callable'], array_merge( array( $context ), $args ) ); + $html[] = (string) $bag; + } + $result = array( + 'attributes' => (object) $bag->toArray(), + 'html' => implode( '|', $html ), + 'contextAfter' => (object) ( $context['attributes'] instanceof AttributeBag ? $context['attributes']->toArray() : $context['attributes'] ), + ); + $expected = $fixture['php']; + $expected['attributes'] = (object) $expected['attributes']; + $expected['contextAfter'] = (object) $expected['contextAfter']; + + if ( json_encode( $result, JSON_THROW_ON_ERROR ) !== json_encode( $expected, JSON_THROW_ON_ERROR ) ) { + throw new RuntimeException( $fixture['id'] . ': PHP helper output changed: ' . json_encode( $result, JSON_UNESCAPED_UNICODE | JSON_THROW_ON_ERROR ) ); + } + + $names = array(); + foreach ( $args as $index => $value ) { + $name = 'argument_' . $index; + $names[] = $name; + $context[ $name ] = $value; + } + $call = '{{ ' . $fixture['helper'] . '(' . implode( ', ', $names ) . ') }}'; + $template = implode( '|', array_fill( 0, $fixture['repeat'] ?? 1, $call ) ); + $html = $environment->createTemplate( $template )->render( $context ); + + if ( $expected['html'] !== $html ) { + throw new RuntimeException( $fixture['id'] . ': registered Twig rendering changed: ' . $html ); + } + } + + echo 'PASS ' . count( $corpus['cases'] ) . ' PHP Twig helper cases and registered autoescaped renders on PHP ' . PHP_VERSION . ".\n"; +} catch ( Throwable $throwable ) { + fwrite( STDERR, $throwable->getMessage() . "\n" ); + exit( 1 ); +} diff --git a/.github/scripts/twig-project-namespace-smoke.php b/.github/scripts/twig-project-namespace-smoke.php index a9fbb59..6248e84 100644 --- a/.github/scripts/twig-project-namespace-smoke.php +++ b/.github/scripts/twig-project-namespace-smoke.php @@ -200,8 +200,10 @@ function emulsify_twig_project_smoke_render( \Twig\Environment $environment, str $child = $work_root . '/child-theme'; $missing_child = $work_root . '/missing-project-child'; $invalid_child = $work_root . '/invalid-project-child'; +$structured_child = $work_root . '/structured-child'; $parent = $work_root . '/parent-theme'; $extra = $work_root . '/extra-components'; +$failures = array(); try { emulsify_twig_project_smoke_write( @@ -211,18 +213,6 @@ function emulsify_twig_project_smoke_render( \Twig\Environment $environment, str 'project' => array( 'machineName' => 'whisk', ), - 'variant' => array( - 'structureImplementations' => array( - array( - 'name' => 'custom', - 'directory' => 'custom-twig', - ), - array( - 'name' => '@unsafe', - 'directory' => '../outside', - ), - ), - ), ), JSON_UNESCAPED_SLASHES ) @@ -231,10 +221,62 @@ function emulsify_twig_project_smoke_render( \Twig\Environment $environment, str emulsify_twig_project_smoke_write( $child . '/src/components/badge.twig', 'Child badge' ); emulsify_twig_project_smoke_write( $child . '/src/components/ui/heading/heading.twig', 'Child heading' ); emulsify_twig_project_smoke_write( $child . '/components/link/link.twig', 'Child legacy link' ); - emulsify_twig_project_smoke_write( $child . '/custom-twig/teaser.twig', 'Configured namespace teaser' ); emulsify_twig_project_smoke_write( $parent . '/src/components/example-card/example-card.twig', 'Parent example card' ); emulsify_twig_project_smoke_write( $extra . '/filtered/filtered.twig', 'Filtered root' ); + $component_fixtures = array( + 'exact-file.twig' => 'Twig extension after exact file', + 'trailing.twig' => 'Flat trailing name must not win', + 'trailing/.twig' => 'Trailing slash dot Twig candidate', + 'trailing/trailing.twig' => 'Nested trailing name after dot Twig', + 'atoms/button/button.twig' => 'Grouped button', + 'ui/controls/deep-card/deep-card.twig' => 'Deep grouped card', + '01-duplicate/duplicate/duplicate.twig' => 'First sibling duplicate', + '02-duplicate/duplicate/duplicate.twig' => 'Second sibling duplicate', + 'a-depth/deeper/breadth/breadth.twig' => 'Deeper duplicate', + 'z-depth/breadth/breadth.twig' => 'Shallower duplicate', + "\u{1F600}/unicode-order/unicode-order.twig" => 'UTF-16 first duplicate', + "\u{E000}/unicode-order/unicode-order.twig" => 'UTF-8 first duplicate', + 'exact-file' => 'Exact file candidate', + 'direct-priority.twig' => 'Direct before grouped', + 'atoms/direct-priority/direct-priority.twig' => 'Grouped after direct', + 'candidate-order.twig' => 'Flat Twig candidate', + 'candidate-order.html.twig' => 'Flat HTML Twig candidate', + 'candidate-order/candidate-order.twig' => 'Nested Twig candidate', + 'flat-html.html.twig' => 'HTML Twig before nested', + 'flat-html/flat-html.twig' => 'Nested after HTML Twig', + 'nested-order/nested-order.twig' => 'Nested Twig before HTML Twig', + 'nested-order/nested-order.html.twig' => 'Nested HTML Twig after Twig', + 'nested-html/nested-html.html.twig' => 'Nested HTML Twig candidate', + 'nested.html/nested.html.twig' => 'HTML extension stays in nested stem', + 'atoms/grouped-html/grouped-html.html.twig' => 'Grouped HTML Twig candidate', + 'atoms/override/override.twig' => 'Child grouped override', + ); + + foreach ( $component_fixtures as $relative => $contents ) { + emulsify_twig_project_smoke_write( $child . '/src/components/' . $relative, $contents ); + } + + emulsify_twig_project_smoke_write( $parent . '/src/components/override.twig', 'Parent direct override' ); + emulsify_twig_project_smoke_write( $parent . '/src/components/parent-only.twig', 'Parent source root' ); + emulsify_twig_project_smoke_write( $parent . '/components/parent-legacy.twig', 'Parent legacy root' ); + + $skipped_directories = array( 'node_modules', '.git', '.cache', '.vite', '.out', '.coverage', 'dist' ); + foreach ( $skipped_directories as $index => $directory ) { + emulsify_twig_project_smoke_write( $child . '/src/components/' . $directory . '/skipped-' . $index . '/skipped-' . $index . '.twig', 'Skipped component' ); + emulsify_twig_project_smoke_write( $child . '/src/components/ui/' . $directory . '/nested-skip-' . $index . '/nested-skip-' . $index . '.twig', 'Nested skipped component' ); + } + + $outside = $work_root . '/outside-components'; + emulsify_twig_project_smoke_write( $outside . '/escape.twig', 'Outside directory template' ); + emulsify_twig_project_smoke_write( $outside . '/external/external.twig', 'Outside grouped template' ); + if ( ! symlink( $outside, $child . '/src/components/escape' ) || ! symlink( $outside . '/escape.twig', $child . '/src/components/escape-file.twig' ) ) { + throw new RuntimeException( 'Could not create component containment symlink fixtures.' ); + } + if ( ! symlink( $child . '/src/components/badge.twig', $child . '/src/components/inside-file.twig' ) || ! symlink( $child . '/src/components/atoms/button', $child . '/src/components/inside-directory' ) ) { + throw new RuntimeException( 'Could not create contained component symlink fixtures.' ); + } + add_filter( 'emulsify_theme_project_component_roots', static function ( array $roots, string $machine_name ) use ( $extra ): array { @@ -249,6 +291,21 @@ static function ( array $roots, string $machine_name ) use ( $extra ): array { ); $environment = emulsify_twig_project_smoke_environment( $child, $parent ); + $freshness_path = $child . '/src/components/example-card/example-card.twig'; + $freshness_time = filemtime( $freshness_path ); + $native_loader = new \Twig\Loader\FilesystemLoader( $child . '/src/components' ); + + foreach ( array( -1, 0, 1 ) as $offset ) { + $cached_time = $freshness_time + $offset; + $expected = $native_loader->isFresh( 'example-card/example-card.twig', $cached_time ); + foreach ( array( 'whisk:example-card', '@whisk/example-card', '@components/example-card' ) as $reference ) { + emulsify_twig_project_smoke_assert_same( + $expected, + $environment->getLoader()->isFresh( $reference, $cached_time ), + $reference . ' freshness must match Twig at source mtime ' . ( $offset < 0 ? '-1' : '+' . $offset ) . '.' + ); + } + } emulsify_twig_project_smoke_assert_same( 'Child example card', @@ -262,12 +319,6 @@ static function ( array $roots, string $machine_name ) use ( $extra ): array { '@components should still resolve child components.' ); - emulsify_twig_project_smoke_assert_same( - 'Configured namespace teaser', - emulsify_twig_project_smoke_render( $environment, '{% include "@custom/teaser.twig" %}' ), - 'variant.structureImplementations should register matching Twig namespaces.' - ); - emulsify_twig_project_smoke_assert_same( 'Child badge', emulsify_twig_project_smoke_render( $environment, '{% include "whisk:badge" %}' ), @@ -297,6 +348,123 @@ static function ( array $roots, string $machine_name ) use ( $extra ): array { 'Unsafe project component references should be rejected.' ); + $resolution_cases = array( + array( 'whisk:button', 'Grouped button', 'A component name should resolve inside a group.' ), + array( '@components/button/button.twig', 'Grouped button', '@components explicit paths should use grouped lookup.' ), + array( '@components/button', 'Grouped button', '@components shorthand should use grouped lookup.' ), + array( 'components:button', 'Grouped button', 'The components colon namespace should use grouped lookup.' ), + array( 'components::button', 'Grouped button', 'The components double-colon namespace should use grouped lookup.' ), + array( 'components/button', 'Grouped button', 'The components slash namespace should use grouped lookup.' ), + array( 'project:button', 'Grouped button', 'Unregistered colon prefixes should use component shorthand.' ), + array( '@organisms/button', 'Grouped button', 'Unregistered at-prefixes should use component shorthand.' ), + array( 'whisk:deep-card', 'Deep grouped card', 'A component name should resolve inside two grouping levels.' ), + array( 'whisk:ui/controls/deep-card', 'Deep grouped card', 'Explicit grouping paths should support more than two segments.' ), + array( 'whisk:atoms\\button', 'Grouped button', 'Windows-style separators should normalize before candidate construction.' ), + array( 'whisk:./badge', 'Child badge', 'Safe current-directory segments should normalize within the root.' ), + array( 'whisk:missing/../badge', 'Child badge', 'Contained parent-directory segments should normalize without requiring an existing directory.' ), + array( 'whisk:atoms//button', 'Grouped button', 'Repeated separators should normalize before candidate construction.' ), + array( 'whisk:atoms/button/', 'Grouped button', 'A trailing separator should preserve nested component candidates.' ), + array( 'whisk:trailing/', 'Trailing slash dot Twig candidate', 'Candidate suffixes should be added before normalizing a trailing separator.' ), + array( 'whisk:duplicate', 'First sibling duplicate', 'Duplicate shorthand names should use sorted sibling order.' ), + array( 'whisk:breadth', 'Shallower duplicate', 'Shallower groups should precede alphabetically earlier deeper groups.' ), + array( 'whisk:unicode-order', 'UTF-16 first duplicate', 'Sibling sorting should use UTF-16 code units rather than UTF-8 bytes.' ), + array( 'whisk:exact-file', 'Exact file candidate', 'An exact file should be the first candidate.' ), + array( 'whisk:direct-priority', 'Direct before grouped', 'Direct candidates should precede every grouped candidate in the same root.' ), + array( 'whisk:candidate-order', 'Flat Twig candidate', 'A flat Twig candidate should precede HTML Twig and nested candidates.' ), + array( 'whisk:flat-html', 'HTML Twig before nested', 'A flat HTML Twig candidate should precede nested candidates.' ), + array( 'whisk:nested-order', 'Nested Twig before HTML Twig', 'A nested Twig candidate should precede nested HTML Twig.' ), + array( 'whisk:nested-html', 'Nested HTML Twig candidate', 'Nested HTML Twig candidates should resolve.' ), + array( 'whisk:grouped-html', 'Grouped HTML Twig candidate', 'Grouped HTML Twig candidates should resolve.' ), + array( 'whisk:badge.twig', 'Child badge', 'Explicit Twig extensions should resolve as exact files.' ), + array( 'whisk:nested-order.twig', 'Nested Twig before HTML Twig', 'Nested candidate stems should strip an explicit final Twig extension.' ), + array( 'whisk:nested.html.twig', 'HTML extension stays in nested stem', 'Nested candidate stems should preserve HTML before the final Twig extension.' ), + array( 'whisk:flat-html.html.twig', 'HTML Twig before nested', 'Explicit HTML Twig extensions should resolve as exact files.' ), + array( 'whisk:inside-file', 'Child badge', 'File symlinks contained by the root should remain usable.' ), + array( 'whisk:inside-directory/button.twig', 'Grouped button', 'Explicit directory symlinks contained by the root should remain usable.' ), + array( '@whisk/button', 'Grouped button', 'Project at-namespace syntax should use grouped lookup.' ), + array( 'whisk:override', 'Child grouped override', 'A child grouped component should precede a parent direct component.' ), + array( 'whisk:parent-only', 'Parent source root', 'The parent source root should remain available.' ), + array( 'whisk:parent-legacy', 'Parent legacy root', 'The parent legacy root should remain available.' ), + ); + + foreach ( $resolution_cases as list( $reference, $expected, $message ) ) { + try { + emulsify_twig_project_smoke_assert_same( + $expected, + emulsify_twig_project_smoke_render( $environment, '{% include ' . json_encode( $reference, JSON_UNESCAPED_SLASHES ) . ' %}' ), + $message + ); + } catch ( Throwable $throwable ) { + $failures[] = $message . ' ' . $throwable->getMessage(); + } + } + + $missing_references = array( + 'whisk:escape' => 'Directory symlinks must not escape the component root.', + 'whisk:escape-file' => 'File symlinks must not escape the component root.', + '@whisk/escape-file' => 'Project at-namespace aliases must not escape the component root.', + 'whisk:external' => 'Grouping discovery must not follow directory symlinks.', + 'whisk:../../outside' => 'Lexical traversal must not escape the component root.', + 'whisk:missing/button' => 'Project paths must preserve a missing first segment.', + 'missing/button' => 'Bare paths must preserve a missing first segment.', + 'missing/button/button.twig' => 'Bare explicit template paths must preserve a missing first segment.', + ); + + foreach ( $skipped_directories as $index => $directory ) { + $missing_references[ 'whisk:skipped-' . $index ] = $directory . ' must not be searched as a group.'; + $missing_references[ 'whisk:nested-skip-' . $index ] = $directory . ' must be skipped inside nested groups.'; + } + + foreach ( $missing_references as $reference => $message ) { + try { + emulsify_twig_project_smoke_assert( false === $environment->getLoader()->exists( $reference ), $message ); + } catch ( Throwable $throwable ) { + $failures[] = $throwable->getMessage(); + } + } + + foreach ( array( 'whisk:missing-component' => 'is not defined', 'whisk:../example-card' => 'name "whisk:../example-card" is invalid' ) as $reference => $expected_message ) { + try { + $environment->getLoader()->getSourceContext( $reference ); + $failures[] = 'Missing or invalid project references should throw LoaderError: ' . $reference; + } catch ( \Twig\Error\LoaderError $exception ) { + emulsify_twig_project_smoke_assert( false !== strpos( $exception->getMessage(), $expected_message ), 'Project component loader errors should retain their existing wording.' ); + } + } + + // Structure overrides replace the child's defaults with Core's configured + // components root; a named components implementation would take precedence. + emulsify_twig_project_smoke_write( + $structured_child . '/project.emulsify.json', + json_encode( + array( + 'project' => array( 'machineName' => 'whisk' ), + 'variant' => array( + 'structureImplementations' => array( + array( 'name' => 'custom', 'directory' => 'custom-twig' ), + array( 'name' => '@unsafe', 'directory' => '../outside' ), + array( 'name' => 'unsafe', 'directory' => '../outside' ), + ), + ), + ), + JSON_UNESCAPED_SLASHES + ) + ); + emulsify_twig_project_smoke_write( $structured_child . '/custom-twig/teaser.twig', 'Configured namespace teaser' ); + emulsify_twig_project_smoke_write( $work_root . '/outside/escape.twig', 'Outside configured root must not render' ); + emulsify_twig_project_smoke_write( $structured_child . '/src/components/legacy-hidden/legacy-hidden.twig', 'Unconfigured child component' ); + $structured_environment = emulsify_twig_project_smoke_environment( $structured_child, $parent ); + foreach ( array( 'whisk:teaser', '@components/teaser.twig', '@custom/teaser.twig' ) as $reference ) { + emulsify_twig_project_smoke_assert_same( + 'Configured namespace teaser', + emulsify_twig_project_smoke_render( $structured_environment, '{% include ' . json_encode( $reference ) . ' %}' ), + 'Structure overrides should use the first safe implementation for component references and its registered namespace.' + ); + } + foreach ( array( 'whisk:legacy-hidden', '@components/legacy-hidden/legacy-hidden.twig', '@unsafe/escape.twig', '@unsafe/../outside/escape.twig' ) as $reference ) { + emulsify_twig_project_smoke_assert( ! $structured_environment->getLoader()->exists( $reference ), 'Structure overrides must exclude old child defaults and unsafe configured roots.' ); + } + emulsify_twig_project_smoke_write( $missing_child . '/src/components/example-card/example-card.twig', 'Missing project example card' ); $missing_environment = emulsify_twig_project_smoke_environment( $missing_child, $parent ); @@ -307,9 +475,10 @@ static function ( array $roots, string $machine_name ) use ( $extra ): array { 'Missing project.emulsify.json should not break @components.' ); - emulsify_twig_project_smoke_assert( - false === $missing_environment->getLoader()->exists( 'whisk:example-card' ), - 'Missing project.emulsify.json should not register a project component loader.' + emulsify_twig_project_smoke_assert_same( + 'Missing project example card', + emulsify_twig_project_smoke_render( $missing_environment, '{% include "whisk:example-card" %}' ), + 'Without project metadata, an unregistered prefix should use Core component shorthand.' ); emulsify_twig_project_smoke_write( $invalid_child . '/project.emulsify.json', '{"project":' ); @@ -323,6 +492,10 @@ static function ( array $roots, string $machine_name ) use ( $extra ): array { 'Invalid project.emulsify.json should not break @components.' ); + if ( $failures ) { + throw new RuntimeException( implode( "\n", $failures ) ); + } + echo "Twig project namespace smoke checks passed.\n"; } catch ( Throwable $throwable ) { fwrite( STDERR, $throwable->getMessage() . "\n" ); diff --git a/.github/scripts/wordpress-attribute-test-adapter.php b/.github/scripts/wordpress-attribute-test-adapter.php new file mode 100644 index 0000000..c28f8fa --- /dev/null +++ b/.github/scripts/wordpress-attribute-test-adapter.php @@ -0,0 +1,40 @@ +<?php +/** + * Standalone adapters for WordPress's URL-attribute APIs. + * + * These cover the shared protocol test vectors without bootstrapping WordPress. + * attribute-hardening-wordpress-smoke.php repeats those vectors against the real + * core functions; this adapter is not a replacement for the WordPress fixture. + * + * @package Emulsify + */ + +if ( ! function_exists( 'wp_allowed_protocols' ) ) { + function wp_allowed_protocols(): array { + return array( 'http', 'https', 'ftp', 'ftps', 'mailto', 'news', 'irc', 'irc6', 'ircs', 'gopher', 'nntp', 'feed', 'telnet', 'mms', 'rtsp', 'sms', 'svn', 'tel', 'fax', 'xmpp', 'webcal', 'urn' ); + } +} + +if ( ! function_exists( 'wp_kses_uri_attributes' ) ) { + function wp_kses_uri_attributes(): array { + return array( 'action', 'archive', 'background', 'cite', 'classid', 'codebase', 'data', 'formaction', 'href', 'icon', 'longdesc', 'manifest', 'poster', 'profile', 'src', 'usemap', 'xmlns' ); + } +} + +if ( ! function_exists( 'wp_kses_bad_protocol' ) ) { + function wp_kses_bad_protocol( string $content, array $allowed_protocols ): string { + $content = preg_replace( '/[\x00-\x08\x0B\x0C\x0E-\x1F]/', '', $content ); + for ( $iteration = 0; $iteration < 6; ++$iteration ) { + $parts = preg_split( '/:|�*58;?|�*3a;?|:/i', $content, 2 ); + if ( count( $parts ) < 2 || preg_match( '%/\?%', $parts[0] ) ) { + return $content; + } + $scheme = strtolower( preg_replace( '/\s/', '', html_entity_decode( $parts[0], ENT_QUOTES | ENT_HTML5, 'UTF-8' ) ) ); + if ( in_array( $scheme, $allowed_protocols, true ) ) { + return $scheme . ':' . trim( $parts[1] ); + } + $content = trim( $parts[1] ); + } + return ''; + } +} diff --git a/.github/scripts/wordpress-fixture-smoke.cjs b/.github/scripts/wordpress-fixture-smoke.cjs index c4a08e0..0a5437c 100755 --- a/.github/scripts/wordpress-fixture-smoke.cjs +++ b/.github/scripts/wordpress-fixture-smoke.cjs @@ -17,8 +17,9 @@ const expectedGeneratedFromVersion = JSON.parse( ).version; const required = process.env.WP_SMOKE_REQUIRED === '1'; const keepFixture = process.env.WP_SMOKE_KEEP === '1'; +const auditAccessibility = process.env.WP_SMOKE_A11Y === '1'; const host = process.env.WP_SMOKE_HOST || '127.0.0.1'; -const wordpressVersion = process.env.WP_SMOKE_WORDPRESS_VERSION || '6.7'; +const wordpressVersion = process.env.WP_SMOKE_WORDPRESS_VERSION || '6.8'; let workDir = null; let logDir = null; let server = null; @@ -223,9 +224,11 @@ function copyThemes(themesDir) { if ([ '.git', '.github', + '.artifacts', '.coverage', '.out', '.publish', + 'dist-artifact', 'node_modules', 'vendor', ].includes(first)) { @@ -274,7 +277,6 @@ function assertGeneratedChildTheme(themePath, slug) { 'patterns/.gitkeep', 'src/components/.gitkeep', 'project.emulsify.json', - 'templates/page.twig', ]; if (!style.includes('Theme Name: Smoke Generated') || !style.includes('Template: emulsify')) { @@ -312,6 +314,14 @@ function assertGeneratedChildTheme(themePath, slug) { throw new Error('Generated child theme should not include an empty child theme.json by default.'); } + if (fs.existsSync(path.join(themePath, 'templates'))) { + throw new Error('Generated child theme should not include a templates directory by default.'); + } + + if (fs.readdirSync(themePath, { recursive: true }).some((file) => file.endsWith('.twig'))) { + throw new Error('Generated child theme should not include Twig templates by default.'); + } + for (const directory of ['src/editor', 'src/foundation', 'src/layout']) { if (fs.existsSync(path.join(themePath, directory))) { throw new Error(`Generated child theme should not include assumed source directory: ${directory}`); @@ -328,9 +338,27 @@ function assertGeneratedChildTheme(themePath, slug) { function installGeneratedChildFixtures(themePath) { const globalDirectory = path.join(themePath, 'dist', 'global'); const acfDirectory = path.join(themePath, 'dist', 'components', 'smoke-acf'); + const groupedDirectory = path.join(themePath, 'src', 'components', 'atoms', 'layout', 'smoke-grouped'); + const themeSlug = path.basename(themePath); fs.mkdirSync(globalDirectory, { recursive: true }); fs.mkdirSync(path.join(acfDirectory, 'css'), { recursive: true }); + fs.mkdirSync(groupedDirectory, { recursive: true }); + fs.mkdirSync(path.join(themePath, 'templates'), { recursive: true }); + fs.writeFileSync( + path.join(groupedDirectory, 'smoke-grouped.html.twig'), + '<p class="smoke-grouped-project-component">{{ label }}</p>\n' + ); + fs.writeFileSync( + path.join(themePath, 'templates', 'single.twig'), + `{% extends '@emulsify-tpl/single.twig' %} +{% block content %} + {{ parent() }} + {% include "${themeSlug}:smoke-grouped" with { label: 'Grouped project component via colon' } only %} + {% include "@${themeSlug}/smoke-grouped" with { label: 'Grouped project component via namespace' } only %} +{% endblock %} +` + ); fs.writeFileSync( path.join(globalDirectory, 'smoke.css'), '.smoke-generated-global { color: inherit; }\n' @@ -528,10 +556,10 @@ if ( ! $found ) { } function configureDebugLog(wpPath) { + wp(wpPath, ['config', 'set', 'WP_DEBUG', 'true', '--raw']); const configPath = path.join(wpPath, 'wp-config.php'); const config = fs.readFileSync(configPath, 'utf8'); const debugConfig = ` -define( 'WP_DEBUG', true ); define( 'WP_DEBUG_LOG', true ); define( 'WP_DEBUG_DISPLAY', false ); define( 'WP_ENVIRONMENT_TYPE', 'local' ); @@ -565,6 +593,44 @@ function createFixtureContent(wpPath) { '--post_content=Smoke post content', '--porcelain', ]); + const mediaPageId = wp(wpPath, [ + 'post', 'create', '--post_type=page', '--post_status=publish', + '--post_title=Media embed fixture', '--post_name=media-embeds', + '--post_content=[embed]https://www.youtube.com/watch?v=M7lc1UVf-VE[/embed]\n\n<!-- wp:embed {"url":"https://vimeo.com/76979871/fixturehash","type":"video","providerNameSlug":"vimeo"} -->\n<figure class="wp-block-embed is-type-video is-provider-vimeo"><div class="wp-block-embed__wrapper">\nhttps://vimeo.com/76979871/fixturehash\n</div></figure>\n<!-- /wp:embed -->', + '--porcelain', + ]); + fs.writeFileSync(path.join(wpPath, 'wp-content', 'mu-plugins', 'emulsify-media-fixture.php'), `<?php +// Fixture-only provider responses keep CI independent of provider networks. +add_filter( 'pre_oembed_result', function ( $result, $url ) { + if ( 'https://www.youtube.com/watch?v=M7lc1UVf-VE' === $url ) { + return '<iframe width="200" height="113" src="https://www.youtube.com/embed/M7lc1UVf-VE?feature=oembed&rel=0" title="YouTube fixture" allow="clipboard-write; accelerometer; gyroscope" allowfullscreen></iframe>'; + } + if ( 'https://vimeo.com/76979871/fixturehash' === $url ) { + return '<iframe width="320" height="180" src="https://player.vimeo.com/video/76979871?h=fixturehash&badge=0" title="Vimeo fixture" allow="clipboard-write; accelerometer; gyroscope" allowfullscreen></iframe>'; + } + return $result; +}, 10, 2 ); +add_filter( 'emulsify_theme_media_embed_options', function ( $options ) { + $poster = isset( $_GET['media_poster'] ) && 'provider' === $_GET['media_poster'] ? 'provider' : 'neutral'; + return is_page( 'media-embeds' ) ? array( 'privacy_mode' => true, 'click_to_load' => true, 'poster' => $poster ) : $options; +} ); +add_action( 'template_redirect', function () { + if ( is_page( 'media-embeds' ) ) { + header( "Content-Security-Policy: frame-src https://www.youtube.com https://www.youtube-nocookie.com https://player.vimeo.com; img-src 'self' https://i.ytimg.com https://i.vimeocdn.com data:; style-src 'self' 'unsafe-inline'" ); + header( 'Referrer-Policy: no-referrer' ); + } +} ); +`); + wp(wpPath, ['eval', String.raw` +$poster_options = static function ( $options ) { return array_merge( $options, array( 'click_to_load' => true, 'poster' => 'provider' ) ); }; +add_filter( 'emulsify_theme_media_embed_options', $poster_options, 999 ); +apply_filters( 'oembed_dataparse', + '<iframe src="https://player.vimeo.com/video/76979871?h=fixturehash" title="Vimeo fixture"></iframe>', + (object) array( 'type' => 'video', 'thumbnail_url' => 'https://i.vimeocdn.com/video/fixture_640.jpg', 'title' => 'Vimeo fixture' ), + 'https://vimeo.com/76979871/fixturehash' +); +remove_filter( 'emulsify_theme_media_embed_options', $poster_options, 999 ); +`]); const authorId = wp(wpPath, [ 'user', 'create', @@ -595,7 +661,32 @@ function createFixtureContent(wpPath) { '--comment_approved=1', ]); - return { authorId, categoryId, pageId, postId }; + wp(wpPath, ['eval', String.raw` +update_option( 'permalink_structure', '' ); +update_option( 'posts_per_page', 10 ); +for ( $number = 1; $number <= 11; $number++ ) { + $result = wp_insert_post( array( + 'post_type' => 'post', + 'post_status' => 'publish', + 'post_title' => sprintf( 'PaginationProbe result %02d', $number ), + 'post_content' => sprintf( 'PaginationProbe content %02d', $number ), + 'post_date' => sprintf( '2001-01-%02d 12:00:00', $number ), + 'post_category' => array( ${Number(categoryId)} ), + ), true ); + if ( is_wp_error( $result ) ) { + fwrite( STDERR, $result->get_error_message() . "\n" ); + exit( 1 ); + } +} +`]); + + const menuId = wp(wpPath, ['menu', 'create', 'Smoke Primary', '--porcelain']); + wp(wpPath, ['menu', 'item', 'add-post', menuId, pageId]); + wp(wpPath, ['menu', 'item', 'add-post', menuId, postId]); + wp(wpPath, ['menu', 'item', 'add-term', menuId, 'category', categoryId]); + wp(wpPath, ['menu', 'location', 'assign', menuId, 'primary']); + + return { authorId, categoryId, pageId, postId, mediaPageId }; } function getAvailablePort() { @@ -645,12 +736,12 @@ async function waitForServer(baseUrl) { } async function checkRoute(baseUrl, route) { - const response = await fetch(`${baseUrl}${route.path}`); + const response = await fetch(`${baseUrl}${route.path}`, { headers: route.headers }); const body = await response.text(); const expectedStatus = route.status || 200; appendLog('http.log', `\n${route.name} ${route.path}\nStatus: ${response.status}\n`); - appendLog('http.log', body.slice(0, 4000)); + appendLog('http.log', body); appendLog('http.log', '\n'); if (response.status !== expectedStatus) { @@ -688,6 +779,473 @@ async function checkGeneratedAssets(baseUrl, themeSlug) { await checkGeneratedAsset(baseUrl, themeSlug, 'dist/components/smoke-acf/css/smoke-acf.css', '.smoke-acf'); } +async function checkSearchPagination(baseUrl) { + const firstPage = await checkRoute(baseUrl, { + name: 'search pagination page 1', + path: '/?s=PaginationProbe', + includes: ['Search results for PaginationProbe', 'PaginationProbe result 11'], + }); + appendLog('search-pagination.html', firstPage); + const nextLink = firstPage.match(/<li\b[^>]*\bclass="[^"]*\bpagination__item--next\b[^"]*"[^>]*>\s*<a\b[^>]*\bhref="([^"]+)"/); + if (!nextLink) { + const navigation = firstPage.match(/<nav\b[^>]*>[\s\S]*?<\/nav>/g) || []; + throw new Error(`Search page 1 did not render a next pagination link. Navigation: ${navigation.join('\n') || '(none)'}`); + } + + // Decode HTML attribute ampersands once, as the browser does. A double-escaped + // & must remain a fragment in the URL so the regression cannot pass. + const href = nextLink[1].replace(/&(?:amp|#0*38|#x0*26);/gi, '&'); + const nextUrl = new URL(href, baseUrl); + if ( + nextUrl.origin !== baseUrl || + nextUrl.searchParams.get('s') !== 'PaginationProbe' || + nextUrl.searchParams.get('paged') !== '2' || + nextUrl.hash !== '' + ) { + throw new Error(`Search pagination should retain its search and request page 2; received ${nextUrl.href}.`); + } + + const secondPage = await checkRoute(baseUrl, { + name: 'search pagination page 2', + path: `${nextUrl.pathname}${nextUrl.search}`, + includes: ['Search results for PaginationProbe', 'PaginationProbe result 01'], + }); + if (!/<span\b[^>]*\baria-current="page"[^>]*>\s*2\s*<\/span>/.test(secondPage)) { + throw new Error('Following the search pagination link did not render current page 2.'); + } + if (secondPage.includes('PaginationProbe result 11')) { + throw new Error('Search page 2 incorrectly includes the first-page-only result.'); + } +} + +async function checkChildBlockExtension(baseUrl, pagePath, themePath, baseline) { + const childTemplate = path.join(themePath, 'templates', 'page.twig'); + const original = fs.existsSync(childTemplate) ? fs.readFileSync(childTemplate, 'utf8') : null; + const before = '<!-- child content extension start -->'; + const after = '<!-- child content extension end -->'; + + try { + fs.mkdirSync(path.dirname(childTemplate), { recursive: true }); + fs.writeFileSync( + childTemplate, + `{% extends '@emulsify-tpl/page.twig' %}{% block content %}${before}{{ parent() }}${after}{% endblock %}` + ); + const extended = await checkRoute(baseUrl, { + name: 'child page block extension', + path: pagePath, + includes: [before, after, 'Smoke Page', 'Smoke page content'], + }); + + // Anonymous fixture responses are deterministic. Compare raw bytes, including + // whitespace and WordPress hook output, without normalizing the document. + if ( + extended.split(before).length !== 2 || + extended.split(after).length !== 2 || + extended.replace(before, '').replace(after, '') !== baseline + ) { + throw new Error('Child block extension must preserve every surrounding byte.'); + } + } + finally { + if (original === null) { + fs.rmSync(childTemplate, { force: true }); + } + else { + fs.writeFileSync(childTemplate, original); + } + } + + const restored = await checkRoute(baseUrl, { + name: 'parent page after child extension cleanup', + path: pagePath, + includes: ['Smoke Page', 'Smoke page content'], + }); + if (restored !== baseline) { + throw new Error('Removing the child block extension must restore the parent page bytes.'); + } +} + +async function checkTemplateRouting(wpPath, baseUrl, themePath) { + const options = ['show_on_front', 'page_on_front', 'page_for_posts', 'date_format']; + const original = Object.fromEntries(options.map((name) => [name, wp(wpPath, ['option', 'get', name])])); + const templates = new Map(); + const plugin = path.join(wpPath, 'wp-content', 'mu-plugins', 'emulsify-routing-fixture.php'); + const created = []; + const writeTemplate = (name, text) => { + const file = path.join(themePath, 'templates', name); + if (!templates.has(file)) templates.set(file, fs.existsSync(file) ? fs.readFileSync(file) : null); + fs.mkdirSync(path.dirname(file), { recursive: true }); + fs.writeFileSync(file, text); + }; + const expectRoute = async (name, route, marker, absent = []) => { + const body = await checkRoute(baseUrl, { name, path: route, includes: [marker] }); + for (const value of absent) { + if (body.includes(value)) throw new Error(`${name} incorrectly rendered ${value}.`); + } + return body; + }; + + try { + for (const [type, title, content, date] of [ + ['page', 'Route front page', 'RouteProtectedFrontSecret', null], + ['page', 'Route posts page', '', null], + ['post', 'Route dated post', 'RouteDatedPostContent', '2002-03-14 12:00:00'], + ]) { + created.push(wp(wpPath, [ + 'post', 'create', `--post_type=${type}`, '--post_status=publish', + `--post_title=${title}`, `--post_content=${content}`, ...(date ? [`--post_date=${date}`] : []), '--porcelain', + ])); + } + const [frontId, postsId] = created; + const frontMarker = 'RouteFrontTemplateProbe'; + const homeMarker = 'RouteHomeTemplateProbe'; + writeTemplate('front-page.twig', `{% extends '@emulsify-tpl/layouts/base.twig' %}{% block content %}<p>${frontMarker}</p>{% endblock %}`); + writeTemplate('home.twig', `{% extends '@emulsify-tpl/layouts/base.twig' %}{% block content %}<p>${homeMarker}</p>{% endblock %}`); + wp(wpPath, ['option', 'update', 'show_on_front', 'posts']); + await expectRoute('posts front page prefers front-page Twig', '/', frontMarker, [homeMarker]); + fs.rmSync(path.join(themePath, 'templates', 'front-page.twig')); + await expectRoute('posts front page falls back to home Twig', '/', homeMarker, [frontMarker]); + writeTemplate('front-page.twig', `{% extends '@emulsify-tpl/layouts/base.twig' %}{% block content %}<p>${frontMarker}</p>{% endblock %}`); + + wp(wpPath, ['option', 'update', 'show_on_front', 'page']); + wp(wpPath, ['option', 'update', 'page_on_front', frontId]); + wp(wpPath, ['option', 'update', 'page_for_posts', postsId]); + await expectRoute('static front page uses front-page Twig', '/', frontMarker, [homeMarker]); + await expectRoute('separate posts page uses home Twig', `/?page_id=${postsId}`, homeMarker, [frontMarker]); + fs.rmSync(path.join(themePath, 'templates', 'home.twig')); + await expectRoute('posts page falls back to index Twig', `/?page_id=${postsId}`, 'Smoke Post', [frontMarker, homeMarker]); + fs.rmSync(path.join(themePath, 'templates', 'front-page.twig')); + await expectRoute('static front page falls back to page Twig', '/', 'RouteProtectedFrontSecret', [frontMarker, homeMarker]); + writeTemplate('front-page.twig', `{% extends '@emulsify-tpl/layouts/base.twig' %}{% block content %}<p>${frontMarker}</p>{{ post.post_content|raw }}{% endblock %}`); + wp(wpPath, ['post', 'update', frontId, '--post_password=route-front-password']); + const protectedFront = await expectRoute('protected static front page keeps password priority', '/', 'name="post_password"', [frontMarker, 'RouteProtectedFrontSecret']); + if (!protectedFront.includes('wp-login.php?action=postpass')) throw new Error('Protected static front page lost the native password form action.'); + + fs.writeFileSync(plugin, `<?php +add_action( 'init', function () { + register_post_type( 'route_probe', array( 'public' => true, 'has_archive' => true, 'label' => 'Route archive probe' ) ); +} ); +`); + writeTemplate('archive-route_probe.twig', `{% extends '@emulsify-tpl/archive.twig' %}{% block content %}<p>RouteEmptyArchiveTemplateProbe</p>{{ parent() }}{% endblock %}`); + await expectRoute('empty custom post type archive uses its specific Twig', '/?post_type=route_probe', 'RouteEmptyArchiveTemplateProbe'); + wp(wpPath, ['option', 'update', 'date_format', 'Y/m/d']); + await expectRoute('day archive uses site date format and day number', '/?year=2002&monthnum=3&day=14', 'Archive: 2002/03/14'); + log('Template routing: front-page/home/page hierarchy, protected static front pages, empty custom post type archives and configured day archive dates passed.'); + } finally { + for (const [name, value] of Object.entries(original)) wp(wpPath, ['option', 'update', name, value]); + for (const [file, value] of templates) { + if (value === null) fs.rmSync(file, { force: true }); + else fs.writeFileSync(file, value); + } + fs.rmSync(plugin, { force: true }); + for (const id of created) wp(wpPath, ['post', 'delete', id, '--force']); + } +} + +async function checkPasswordProtection(wpPath, content, baseUrl, themePath) { + const password = 'fixture-content-password'; + const secrets = ['PasswordFixtureProbePageContent', 'PasswordFixtureProbePageExcerpt', 'PasswordFixtureProbePostContent', 'PasswordFixtureProbePostExcerpt']; + const created = []; + const originalSiteUrl = wp(wpPath, ['option', 'get', 'siteurl']); + const originalFront = wp(wpPath, ['option', 'get', 'show_on_front']); + const originalFrontPage = wp(wpPath, ['option', 'get', 'page_on_front']); + const childPasswordTemplate = path.join(themePath, 'templates', 'single-password.twig'); + const originalPasswordTemplate = fs.existsSync(childPasswordTemplate) ? fs.readFileSync(childPasswordTemplate, 'utf8') : null; + const formPlugin = path.join(wpPath, 'wp-content', 'mu-plugins', 'emulsify-password-fixture.php'); + const assertPrivate = (body, name) => { + for (const secret of secrets) { + if (body.includes(secret)) throw new Error(`${name} leaked protected content or an excerpt: ${secret}.`); + } + }; + const assertForm = (body, expectedAction, id, name) => { + const forms = [...body.matchAll(/<form\b[^>]*\baction=(["'])(.*?)\1[^>]*>/gi)]; + if (!forms.some((form) => form[2].replace(/&(?:amp|#0*38|#x0*26);/gi, '&') === expectedAction)) { + throw new Error(`${name} must post its password form to ${expectedAction}.`); + } + if (!body.includes('data-password-fixture="core"') || !body.includes(`for="pwbox-${id}"`) || !body.includes('name="post_password"')) { + throw new Error(`${name} must use the filterable WordPress form and its labeled password field.`); + } + }; + const request = (name, route, headers) => checkRoute(baseUrl, { name, path: route, includes: [], headers }); + const submitPassword = async (id, value) => { + const response = await fetch(`${baseUrl}/wp-login.php?action=postpass`, { + method: 'POST', redirect: 'manual', + body: new URLSearchParams({ post_password: value, redirect_to: `${baseUrl}/?p=${id}` }), + }); + const cookie = response.headers.getSetCookie().map((value) => value.split(';')[0]).find((value) => value.startsWith('wp-postpass_')); + if (response.status !== 302 || !cookie) throw new Error('WordPress postpass must redirect and issue its real password cookie.'); + return { Cookie: cookie }; + }; + + try { + for (const [index, type] of ['page', 'post'].entries()) { + created.push(wp(wpPath, [ + 'post', 'create', `--post_type=${type}`, '--post_status=publish', + `--post_title=Password fixture ${type}`, `--post_content=${secrets[index * 2]}`, + `--post_excerpt=${secrets[index * 2 + 1]}`, `--post_password=${password}`, + `--post_author=${content.authorId}`, '--porcelain', + ])); + } + const [pageId, postId] = created; + wp(wpPath, ['post', 'term', 'add', postId, 'category', content.categoryId, '--by=id']); + fs.writeFileSync(formPlugin, `<?php +add_filter( 'the_password_form', function ( $form ) { + if ( 'the_password_form' === get_option( 'emulsify_fixture_empty_password_form' ) ) { + return ''; + } + return str_replace( '<form ', '<form data-password-fixture="core" ', $form ); +}, 999 ); +add_filter( 'timber/post/content/password_form', function ( $form ) { + return 'timber/post/content/password_form' === get_option( 'emulsify_fixture_empty_password_form' ) ? '' : $form; +}, 999 ); +`); + const routes = [ + ['protected page', `/?page_id=${pageId}`, pageId], + ['protected post', `/?p=${postId}`, postId], + ['protected blog listing', '/'], + ['protected category listing', `/?cat=${content.categoryId}`], + ['protected author listing', `/?author=${content.authorId}`], + // Core excludes protected posts from anonymous search. Search for the + // shared prefix so the public heading cannot echo a complete secret. + ['protected search listing', '/?s=PasswordFixtureProbe'], + ]; + for (const [name, route, id] of routes) { + const body = await request(name, route); + assertPrivate(body, name); + if (!id && !route.startsWith('/?s=') && !body.includes(`id="teaser-${postId}"`)) { + throw new Error(`${name} must include the protected post's teaser to exercise excerpt suppression.`); + } + if (id) { + assertForm(body, `${originalSiteUrl}/wp-login.php?action=postpass`, id, name); + const title = wp(wpPath, ['eval', `echo get_the_title( ${Number(id)} );`]); + if (!body.includes(title)) throw new Error(`${name} must retain WordPress's protected title: ${title}.`); + } + } + + // A site installed below its public home URL must use site_url(), and + // customizations of the core form must reach both singular routes. + wp(wpPath, ['option', 'update', 'siteurl', `${baseUrl}/wordpress-core`]); + try { + for (const [name, route, id] of routes.slice(0, 2)) { + const body = await request(`${name} with separate site URL`, route); + assertPrivate(body, name); + assertForm(body, `${baseUrl}/wordpress-core/wp-login.php?action=postpass`, id, name); + } + } finally { + wp(wpPath, ['option', 'update', 'siteurl', originalSiteUrl]); + } + + wp(wpPath, ['option', 'update', 'show_on_front', 'page']); + wp(wpPath, ['option', 'update', 'page_on_front', pageId]); + try { + const front = await request('protected static front page', '/'); + assertPrivate(front, 'protected static front page'); + assertForm(front, `${originalSiteUrl}/wp-login.php?action=postpass`, pageId, 'protected static front page'); + } finally { + wp(wpPath, ['option', 'update', 'show_on_front', originalFront]); + wp(wpPath, ['option', 'update', 'page_on_front', originalFrontPage]); + } + + // The shared Timber filter must also protect a child that directly prints + // post.content rather than inheriting the parent's password form markup. + fs.mkdirSync(path.dirname(childPasswordTemplate), { recursive: true }); + fs.writeFileSync(childPasswordTemplate, `{% extends '@emulsify-tpl/layouts/base.twig' %}{% block content %}<div data-password-child-content>{{ post.content|raw }}</div>{% endblock %}`); + for (const [name, route, id] of routes.slice(0, 2)) { + const body = await request(`${name} through child post.content`, route); + assertPrivate(body, name); + assertForm(body, `${originalSiteUrl}/wp-login.php?action=postpass`, id, name); + } + for (const hook of ['the_password_form', 'timber/post/content/password_form']) { + wp(wpPath, ['option', 'update', 'emulsify_fixture_empty_password_form', hook]); + for (const [name, route] of routes.slice(0, 2)) { + const body = await request(`${name} with empty ${hook}`, route); + assertPrivate(body, `${name} with empty ${hook}`); + if (!body.includes('data-password-child-content') || body.includes('name="post_password"')) { + throw new Error('A hidden password form must remain hidden without exposing child post.content.'); + } + } + } + wp(wpPath, ['option', 'delete', 'emulsify_fixture_empty_password_form']); + if (originalPasswordTemplate === null) fs.rmSync(childPasswordTemplate); + else fs.writeFileSync(childPasswordTemplate, originalPasswordTemplate); + + const wrongCookie = await submitPassword(postId, 'incorrect-fixture-password'); + for (const [name, route, id] of routes.slice(0, 2)) { + const body = await request(`${name} with incorrect password`, route, wrongCookie); + assertPrivate(body, name); + assertForm(body, `${originalSiteUrl}/wp-login.php?action=postpass`, id, name); + } + for (const [index, [name, route, id]] of routes.slice(0, 2).entries()) { + const correctCookie = await submitPassword(id, password); + const body = await request(`${name} after postpass`, route, correctCookie); + if (!body.includes(secrets[index * 2]) || body.includes('name="post_password"')) { + throw new Error(`${name} must reveal its content after the correct WordPress password cookie.`); + } + } + await checkRoute(baseUrl, { name: 'unprotected page after password checks', path: `/?page_id=${content.pageId}`, includes: ['Smoke page content'] }); + await checkRoute(baseUrl, { name: 'unprotected post after password checks', path: `/?p=${content.postId}`, includes: ['Smoke post content'] }); + log('Password protection: page/post/listing secrets stayed private, native forms used site URL and filters, static front pages and direct child content stayed protected, and wrong/correct postpass cookies behaved correctly.'); + } finally { + wp(wpPath, ['eval', "delete_option( 'emulsify_fixture_empty_password_form' );"]); + wp(wpPath, ['option', 'update', 'siteurl', originalSiteUrl]); + wp(wpPath, ['option', 'update', 'show_on_front', originalFront]); + wp(wpPath, ['option', 'update', 'page_on_front', originalFrontPage]); + if (originalPasswordTemplate === null) fs.rmSync(childPasswordTemplate, { force: true }); + else fs.writeFileSync(childPasswordTemplate, originalPasswordTemplate); + fs.rmSync(formPlugin, { force: true }); + for (const id of created) wp(wpPath, ['post', 'delete', id, '--force']); + } +} + +async function checkFormattedText(wpPath, baseUrl) { + const values = { + title: 'Don\'t "panic" & relax', + category: "Rock 'n' Roll & Blues", + site: "Ben & Jerry's", + author: "Writer & Reader's", + search: 'Tom & Jerry "live"', + }; + const fixture = JSON.parse(wp(wpPath, ['eval', String.raw` +$values = json_decode( file_get_contents( 'php://stdin' ), true ); +$fixture = array( + 'blogname' => get_option( 'blogname' ), + 'locations' => get_theme_mod( 'nav_menu_locations', array() ), +); +$fixture['author'] = wp_insert_user( array( 'user_login' => 'formatted-text-fixture', 'user_pass' => wp_generate_password(), 'display_name' => $values['author'], 'role' => 'author' ) ); +$category = wp_insert_term( $values['category'], 'category' ); +$fixture['category'] = $category['term_id']; +foreach ( array( 'post', 'page' ) as $type ) { + $fixture[$type] = wp_insert_post( wp_slash( array( 'post_type' => $type, 'post_status' => 'publish', 'post_title' => $values['title'], 'post_content' => 'FormattedTextFixture content', 'post_author' => $fixture['author'], 'post_category' => array( $fixture['category'] ) ) ) ); +} +$fixture['comment'] = wp_insert_comment( array( 'comment_post_ID' => $fixture['post'], 'comment_author' => 'Reader & Friend’s', 'comment_content' => 'Formatted text comment', 'comment_approved' => 1 ) ); +$fixture['menu'] = wp_create_nav_menu( 'Formatted text fixture' ); +$fixture['menuItem'] = wp_update_nav_menu_item( $fixture['menu'], 0, array( 'menu-item-object-id' => $fixture['post'], 'menu-item-object' => 'post', 'menu-item-type' => 'post_type', 'menu-item-status' => 'publish' ) ); +set_theme_mod( 'nav_menu_locations', array( 'primary' => $fixture['menu'] ) ); +update_option( 'blogname', $values['site'] ); +// A tiny local image exercises the actual Timber thumbnail and its title fallback. +$upload = wp_upload_bits( 'formatted-text.png', null, base64_decode( 'iVBORw0KGgoAAAANSUhEUgAAAAIAAAACCAIAAAD91JpzAAAACXBIWXMAAA7EAAAOxAGVKw4bAAAAC0lEQVQImWNgQAYAAA4AAbGa6gYAAAAASUVORK5CYII=' ) ); +$fixture['attachment'] = wp_insert_attachment( array( 'post_mime_type' => 'image/png', 'post_title' => 'Formatted text image', 'post_status' => 'inherit' ), $upload['file'] ); +require_once ABSPATH . 'wp-admin/includes/image.php'; +wp_update_attachment_metadata( $fixture['attachment'], wp_generate_attachment_metadata( $fixture['attachment'], $upload['file'] ) ); +set_post_thumbnail( $fixture['post'], $fixture['attachment'] ); +update_option( 'emulsify_fixture_text_ids', array( $fixture['post'], $fixture['page'] ) ); +$decode = static function ( $value ) { return html_entity_decode( $value, ENT_QUOTES | ENT_HTML5, 'UTF-8' ); }; +$fixture['expected'] = array( + 'title' => $decode( get_the_title( $fixture['post'] ) ), + 'site' => $decode( ( new \Timber\Site() )->name ), + 'category' => $decode( apply_filters( 'single_cat_title', get_term( $fixture['category'], 'category' )->name ) ), + 'author' => $decode( \Timber\Timber::get_user( $fixture['author'] )->name() ), + 'comment' => $decode( get_comment( $fixture['comment'] )->comment_author ), +); +echo wp_json_encode( $fixture ); +`], { input: JSON.stringify(values) })); + const plugin = path.join(wpPath, 'wp-content', 'mu-plugins', 'emulsify-formatted-text-fixture.php'); + const inspect = (name, html, assertions) => run(`Inspect ${name} DOM`, 'php', [path.join(repoRoot, '.github/scripts/formatted-text-dom-smoke.php')], { + input: JSON.stringify({ name, html, assertions }), + }); + const request = (name, route) => checkRoute(baseUrl, { name, path: route, includes: [] }); + const common = (site, menu) => [ + { xpath: '//a[@rel="home"]', text: site }, + { xpath: '//footer/p', contains: site }, + { xpath: `//nav//a[contains(@href, '?p=${fixture.post}')]`, text: menu }, + ]; + const postTitle = (id, text, extra = {}) => ({ xpath: `//*[@id="post-${id}"]//h1`, text, ...extra }); + const teaserTitle = (text, extra = {}) => ({ xpath: `//*[@id="teaser-${fixture.post}"]//h2/a`, text, ...extra }); + const imageAlt = (singular, text) => ({ xpath: `//*[@id="${singular ? 'post' : 'teaser'}-${fixture.post}"]//*[contains(concat(' ', normalize-space(@class), ' '), ' ${singular ? 'entry' : 'teaser'}__media ')]/img`, attribute: 'alt', text }); + try { + const expected = fixture.expected; + for (const [type, query] of [['post', 'p'], ['page', 'page_id']]) { + const body = await request(`formatted ${type}`, `/?${query}=${fixture[type]}`); + const assertions = [...common(expected.site, expected.title), postTitle(fixture[type], expected.title)]; + if (type === 'post') assertions.push( + { xpath: `//*[@id="post-${fixture.post}"]//*[contains(@class, 'entry__author')]/a`, text: expected.author }, + { xpath: `//*[@id="comment-${fixture.comment}"]//h3`, text: expected.comment }, + imageAlt(true, expected.title), + ); + inspect(`formatted ${type}`, body, assertions); + } + for (const [name, route, heading] of [ + ['blog', '/', null], + ['category', `/?cat=${fixture.category}`, expected.category], + ['author', `/?author=${fixture.author}`, `Archive of ${expected.author}`], + ]) { + const body = await request(`formatted ${name}`, route); + const assertions = [...common(expected.site, expected.title), teaserTitle(expected.title), imageAlt(false, expected.title)]; + if (heading) assertions.push({ xpath: '//main/header/h1', text: heading }); + inspect(`formatted ${name}`, body, assertions); + } + const search = await request('formatted search', `/?s=${encodeURIComponent(values.search)}`); + inspect('formatted search', search, [...common(expected.site, expected.title), { xpath: '//main/header/h1', text: `Search results for ${values.search}` }]); + + // Inject values after WordPress's save-time sanitization to model plugin + // title/name filters, including both raw and already encoded input. + fs.writeFileSync(plugin, `<?php +function emulsify_fixture_text_value( $key, $fallback ) { + $values = get_option( 'emulsify_fixture_text_values', array() ); + return isset( $values[$key] ) ? $values[$key] : $fallback; +} +add_filter( 'the_title', function ( $title, $id ) { + return in_array( (int) $id, get_option( 'emulsify_fixture_text_ids', array() ), true ) ? emulsify_fixture_text_value( 'title', $title ) : $title; +}, 999, 2 ); +add_filter( 'nav_menu_item_title', function ( $title ) { return emulsify_fixture_text_value( 'name', $title ); }, 999 ); +add_filter( 'option_blogname', function ( $name ) { return emulsify_fixture_text_value( 'name', $name ); }, 999 ); +add_filter( 'timber/user/name', function ( $name ) { return emulsify_fixture_text_value( 'name', $name ); }, 999 ); +add_filter( 'single_cat_title', function ( $name ) { return emulsify_fixture_text_value( 'name', $name ); }, 999 ); +`); + const safeTitle = '<strong>Bold</strong> & <em>calm</em> "quotes"'; + const hostile = '<script>alert("fixture")</script><img src="javascript:alert(1)" onerror=alert(1)> "quoted" & relaxed'; + for (const [name, title, plainName, inlineCount] of [ + ['safe inline title', safeTitle, hostile, 2], + ['hostile raw title', hostile, hostile, null], + ['hostile encoded title', '<script>alert("fixture")</script> & calm', '<img src=x onerror=alert(1)> "quoted" & relaxed', null], + ]) { + wp(wpPath, ['option', 'update', 'emulsify_fixture_text_values', JSON.stringify({ title, name: plainName }), '--format=json']); + const expected = JSON.parse(wp(wpPath, ['eval', String.raw` +$values = get_option( 'emulsify_fixture_text_values' ); +$decode = static function ( $value ) { return html_entity_decode( $value, ENT_QUOTES | ENT_HTML5, 'UTF-8' ); }; +echo wp_json_encode( array( 'title' => $decode( wp_strip_all_tags( wp_kses_post( $values['title'] ) ) ), 'name' => $decode( $values['name'] ), 'alt' => $decode( wp_strip_all_tags( $values['title'] ) ) ) ); +`])); + const titleOptions = { elements: ['strong', 'em', 'img'], ...(inlineCount === null ? {} : { elementCount: inlineCount }) }; + const post = await request(name, `/?p=${fixture.post}`); + inspect(name, post, [...common(expected.name, expected.name), postTitle(fixture.post, expected.title, titleOptions), imageAlt(true, expected.alt), + { xpath: `//*[@id="post-${fixture.post}"]//*[contains(@class, 'entry__author')]/a`, text: expected.name }, + ]); + const page = await request(`${name} page`, `/?page_id=${fixture.page}`); + inspect(`${name} page`, page, [postTitle(fixture.page, expected.title, titleOptions)]); + const archive = await request(`${name} category`, `/?cat=${fixture.category}`); + inspect(`${name} category`, archive, [teaserTitle(expected.title, titleOptions), imageAlt(false, expected.alt), { xpath: '//main/header/h1', text: expected.name }]); + } + wp(wpPath, ['option', 'delete', 'emulsify_fixture_text_values']); + for (const [altName, alt, expectedAlt] of [ + ['raw', '<script>alert("fixture")</script><style>body{display:none}</style><img src=x onerror=alert(1)> Portrait "quoted" & relaxed', 'Portrait "quoted" & relaxed'], + ['encoded', '<script>alert(1)</script> Portrait & "quoted"', '<script>alert(1)</script> Portrait & "quoted"'], + ]) { + wp(wpPath, ['post', 'meta', 'update', String(fixture.attachment), '_wp_attachment_image_alt', alt]); + for (const [name, route, singular] of [['single', `/?p=${fixture.post}`, true], ['blog', '/', false]]) { + const body = await request(`explicit ${altName} thumbnail alt ${name}`, route); + inspect(`explicit ${altName} thumbnail alt ${name}`, body, [imageAlt(singular, expectedAlt)]); + } + } + log('WordPress formatted text: native title/name/search characters render once; safe title markup survives; hostile markup and thumbnail attributes remain safe.'); + } finally { + fs.rmSync(plugin, { force: true }); + wp(wpPath, ['eval', String.raw` +$fixture = json_decode( file_get_contents( 'php://stdin' ), true ); +delete_option( 'emulsify_fixture_text_ids' ); +delete_option( 'emulsify_fixture_text_values' ); +update_option( 'blogname', $fixture['blogname'] ); +set_theme_mod( 'nav_menu_locations', $fixture['locations'] ); +wp_delete_nav_menu( $fixture['menu'] ); +wp_delete_post( $fixture['post'], true ); +wp_delete_post( $fixture['page'], true ); +wp_delete_attachment( $fixture['attachment'], true ); +wp_delete_term( $fixture['category'], 'category' ); +require_once ABSPATH . 'wp-admin/includes/user.php'; +wp_delete_user( $fixture['author'] ); +`], { input: JSON.stringify(fixture) }); + } +} + async function renderRoutes(wpPath, content, baseUrl, port, themeSlug) { startServer(wpPath, port); await waitForServer(baseUrl); @@ -695,25 +1253,104 @@ async function renderRoutes(wpPath, content, baseUrl, port, themeSlug) { const pageIncludes = [ 'Smoke Page', 'Smoke page content', - `${themeSlug}-page`, + `<article class="entry" id="post-${content.pageId}">`, + '<h1 class="entry__title">Smoke Page</h1>', + '<div class="entry__content">', `/wp-content/themes/${themeSlug}/dist/global/smoke.css`, `/wp-content/themes/${themeSlug}/dist/components/smoke-acf/css/smoke-acf.css`, ]; const routes = [ { name: 'home', path: '/', includes: ['Emulsify Smoke', 'Smoke Post'] }, { name: 'page', path: `/?page_id=${content.pageId}`, includes: pageIncludes }, - { name: 'single', path: `/?p=${content.postId}`, includes: ['Smoke Post', 'Smoke post content', 'Smoke comment content'] }, + { + name: 'single', + path: `/?p=${content.postId}`, + includes: [ + 'Smoke Post', + 'Smoke post content', + 'Smoke comment content', + 'Grouped project component via colon', + 'Grouped project component via namespace', + ], + }, { name: 'archive', path: `/?cat=${content.categoryId}`, includes: ['Smoke Category', 'Smoke Post'] }, + { name: 'media-embeds', path: `/?page_id=${content.mediaPageId}`, includes: ['Media embed fixture', 'srcdoc=', 'YouTube fixture', 'Vimeo fixture'] }, { name: 'search', path: '/?s=Smoke', includes: ['Search results for Smoke', 'Smoke Post'] }, { name: 'author', path: `/?author=${content.authorId}`, includes: ['Archive of Smoke Author', 'Smoke Post'] }, { name: '404', path: '/?p=9999999', status: 404, includes: ['Page not found'] }, ]; + let parentPage = null; for (const route of routes) { - await checkRoute(baseUrl, route); + const body = await checkRoute(baseUrl, route); + if (route.name === 'page') { + parentPage = body; + } } + await checkChildBlockExtension( + baseUrl, + `/?page_id=${content.pageId}`, + path.join(wpPath, 'wp-content', 'themes', themeSlug), + parentPage + ); + await checkSearchPagination(baseUrl); await checkGeneratedAssets(baseUrl, themeSlug); + await checkPasswordProtection(wpPath, content, baseUrl, path.join(wpPath, 'wp-content', 'themes', themeSlug)); + await checkTemplateRouting(wpPath, baseUrl, path.join(wpPath, 'wp-content', 'themes', themeSlug)); + await checkFormattedText(wpPath, baseUrl); + + if (auditAccessibility) { + const archiveCount = Number(wp(wpPath, ['post', 'list', '--post_type=post', '--post_status=publish', `--cat=${content.categoryId}`, '--format=count'])); + if (!Number.isInteger(archiveCount) || archiveCount < 12) { + throw new Error(`Rendered accessibility archive needs at least 12 published posts; found ${archiveCount}.`); + } + wp(wpPath, ['option', 'update', 'posts_per_page', '1']); + const themeDir = path.join(wpPath, 'wp-content', 'themes', themeSlug); + run('Install generated child accessibility dependencies', 'npm', [ + 'install', '--ignore-scripts', '--package-lock=false', + ], { + cwd: themeDir, + env: { ...process.env, PUPPETEER_SKIP_DOWNLOAD: 'true' }, + }); + run('Verify rendered accessibility failure gates', 'node', [ + '--test', path.join(repoRoot, '.github/scripts/rendered-a11y.test.cjs'), + ], { env: { ...process.env, EMULSIFY_A11Y_THEME: themeDir } }); + const { auditRenderedPages } = require('./rendered-a11y.cjs'); + const outputDir = path.resolve(process.env.WP_SMOKE_A11Y_OUTPUT || path.join(repoRoot, '.artifacts', 'wordpress-a11y')); + const pageUrl = `${baseUrl}/?page_id=${content.pageId}`; + const singleUrl = `${baseUrl}/?p=${content.postId}`; + const archiveUrl = `${baseUrl}/?cat=${content.categoryId}`; + const routes = [ + { name: 'home', url: `${baseUrl}/`, expectedText: 'Smoke Post' }, + { name: 'page', url: pageUrl, expectedText: ['Smoke Page', 'Smoke page content'], currentMenuHref: pageUrl }, + { name: 'single', url: singleUrl, expectedText: ['Smoke Post', 'Smoke post content'], currentMenuHref: singleUrl }, + { name: 'archive', url: archiveUrl, expectedText: ['Smoke Category', 'Smoke Post'], currentMenuHref: archiveUrl }, + { name: 'media-embeds', url: `${baseUrl}/?page_id=${content.mediaPageId}`, expectedText: 'Media embed fixture', mediaEmbeds: 2 }, + // A unique content phrase avoids depending on core's relevance ordering. + { name: 'search', url: `${baseUrl}/?s=Smoke%20post%20content`, expectedText: ['Search results for Smoke post content', 'Smoke Post'] }, + { + name: 'archive-page-2', + url: `${archiveUrl}&paged=2`, + expectedText: ['Smoke Category', 'PaginationProbe result 11'], + paginationPage: 2, + currentMenuHref: archiveUrl, + }, + ]; + fs.mkdirSync(outputDir, { recursive: true }); + fs.writeFileSync(path.join(outputDir, 'routes.json'), `${JSON.stringify(routes, null, 2)}\n`); + await auditRenderedPages({ themeDir, outputDir, routes }); + const { verifyMediaEmbeds } = require('./media-embed-browser.cjs'); + await verifyMediaEmbeds({ themeDir, url: `${baseUrl}/?page_id=${content.mediaPageId}`, outputDir }); + log(`Rendered accessibility reports: ${outputDir}`); + } +} + +function assertCleanDebugLog(wpPath) { + const debugLog = path.join(wpPath, 'wp-content', 'debug.log'); + if (fs.existsSync(debugLog) && fs.readFileSync(debugLog, 'utf8').trim() !== '') { + throw new Error(`WordPress fixture debug log must remain clean. See ${debugLog}.`); + } } function dumpLogs(wpPath) { @@ -768,6 +1405,8 @@ async function main() { `--version=${wordpressVersion}`, '--force', ]); + const resolvedWordpressVersion = wp(wpPath, ['core', 'version']); + log(`WordPress version: requested ${wordpressVersion}; resolved ${resolvedWordpressVersion}`); run('Create wp-config.php', 'wp', [ '--allow-root', @@ -816,6 +1455,13 @@ async function main() { runNativeBlockDiscovery(wpPath); installAcfStub(wpPath); runAcfDiscoveryWithStub(wpPath); + wp(wpPath, ['eval-file', path.join(repoRoot, '.github/scripts/media-embed-smoke.php')]); + wp(wpPath, ['eval-file', path.join(repoRoot, '.github/scripts/core-block-context-smoke.php')]); + wp(wpPath, ['eval-file', path.join(repoRoot, '.github/scripts/attribute-hardening-wordpress-smoke.php')]); + wp(wpPath, ['eval-file', path.join(repoRoot, '.github/scripts/context-wordpress-smoke.php')]); + run('Compare generators with real WordPress sanitization', 'npm', ['run', 'smoke:generation-parity'], { + env: { ...process.env, EMULSIFY_PARITY_REQUIRED: '1', EMULSIFY_WP_FORMATTING_FILE: path.join(wpPath, 'wp-includes/formatting.php') }, + }); wp(wpPath, [ 'eval', 'if ( ! class_exists( "\\\\Timber\\\\Timber" ) ) { fwrite( STDERR, "Timber is not loaded.\\n" ); exit( 1 ); }', @@ -824,8 +1470,9 @@ async function main() { const content = createFixtureContent(wpPath); await renderRoutes(wpPath, content, baseUrl, port, generatedChildSlug); stopServer(); + assertCleanDebugLog(wpPath); - log('Generated and activated a child theme, checked block discovery, loaded assets, and rendered home, page, single, archive, search, author, and 404 routes.'); + log(`WordPress ${resolvedWordpressVersion} (requested ${wordpressVersion}): Generated and activated a child without Twig templates, checked block discovery, loaded assets, rendered parent page fallbacks and child block extensions without changing surrounding bytes, rendered home, single, archive, search, author, 404, and media routes, and followed search pagination to page 2 with a clean debug log.` + (auditAccessibility ? ' Seven rendered routes passed the WCAG accessibility audit.' : '')); dropDatabase(env); if (!keepFixture) { diff --git a/.github/scripts/wordpress-starter-init-smoke.cjs b/.github/scripts/wordpress-starter-init-smoke.cjs index d7987e6..d0b8e54 100644 --- a/.github/scripts/wordpress-starter-init-smoke.cjs +++ b/.github/scripts/wordpress-starter-init-smoke.cjs @@ -94,7 +94,7 @@ function runNodeScript(scriptPath) { } } -function runWhiskTestScript() { +function assertEmptyGeneratedTestFails(projectDir) { const jestBin = path.join( starterRoot, 'node_modules', @@ -108,17 +108,16 @@ function runWhiskTestScript() { ); const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'; - const result = childProcess.spawnSync(npm, ['--prefix', 'whisk', 'run', 'test'], { - cwd: repoRoot, + fs.symlinkSync(path.join(starterRoot, 'node_modules'), path.join(projectDir, 'node_modules'), 'junction'); + const result = childProcess.spawnSync(npm, ['test', '--', '--runInBand'], { + cwd: projectDir, encoding: 'utf8', - env: process.env, + env: { ...process.env, CI: '1' }, + timeout: 60000, }); - - if (result.status !== 0) { - throw new Error( - `npm --prefix whisk run test failed:\n${result.stdout || ''}${result.stderr || ''}`.trim(), - ); - } + const output = `${result.stdout || ''}${result.stderr || ''}`; + assert(!result.error, `Generated npm test could not run: ${result.error && result.error.message}`); + assert(result.status !== 0 && /No tests found/.test(output), `An empty generated child theme must fail npm test because no tests exist:\n${output}`); } function runGeneratedComponentInspector(projectDir) { @@ -227,6 +226,42 @@ const target = path.join(workRoot, 'acme-theme'); const hostileName = 'Acme */ echo 1; /* Theme'; try { + for (const invalid of ['Acme_Site', '../Acme', '---', 'café', 'İSite']) { + const rejectedTarget = path.join(workRoot, `invalid-${Buffer.from(invalid).toString('hex')}`); + copyStarterFixture(starterRoot, rejectedTarget); + const config = readJson(path.join(rejectedTarget, 'project.emulsify.json')); + config.project.name = 'Machine-name fixture'; + config.project.machineName = invalid; + writeJson(path.join(rejectedTarget, 'project.emulsify.json'), config); + const before = fs.readFileSync(path.join(rejectedTarget, 'style.css'), 'utf8'); + const rejected = childProcess.spawnSync(process.execPath, [path.join(rejectedTarget, '.cli/init.js')], { + cwd: rejectedTarget, encoding: 'utf8', + }); + assert(rejected.status !== 0 && /machineName.*lowercase|machineName.*canonical/i.test(rejected.stderr), `Invalid machineName ${invalid} must fail with naming guidance.`); + assert(fs.readFileSync(path.join(rejectedTarget, 'style.css'), 'utf8') === before, 'Invalid machineName must fail before rewriting metadata.'); + } + + for (const value of [ + '<script>ignored()</script>Theme', + 'A <b title="unterminated>text', + 'A <\nscript>alert(1)</script>', + 'A <!-- c -- > text', + 'A <scriptx>hidden</script> B', + ]) { + for (const field of ['name', 'description']) { + const rejectedTarget = fs.mkdtempSync(path.join(workRoot, 'html-')); + copyStarterFixture(starterRoot, rejectedTarget); + const config = readJson(path.join(rejectedTarget, 'project.emulsify.json')); + config.project.machineName = 'plain-text'; + config.project[field] = value; + writeJson(path.join(rejectedTarget, 'project.emulsify.json'), config); + const originalStyle = fs.readFileSync(path.join(rejectedTarget, 'style.css'), 'utf8'); + const rejected = childProcess.spawnSync(process.execPath, [path.join(rejectedTarget, '.cli/init.js')], { cwd: rejectedTarget, encoding: 'utf8' }); + assert(rejected.status !== 0 && /must be plain text/.test(rejected.stderr), `HTML project.${field} must fail with plain-text guidance.`); + assert(fs.readFileSync(path.join(rejectedTarget, 'style.css'), 'utf8') === originalStyle, 'HTML metadata must fail before rewriting starter files.'); + } + } + copyStarterFixture(starterRoot, target); writeJson(path.join(target, 'project.emulsify.json'), { @@ -275,7 +310,6 @@ try { const project = readJson(path.join(target, 'project.emulsify.json')); const pattern = readJson(path.join(target, 'patterns/smoke-pattern.json')); const functionsPhp = fs.readFileSync(path.join(target, 'functions.php'), 'utf8'); - const pageTwig = fs.readFileSync(path.join(target, 'templates/page.twig'), 'utf8'); assert(style['Theme Name'] === 'Acme echo 1 Theme', 'style.css should use a source-safe Theme Name.'); assert(!style['Theme Name'].includes('*/'), 'style.css should not contain a crafted comment terminator.'); @@ -295,8 +329,7 @@ try { ); assert(functionsPhp.includes('Acme echo 1 Theme child theme hooks.'), 'functions.php should use a source-safe visible label.'); assert(!functionsPhp.includes('*/ echo 1; /*'), 'functions.php should not contain the attempted docblock breakout.'); - assert(pageTwig.includes('acme-theme-page'), 'templates/page.twig should update the page class.'); - assert(!pageTwig.includes('whisk-page'), 'templates/page.twig should not keep the starter page class.'); + assert(!fs.existsSync(path.join(target, 'templates')), 'Fresh generated child themes should inherit parent templates without a local templates directory.'); assert(pattern.name === 'acme-theme/smoke-pattern', 'JSON pattern names should update the whisk namespace.'); assert( !fs.existsSync(path.join(target, '.cli')), @@ -361,7 +394,7 @@ try { ); } - runWhiskTestScript(); + assertEmptyGeneratedTestFails(target); console.log('WordPress starter init smoke checks passed.'); } catch (error) { diff --git a/.github/scripts/wordpress-text-test-adapter.php b/.github/scripts/wordpress-text-test-adapter.php new file mode 100644 index 0000000..8a772e4 --- /dev/null +++ b/.github/scripts/wordpress-text-test-adapter.php @@ -0,0 +1,50 @@ +<?php +/** + * Conservative WordPress text adapters for standalone Twig wiring checks. + * + * These checks cannot load WordPress. Timber supplies the actual filter + * definitions and safety options; the callbacks below cover entity handling + * only. In particular, stripping every tag is not a KSES implementation: the + * full WordPress fixture verifies allowed markup, protocols and attributes. + * + * @package Emulsify + */ + +require_once __DIR__ . '/wordpress-attribute-test-adapter.php'; + +if ( ! function_exists( 'apply_filters' ) ) { + function apply_filters( string $hook, $value, ...$arguments ) { + return $value; + } +} + +if ( ! function_exists( 'wp_strip_all_tags' ) ) { + function wp_strip_all_tags( $value, bool $remove_breaks = false ): string { + $value = preg_replace( '@<(script|style)\b[^>]*?>.*?</\1>@si', '', (string) $value ); + $value = strip_tags( $value ); + return trim( $remove_breaks ? preg_replace( '/[\r\n\t ]+/', ' ', $value ) : $value ); + } +} + +/** + * Adds Timber's real filter metadata with conservative standalone callbacks. + * + * @param \Twig\Environment $environment Test Twig environment. + * @return void + */ +function emulsify_register_wordpress_text_test_filters( \Twig\Environment $environment ): void { + $encode = static function ( $value ): string { + return htmlspecialchars( (string) $value, ENT_QUOTES | ENT_SUBSTITUTE, 'UTF-8', false ); + }; + $callbacks = array( + 'esc_html' => $encode, + 'esc_attr' => $encode, + 'wp_kses_post' => static function ( $value ) use ( $encode ): string { + return $encode( strip_tags( (string) $value ) ); + }, + ); + $definitions = ( new \Timber\Twig() )->get_timber_escaper_filters(); + foreach ( $callbacks as $name => $callback ) { + $environment->addFilter( new \Twig\TwigFilter( $name, $callback, $definitions[ $name ]['options'] ?? array( 'is_safe' => array( 'html' ) ) ) ); + } +} diff --git a/.github/workflows/addtoprojects.yml b/.github/workflows/addtoprojects.yml index 9fb9df2..de210f6 100644 --- a/.github/workflows/addtoprojects.yml +++ b/.github/workflows/addtoprojects.yml @@ -9,14 +9,20 @@ on: - opened workflow_dispatch: +permissions: + contents: read + jobs: add-to-project: name: Add issue to project + if: >- + github.event_name != 'pull_request' || + (github.event.pull_request.head.repo.full_name == github.repository && github.event.pull_request.user.login != 'dependabot[bot]') runs-on: ubuntu-latest steps: - - uses: actions/add-to-project@v0.3.0 + - uses: actions/add-to-project@5afcf98fcd03f1c2f92c3c83f58ae24323cc57fd # v2.0.0 with: # You can target a repository in a different organization # to the issue project-url: https://github.com/orgs/emulsify-ds/projects/6 - token: ${{ secrets.ADD_TO_PROJECT_PAT }} + github-token: ${{ secrets.ADD_TO_PROJECT_PAT }} diff --git a/.github/workflows/contributors.yml b/.github/workflows/contributors.yml deleted file mode 100644 index 07b7454..0000000 --- a/.github/workflows/contributors.yml +++ /dev/null @@ -1,24 +0,0 @@ -name: Add contributors -on: - schedule: - - cron: '20 20 * * *' - push: - branches: - - main - workflow_dispatch: - -jobs: - add-contributors: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - uses: BobAnkh/add-contributors@master - with: - CONTRIBUTOR: '### Contributors' - COLUMN_PER_ROW: '6' - ACCESS_TOKEN: ${{secrets.ADD_TO_PROJECT_PAT}} - IMG_WIDTH: '100' - FONT_SIZE: '14' - PATH: '/README.md' - COMMIT_MESSAGE: 'docs(README): update contributors' - AVATAR_SHAPE: 'round' diff --git a/.github/workflows/semantic-release.yml b/.github/workflows/semantic-release.yml index c9d2446..5957e1d 100644 --- a/.github/workflows/semantic-release.yml +++ b/.github/workflows/semantic-release.yml @@ -1,9 +1,5 @@ name: WordPress Release -# Release publishing is gated by the same local readiness script used by -# maintainers, with the WordPress fixture required instead of optional. The -# release-readiness job installs WP-CLI, starts MySQL, and runs release:check -# with WP_SMOKE_REQUIRED=1 before semantic-release can publish. on: push: branches: @@ -18,119 +14,81 @@ concurrency: cancel-in-progress: false jobs: - release-readiness: - name: Release readiness + release-state: + name: Check release publication state runs-on: ubuntu-latest - services: - mysql: - image: mysql:8.0 - env: - MYSQL_ROOT_PASSWORD: root - MYSQL_DATABASE: wordpress_smoke - ports: - - 3306:3306 - options: >- - --health-cmd="mysqladmin ping -h 127.0.0.1 -uroot -proot" - --health-interval=10s - --health-timeout=5s - --health-retries=10 + timeout-minutes: 10 permissions: - contents: write - issues: write - pull-requests: write + contents: read steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 + persist-credentials: false - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc - cache: npm - - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: '8.3' - extensions: mysqli - tools: composer:v2, wp-cli - coverage: none - - - name: Clean npm install - run: npm ci --ignore-scripts - - - name: Validate Composer metadata - run: composer validate --no-check-publish --strict - - - name: Install Composer dependencies for PHP lint - run: composer install --no-interaction --no-progress --prefer-dist - - - name: Run PHP lint - run: npm run lint:php - - - name: Run runtime npm audit - run: npm audit --omit=dev - - - name: Check release config syntax - run: node --check release.config.js - - name: Build tested installable theme archive - run: npm run build:dist - - - name: Run release readiness checks - env: - WP_SMOKE_REQUIRED: '1' - WP_SMOKE_THEME_ARCHIVE: dist-artifact/emulsify.zip - WP_SMOKE_DB_HOST: 127.0.0.1 - WP_SMOKE_DB_PORT: '3306' - WP_SMOKE_DB_NAME: wordpress_smoke - WP_SMOKE_DB_USER: root - WP_SMOKE_DB_PASSWORD: root - run: npm run release:check - - - name: Run release dry run + # Diagnose a partial tag before a stale release draft fails readiness. + - name: Check published release and ZIP env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: npm run publish-test -- --no-ci + run: node .github/scripts/semantic-release.cjs --check-publication - - name: Run full npm audit - continue-on-error: true - run: npm audit + release-readiness: + name: Full release readiness + needs: release-state + uses: ./.github/workflows/theme-readiness.yml + with: + release: true + permissions: + contents: read semantic-release: name: Semantic release needs: release-readiness runs-on: ubuntu-latest + timeout-minutes: 15 permissions: contents: write issues: write pull-requests: write steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 with: fetch-depth: 0 + persist-credentials: false - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc cache: npm - - name: Setup PHP - uses: shivammathur/setup-php@v2 - with: - php-version: '8.3' - tools: composer:v2 - coverage: none - - name: Clean npm install run: npm ci --ignore-scripts - - name: Build installable theme archive - run: npm run build:dist + - name: Download tested release bundle + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: emulsify-tested-${{ github.sha }} + path: dist-artifact + digest-mismatch: error + + - name: Verify tested archive checksum + working-directory: dist-artifact + run: sha256sum --check emulsify.zip.sha256 + + # semantic-release verifies push permission even in dry-run mode, so + # keep this check in the publishing job with its scoped write token. + - name: Run release dry run + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + run: npm run publish-test -- --no-ci - name: Semantic release id: semantic diff --git a/.github/workflows/theme-readiness.yml b/.github/workflows/theme-readiness.yml index db13c46..50b0a92 100644 --- a/.github/workflows/theme-readiness.yml +++ b/.github/workflows/theme-readiness.yml @@ -6,6 +6,12 @@ name: WordPress Theme Readiness # exercise the same extended coverage, while manual inputs select either # expensive fixture independently. on: + workflow_call: + inputs: + release: + description: Require the full release readiness gates. + type: boolean + default: false pull_request: branches: - main @@ -24,7 +30,7 @@ on: type: boolean default: true extended_checks: - description: Run the CI-seeded Whisk Storybook build and accessibility audit. + description: Run CI-seeded Whisk tests, Storybook build, and accessibility audit. required: false type: boolean default: false @@ -35,38 +41,42 @@ permissions: contents: read concurrency: - group: theme-readiness-${{ github.event.pull_request.number || github.ref }} + group: theme-readiness-${{ github.workflow }}-${{ github.event.pull_request.number || github.ref }} cancel-in-progress: ${{ github.event_name == 'pull_request' }} jobs: practical: name: Practical theme readiness (PHP ${{ matrix.php-version }}) runs-on: ubuntu-latest + timeout-minutes: 20 strategy: fail-fast: false matrix: - # 8.3 is the supported baseline. 8.4 proves the runtime stays clean on - # the current release, and 8.5 is an advisory forward-compatibility lane. + # The supported baseline and both newer PHP releases are blocking; + # PHP 8.5 passed the Composer, PHP analysis, and practical checks. include: - php-version: '8.3' experimental: false - php-version: '8.4' experimental: false - php-version: '8.5' - experimental: true + experimental: false continue-on-error: ${{ matrix.experimental }} steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + fetch-depth: 0 - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc cache: npm - name: Setup PHP - uses: shivammathur/setup-php@v2 + uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 with: php-version: ${{ matrix.php-version }} tools: composer:v2 @@ -79,7 +89,10 @@ jobs: run: composer validate --no-check-publish --strict - name: Install Composer dependencies for runtime smoke coverage - run: composer install --no-interaction --no-progress --prefer-dist ${{ matrix.experimental && '--ignore-platform-req=php+' || '' }} + run: composer install --no-interaction --no-progress --prefer-dist + + - name: Audit shipped Composer dependencies + run: composer audit --locked --no-dev - name: Run runtime npm audit run: npm audit --omit=dev @@ -106,9 +119,26 @@ jobs: if: matrix.php-version == '8.3' run: npm run build:dist + - name: Checksum installable theme archive + if: matrix.php-version == '8.3' + working-directory: dist-artifact + run: sha256sum emulsify.zip > emulsify.zip.sha256 + + - name: Upload tested release bundle + if: matrix.php-version == '8.3' + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: emulsify-tested-${{ github.sha }} + path: | + dist-artifact/emulsify.zip + dist-artifact/emulsify.zip.sha256 + overwrite: true + if-no-files-found: error + retention-days: 14 + - name: Upload installable theme archive if: matrix.php-version == '8.3' - uses: actions/upload-artifact@v7 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: path: dist-artifact/emulsify.zip archive: false @@ -118,7 +148,7 @@ jobs: - name: Upload failure diagnostics if: failure() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: practical-readiness-php-${{ matrix.php-version }} path: | @@ -133,16 +163,18 @@ jobs: timeout-minutes: 10 steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc cache: npm - name: Setup PHP - uses: shivammathur/setup-php@v2 + uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 with: php-version: '8.3' tools: composer:v2 @@ -157,22 +189,25 @@ jobs: wordpress-fixture: name: WordPress fixture smoke (WordPress ${{ matrix.wordpress-version }}) if: >- + inputs.release || (github.event_name == 'pull_request' && (github.base_ref == 'main' || github.base_ref == 'release-2.x')) || github.event_name == 'push' || github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && inputs.wordpress_fixture) + needs: practical runs-on: ubuntu-latest timeout-minutes: 20 strategy: fail-fast: false matrix: - # 6.7 is the declared baseline in style.css. `latest` is an advisory - # forward-compatibility lane so a WordPress release cannot break the - # theme silently between scheduled runs. + # The declared minimum and dynamically resolved current stable release + # are blocking. Nightly tracks the next release without blocking merges. include: - - wordpress-version: '6.7' + - wordpress-version: '6.8' experimental: false - wordpress-version: latest + experimental: false + - wordpress-version: nightly experimental: true continue-on-error: ${{ matrix.experimental }} services: @@ -190,16 +225,29 @@ jobs: --health-retries=10 steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false + fetch-depth: 0 - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc cache: npm + - name: Select and verify runner Chrome + timeout-minutes: 1 + run: | + # Ubuntu's AppArmor profile permits the installed Google Chrome. + # Verify it launches with its sandbox before Puppeteer runs. + chrome_path="$(command -v google-chrome)" + "$chrome_path" --version + "$chrome_path" --headless --dump-dom about:blank + printf 'PUPPETEER_EXECUTABLE_PATH=%s\n' "$chrome_path" >> "$GITHUB_ENV" + - name: Setup PHP - uses: shivammathur/setup-php@v2 + uses: shivammathur/setup-php@f3e473d116dcccaddc5834248c87452386958240 # v2.37.2 with: php-version: '8.3' extensions: mysqli @@ -212,12 +260,25 @@ jobs: - name: Install Composer dependencies run: composer install --no-dev --no-interaction --no-progress --prefer-dist - - name: Build installable theme archive - run: npm run build:dist + - name: Audit shipped Composer dependencies + run: composer audit --locked --no-dev + + - name: Download tested release bundle + uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1 + with: + name: emulsify-tested-${{ github.sha }} + path: dist-artifact + digest-mismatch: error + + - name: Verify tested archive checksum + working-directory: dist-artifact + run: sha256sum --check emulsify.zip.sha256 - name: Run WordPress fixture smoke env: WP_SMOKE_REQUIRED: '1' + WP_SMOKE_A11Y: '1' + WP_SMOKE_A11Y_OUTPUT: .artifacts/wordpress-a11y WP_SMOKE_THEME_ARCHIVE: dist-artifact/emulsify.zip WP_SMOKE_WORDPRESS_VERSION: ${{ matrix.wordpress-version }} WP_SMOKE_DB_HOST: 127.0.0.1 @@ -227,13 +288,23 @@ jobs: WP_SMOKE_DB_PASSWORD: root run: npm run release:check + - name: Upload rendered WordPress accessibility reports + if: always() + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: wordpress-rendered-a11y-${{ matrix.wordpress-version }} + path: .artifacts/wordpress-a11y/ + include-hidden-files: true + if-no-files-found: ignore + retention-days: 7 + - name: Upload fixture diagnostics if: failure() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: wordpress-fixture-${{ matrix.wordpress-version }} path: | - /tmp/emulsify-wp-smoke*/**/*.log + /tmp/emulsify-wordpress-smoke*/**/*.log npm-debug.log* if-no-files-found: ignore retention-days: 7 @@ -241,6 +312,7 @@ jobs: extended-whisk: name: Extended Whisk Storybook and a11y if: >- + inputs.release || (github.event_name == 'pull_request' && (github.base_ref == 'main' || github.base_ref == 'release-2.x')) || github.event_name == 'push' || github.event_name == 'schedule' || @@ -249,37 +321,61 @@ jobs: timeout-minutes: 20 steps: - name: Checkout - uses: actions/checkout@v7 + uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1 + with: + persist-credentials: false - name: Setup Node - uses: actions/setup-node@v6 + uses: actions/setup-node@249970729cb0ef3589644e2896645e5dc5ba9c38 # v6.5.0 with: node-version-file: .nvmrc cache: npm + - name: Select and verify runner Chrome + timeout-minutes: 1 + run: | + # Ubuntu's AppArmor profile permits the installed Google Chrome. + # Verify it launches with its sandbox before Puppeteer runs. + chrome_path="$(command -v google-chrome)" + "$chrome_path" --version + "$chrome_path" --headless --dump-dom about:blank + printf 'PUPPETEER_EXECUTABLE_PATH=%s\n' "$chrome_path" >> "$GITHUB_ENV" + - name: Clean npm install run: npm ci --ignore-scripts - name: Install Whisk dependencies - run: npm run whisk:install + env: + PUPPETEER_SKIP_DOWNLOAD: 'true' + # Keep this job's resolved tree for the informational audit below. + run: npm run whisk:install -- --package-lock=true + + - name: Audit Whisk dependencies + continue-on-error: true + run: npm --prefix whisk audit - name: Seed CI-only Whisk component run: cp -R .github/fixtures/whisk-a11y/. whisk/src/components/ - - name: Setup Chrome - id: setup-chrome - uses: browser-actions/setup-chrome@v2 - with: - chrome-version: stable + - name: Run CI-seeded Whisk frontend tests + run: npm --prefix whisk run test -- --runInBand - name: Build Storybook and run a11y - env: - PUPPETEER_EXECUTABLE_PATH: ${{ steps.setup-chrome.outputs.chrome-path }} run: npm --prefix whisk run a11y + - name: Upload Whisk coverage + if: ${{ !cancelled() }} + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 + with: + name: extended-whisk-coverage + path: whisk/.coverage/ + include-hidden-files: true + if-no-files-found: ignore + retention-days: 7 + - name: Upload Storybook diagnostics if: failure() - uses: actions/upload-artifact@v4 + uses: actions/upload-artifact@cf430e030ddbb5b0abf93d22962f4752f3646cd9 # v7.0.2 with: name: extended-whisk-storybook path: | diff --git a/.gitignore b/.gitignore index efcae5e..e06c20a 100644 --- a/.gitignore +++ b/.gitignore @@ -22,6 +22,9 @@ vendor # Storybook .out +# Rendered WordPress accessibility reports. +/.artifacts/ + # Local AI/release working notes /*-PROMPTS.md /PROMPTS-*.md diff --git a/.husky/commit-msg b/.husky/commit-msg new file mode 100644 index 0000000..70bd3dd --- /dev/null +++ b/.husky/commit-msg @@ -0,0 +1 @@ +npx --no-install commitlint --edit "$1" diff --git a/.husky/pre-commit b/.husky/pre-commit index 20d0d06..3867a0f 100755 --- a/.husky/pre-commit +++ b/.husky/pre-commit @@ -1,4 +1 @@ -#!/bin/sh -. "$(dirname "$0")/_/husky.sh" - npm run lint diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..afc4778 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,83 @@ +# Emulsify WordPress contributor guidance + +## Repository map + +- This repository distributes the `emulsify` WordPress parent theme, not a site. +- `includes/` owns reusable PHP runtime services; root PHP route controllers and + `templates/` provide Timber fallbacks and public Twig extension blocks. +- `whisk/` is the generation source for project-owned child themes. Its + `AGENTS.md`, integration guide, and skill describe generated-project work. + While changing that source here, follow this contributor workflow and verify + the generated result. +- `whisk/config/emulsify-core/` supplies copied project extension points. Shared + frontend tooling belongs to the installed `@emulsify/core` package. +- `.github/scripts/` and `.github/fixtures/` implement maintainer checks and + consumer contracts; they are not generated-project commands. +- `scripts/build-dist.sh` builds the installable parent ZIP, including the + starter payload and production Composer dependencies. + +Read [README.md](README.md), [UPGRADE.md](UPGRADE.md), and the relevant contracts +in `docs/`, especially [sister-project parity](docs/sister-project-parity.md), +[generated themes](docs/generated-child-theme-contract.md), and +[template extension](docs/template-extension.md). + +## Ownership boundaries + +The parent owns reusable WordPress integration, context, discovery, assets, +and fallback rendering. Project-specific templates, components, stories, +styling, and content mappings belong in the generated child; functionality +independent of the theme belongs in a project plugin. The parent ships no +stylesheet, but its `theme.json` produces WordPress global styles on the +frontend: h1–h6 color and typography, visited-link color, root padding, +button border radius/width and padding, and quote/cite typography and margins +plus cite color. It also produces preset custom properties and `.has-*` +classes, which style nothing until content uses them. Projects own final +presentation, target size, `screen-reader-text`, and focus styles. Keep +WordPress behavior native rather than importing Drupal names or mechanics. + +Keep the starter component-library-neutral. Discover the selected library's +directories, APIs, namespaces, tokens, stories, and build inputs from its guide +and existing project code. Do not scaffold one library's conventions into the +starter. Keep generated guidance free of starter identity and documentation +tokens so it copies unchanged; its links must resolve inside the child theme. + +Child generation has two implementations: +`includes/Cli/GenerateChildThemeCommand.php` and `whisk/.cli/init.js`. Update +both when their behavior changes. Preserve hidden `.agents/` skills through +both generators, the installable ZIP, and Git distributions. Only generation +tooling such as `.cli/` is removed. + +Preserve Twig autoescaping, translations, accessibility, WordPress hooks, and +the `#content` skip-link target when changing rendering. Existing Twig block +names and boundaries are public contracts; check their docs and exact-output +fixtures before changing them. + +## Validation and releases + +Use root `package.json` for maintainer commands and a generated theme's own +package for consumer commands. Install with `composer install` and +`npm ci --ignore-scripts`, then run: + +```sh +npm run lint:php +npm run pr:check +npm run test:generated-theme +npm run smoke:generation-parity +npm run release:check +``` + +`npm run docs:check-commands` checks documented npm commands. For static release +checks use `npm run release:check -- --skip-smoke`. Changes to rendering or +generation need the full WordPress fixture with WP-CLI and MySQL; set +`WP_SMOKE_REQUIRED=1` to fail when prerequisites are missing. Report checks run, +skips and their reasons, and any behavior still unverified. Storybook does not +exercise Timber context, ACF, or WordPress hooks. Empty generated projects have +no tests and intentionally fail `npm run test`; builds need library inputs. + +Use Conventional Commits. Do not bump versions outside the +[release procedure](docs/release-process.md): root `package.json` is the version +source, derived metadata must match, and publishing requires semantic-release +to compute the prepared committed version. Release checks require full Git +history and stable tags. Preserve generated-source lineage and unrelated +working-tree changes. Put user-facing changes in +`docs/release-notes-next.md` and consumer actions in `UPGRADE.md`. diff --git a/README.md b/README.md index 6ab6cc6..fec0467 100644 --- a/README.md +++ b/README.md @@ -1,8 +1,8 @@ - + # Emulsify WordPress -Emulsify WordPress 2.0.0 is a Timber-first WordPress parent theme for teams building component-driven sites with Emulsify Core 4, Vite, Storybook, and Twig. +Emulsify WordPress is a Timber-first WordPress parent theme for teams building component-driven sites with Emulsify Core 4, Vite, Storybook, and Twig. The parent theme provides the WordPress runtime: theme setup, Timber bootstrapping, Twig namespaces and helpers, template fallbacks, asset loading, and optional block registration. Generated child themes provide the project layer: components, templates, source Sass and JavaScript, compiled assets, and site-specific overrides. @@ -31,10 +31,10 @@ Use the named `emulsify.zip` asset, not GitHub's automatically generated **Sourc ## Requirements -- WordPress 6.7 or newer. +- WordPress 6.8 or newer. - PHP 8.3 or newer. - Composer 2 for Composer-based installation and parent-theme maintenance. -- Node.js 24. Root release tooling expects `>=24.10`; generated child themes expect `>=24`. +- Node.js 24.13.0 or newer for generated child themes: their `package.json` advertises `>=24`, but Emulsify Core 4.5.0 requires `>=24.13.0`. Root release tooling separately requires `>=24.10`. Both `.nvmrc` files select the Node 24 line without pinning a minor version. - Timber 2, installed by the site project or bundled in the manual release ZIP. - WP-CLI when generating child themes or running the full WordPress fixture smoke test. @@ -89,7 +89,7 @@ npm install | `npm run audit:twig-stories` | Check Twig story compatibility. | | `npm run inspect:components` | Discover components and report metadata, dependencies, configuration issues, and orphaned files. | | `npm run a11y` | Build Storybook and run the Core accessibility check. | -| `npm run test` | Run Jest with `--passWithNoTests` for starter projects. | +| `npm run test` | Run project Jest tests with coverage; fails when no tests exist. | The component inspector comes from the installed `@emulsify/core` package and runs from the generated child theme root without requiring WordPress to be @@ -115,7 +115,7 @@ The generated `whisk` child theme owns project implementation: - `whisk/src/components` is an empty placeholder until a project installs the component system it wants to use. - Source Sass, JavaScript, stories, data fixtures, and component metadata are defined by the selected Emulsify component system, not by this parent theme starter. - `whisk/assets/images` and `whisk/assets/icons` are empty placeholders for project-owned theme media and icon files. -- `whisk/templates/page.twig` is a small example override. +- New generated themes contain no Twig overrides or `templates/` directory. Add project templates only when needed; use the documented [Twig extension points](docs/template-extension.md). - `whisk/dist/global` and `whisk/dist/components` are runtime build output conventions when a component system emits them. - `whisk/project.emulsify.json` uses `"platform": "wordpress"` so Core and CLI tooling can load the WordPress platform adapter. It also records `generatedFrom` and `generatedFromVersion` so future upgrades and support diagnostics can identify Emulsify-generated WordPress child themes. Projects can also use Core-supported metadata such as `variant.structureImplementations` there when a selected component system needs legacy Twig namespaces. @@ -147,7 +147,10 @@ npm run lint:php `lint:php` runs PHPCS with `phpcs.xml.dist`, followed by PHPStan with `phpstan.neon.dist`. Both configurations cover `includes/` and the parent theme's root PHP entry points, including `functions.php`. Use `npm run lint:php:fix` to apply safe PHPCBF coding-standard fixes, then rerun `npm run lint:php` to confirm PHPStan and the remaining PHPCS checks. -The `.husky/pre-commit` hook already runs `npm run lint`, which delegates to this PHP check. +The `.husky/pre-commit` hook runs `npm run lint`, which delegates to this PHP +check. A normal `npm install` installs Husky 9 hooks in clones and worktrees. +After installing with `npm ci --ignore-scripts`, enable local hooks with +`npx --no-install husky`. | Command | Purpose | | --- | --- | @@ -155,9 +158,16 @@ The `.husky/pre-commit` hook already runs `npm run lint`, which delegates to thi | `npm run pr:check` | Run the practical, stubbed pull request validation suite. | | `npm run release:check` | Run release-readiness checks. | | `npm run build:dist` | Build the installable `dist-artifact/emulsify.zip` release archive. | -| `npm run publish-test -- --no-ci` | Run a local semantic-release dry run. | +| `npm run publish-test -- --no-ci` | Run a local release dry run after meeting the [prerequisites](docs/release-process.md#local-release-dry-runs). | -Every pull request to the configured branches runs two visible fast readiness jobs: practical smoke checks and dedicated PHPCS/PHPStan analysis. Pull requests targeting `main` or `release-2.x` additionally run the MySQL-backed WordPress fixture and Whisk Storybook accessibility audit. The WordPress job builds and extracts `emulsify.zip`, confirms its packaged generator and Whisk source, and sets `WP_SMOKE_REQUIRED=1`, so missing WP-CLI/MySQL prerequisites or route render failures fail the job instead of producing a skip. The Whisk job installs Chrome explicitly, copies an accessible CI-only story and Vite entry into the otherwise component-agnostic starter, and then builds Storybook and runs axe. +Every pull request to the configured branches runs two visible fast readiness jobs: practical smoke checks and dedicated PHPCS/PHPStan analysis. Pull requests targeting `main` or `release-2.x` additionally run the MySQL-backed WordPress fixture and Whisk Storybook accessibility audit. The PHP 8.3 practical lane builds `emulsify.zip`; the WordPress jobs verify and extract that same archive, confirm its packaged generator and Whisk source, and set `WP_SMOKE_REQUIRED=1`, so missing WP-CLI/MySQL prerequisites or route render failures fail the job instead of producing a skip. They also audit seven actual WordPress routes, including YouTube and Vimeo posters, with explicit WCAG 2.2 AA axe tags and save rendered HTML, results, and navigation evidence. The sole `target-size` exclusion reflects the unstyled parent; projects own target sizing and focus/helper styles. See [accessibility checks](docs/accessibility.md). + +Practical checks block on PHP 8.3, 8.4, and 8.5. The WordPress fixture blocks on +the minimum 6.8 and on `latest`, resolved at run time with the downloaded +version logged; nightly coverage is advisory. The theme is tested through +WordPress 7.1 (the current stable fixture resolved to 7.1.3 on October 23, 2026). + +The Whisk job selects and verifies the runner-installed Chrome with its sandbox enabled, copies an accessible CI-only story and Vite entry into the otherwise component-agnostic starter, runs seeded project tests, and then builds Storybook and runs axe. Storybook coverage supplements the actual WordPress route audit. Weekly scheduled runs repeat the WordPress fixture and Whisk accessibility audit. Manual GitHub Actions > `WordPress Theme Readiness` runs can select either extended fixture with the `wordpress_fixture` and `extended_checks` inputs. Local `release:check` still skips the database fixture when prerequisites are unavailable unless `WP_SMOKE_REQUIRED=1` is set. Release publishing also requires the full WordPress fixture path before semantic-release can publish. @@ -183,6 +193,12 @@ For Emulsify CLI integration, the standalone starter repository is `https://gith ## Documentation +This README, [UPGRADE.md](UPGRADE.md), and the guides in this repository are +authoritative for the WordPress 2.x workflow. The +[Emulsify documentation site](https://emulsify.info/docs) also covers older +tooling and other platforms; check a guide's platform and version before using +its commands. + - [Documentation index](docs/README.md) - [Generated-theme upgrade guide](UPGRADE.md) - [Upgrading from 1.x to 2.x](docs/upgrading-1x-to-2x.md) @@ -190,6 +206,8 @@ For Emulsify CLI integration, the standalone starter repository is `https://gith - [Generated child theme contract](docs/generated-child-theme-contract.md) - [Parent and child theme architecture](docs/parent-child-architecture.md) - [Timber and Twig authoring](docs/timber-and-twig-authoring.md) +- [Accessibility checks and project responsibilities](docs/accessibility.md) +- [Privacy and click-to-load media embeds](docs/media-embeds.md) - [Emulsify Core 4 and Vite workflow](docs/core-4-vite-workflow.md) - [Design token integration](docs/design-token-integration.md) - [Component recipes](docs/component-recipes.md) @@ -212,6 +230,9 @@ Emulsify WordPress is licensed under GPL-2.0-only. See [LICENSE](LICENSE). ## Contributing +Read the [contributor guidance](AGENTS.md) for repository ownership, both child +generators, validation commands, and release rules. + ### Code of conduct Read the [Code of Conduct](https://github.com/emulsify-ds/emulsify-wordpress/blob/main/CODE_OF_CONDUCT.md) before contributing. File bugs and feature requests at [emulsify-ds/emulsify-wordpress](https://github.com/emulsify-ds/emulsify-wordpress/issues). @@ -225,7 +246,9 @@ This repository uses [Conventional Commits](https://www.conventionalcommits.org/ - `feat!:` or a `BREAKING CHANGE:` footer produces a major release. - `docs:`, `test:`, `ci:`, and `chore:` produce no release. -A commit-msg hook validates the format with commitlint. See [docs/release-process.md](docs/release-process.md) for the full version strategy. +The `.husky/commit-msg` hook validates the format with commitlint after local +hooks are installed. See [docs/release-process.md](docs/release-process.md) for +the full version strategy. ### Release readiness diff --git a/UPGRADE.md b/UPGRADE.md index 1659dff..d3ffa14 100644 --- a/UPGRADE.md +++ b/UPGRADE.md @@ -4,6 +4,305 @@ Emulsify WordPress is a parent theme. Generated child themes do not inherit later starter changes, so most upgrades have two parts: update the parent theme, then decide which starter changes to adopt in each generated project. +## Upgrading from 2.0.0 to 2.1.0 + +Before updating the parent theme, review the conditional actions below against +the project's overrides and components. Existing generated child themes are not +rewritten: their copied scripts, configuration, templates, and documentation +remain project-owned. New generated themes receive the updated defaults. + +### Required actions + +1. **Update WordPress first if the site is on 6.7.** The parent now requires + WordPress 6.8 or newer, matching the locked Timber dependency. PHP remains + 8.3 or newer; the PHP and Timber dependency constraints do not change. +2. **Review component resolution if the project has ambiguous paths.** Project + references now follow Core's candidate order: a flat `component.twig` + precedes `component/component.twig`, and a child's grouped component wins + over a parent's direct component. Duplicate names resolve by root, direct + candidate, then breadth-first group order. `@components` now uses that same + grouped lookup: a grouped child source component can win over a direct file + in a later legacy or parent root. Use an explicit group or template path + where a project needs one particular component. + If `variant.structureImplementations` is configured, its `components` entry, + or its first accepted entry when none is named `components`, replaces the + default child component roots. Move components or use an explicit registered + namespace if includes relied on `src/components` or `components` staying + available alongside the override. Parent fallbacks remain available. + Implementation names are trimmed and lowercased; use plain identifiers + without an `@` prefix. Unnamed entries receive `structure-N` names. + Unregistered explicit prefixes now fall back to component lookup as in Core; + registered namespaces retain their scope. Literal prefixed component files + are tried before removing an unregistered prefix, matching Core. Registered + namespace colon aliases now use their named namespace. The `components:...`, + `components::...`, and `components/...` aliases now target component lookup; + use `@templates/components/...` for a controller template under that path. + Custom loaders need `getNamespaces()` and `getPaths()` to support this + integration; opaque loaders keep their native behavior. + Other bare paths keep every segment and stay with WordPress's normal Twig + loader. Correct references that relied on a + missing first segment falling back to another group. See the + [component resolution order](docs/timber-and-twig-authoring.md#component-includes). +3. **Apply the relevant fixes to child overrides.** Unmodified parent fallbacks + receive the fixes automatically; project copies need review: + - Move separate posts-page markup from `front-page.twig` to `home.twig`. + `front-page.twig` now serves only the front page, whether it shows posts or + a static page, ahead of `home.twig` or `page.twig`. Protected static front + pages still use the password template until the password is accepted. + - Mapped core-block templates receive a cached global Timber context and a + fresh block-specific `post`, without setting up WordPress's global post. + Add any required route-specific `posts`, `term`, `author` or `search_query` + values through the block context filter. Use `content` for current-block + HTML, rather than `post.content`. For blocks with children, `inner_content` + now equals the full rendered `content`, including its saved wrapper; print + one of them once. See [mapped block context](docs/core-block-twig-rendering.md#twig-context). + - `templates/partials/pagination.twig`: mark only `page.current` with + `aria-current="page"`; display a translated literal `…` in the existing + non-interactive span; decode Timber's display-escaped URL entities before + passing every page, previous, and next URL to `add_attributes`. + Decode numbered `page.title` entities once before Twig autoescaping, + for both linked and current numbers, so localized non-breaking thousands + separators display correctly. Never apply `|raw` to these titles. + - Numbered pagination links: prefix the number with translated `Page ` in + `span.screen-reader-text`. Keep the current-page span, ellipsis, and + Previous/Next text unchanged. + - `templates/partials/menu.twig`: mark only links whose `item.current` flag + is true with `aria-current="page"`; leave ancestors unmarked. + - Base layout: print Timber's trusted `site.language_attributes` fragment + as markup so `lang` and `dir` parse correctly, while retaining + autoescaping for other values. Keep `get_footer` before the footer block + and `wp_footer` afterward when copying the base layout. + - Argumentless Twig `bem()` and `add_attributes()` now read only inherited + `attributes`. Pass intended values explicitly if a template relied on + unrelated Timber context variables becoming attributes or BEM options. + Explicit-argument calls and the direct PHP helper API are unchanged. +4. **Check the rendered site's accessibility and link states.** Projects own + `screen-reader-text`, visible focus styles, and pointer target sizing. The + parent ships no stylesheet, but its `theme.json` produces WordPress global + styles on the frontend: h1–h6 color and typography, visited-link color, + root padding, button border radius/width and padding, and quote/cite + typography and margins plus cite color. It also produces preset custom + properties and `.has-*` classes, which style nothing until content uses + them. These rules do not supply the project's accessibility helpers. The + rendered audit disables + only axe's `target-size` rule; that exception does not establish WCAG 2.2 + SC 2.5.8 compliance. See + [project responsibilities](docs/accessibility.md#project-responsibilities). + The parent's normal pale-blue link color has been removed because it failed + contrast on white. Its unresolved hover, focus, and active declarations + have also been removed; those declarations caused color inheritance, so + removal can reveal an existing link color. Review normal, visited, and + focused links against project backgrounds. Quote text now inherits the + page's text color instead of the pale blue that failed contrast on white; + review project quote presentation. The removed button color object never + applied, and quote spacing is unchanged: the previously unresolved bottom + quote and top cite margins are now explicitly `0`. Other styles and + presets remain. +5. **Migrate block-data reads if the project opted into experimental core-block + Twig rendering.** In mapped templates and + `emulsify_theme_core_block_twig_context` filters, replace + `attributes.<key>` reads with `block_attributes.<key>` (in PHP, + `$context['block_attributes']['level']`, for example). Until migrated, those + reads return empty values because `attributes` is now an empty array reserved + for HTML attributes. Block data remains available as `block.attrs` and + `block_metadata.attrs`. Do not copy `anchor` or `className` into HTML + `attributes`: the wrapped WordPress content already carries them, and a + copied anchor would duplicate its ID. The PHP attribute bag also rejects + case-insensitive `on*` names to prevent event-handler attributes. See + [core-block context](docs/core-block-twig-rendering.md#twig-context). +6. **Review password-protected content in child overrides.** Check + `post.password_required` in copied `page.twig`, `single.twig`, + `partials/tease.twig`, and `partials/tease-post.twig` before printing protected + content or excerpts. The parent now enables Timber's password-form handling + for `post.content`, including child templates; `post.excerpt`, raw + `post.post_content`, and custom rendering still need an explicit guard. + Protected pages and posts share `single-password.twig`, which now uses + WordPress's filtered password form and site URL. Review styles targeting the + former custom form; core uses `.post-password-form`. See + [password-protected template handling](docs/template-extension.md#password-protected-content). +7. **Use WordPress escapers for formatted text in child overrides.** Print + post/page titles in headings and links with `|wp_kses_post`; site names, + archive/search titles, menu titles, and author names with `|esc_html`. + Strip literal tags with `wp_strip_all_tags` before `|esc_attr` for alt text, + including title fallbacks. These filters avoid encoding WordPress entities + twice while retaining output safety. Keep Twig autoescaping enabled and do + not substitute `|raw`. See + [WordPress-formatted text](docs/timber-and-twig-authoring.md#wordpress-formatted-text). + +8. **Review values passed to `bem()` and `add_attributes()`.** The PHP bag now + rejects `srcdoc`, all Alpine `x-*` and Vue `v-*` directives, and the + documented htmx expression-bearing families (including `data-hx-*` aliases). + Leading `:` bindings, native `on*` and `@` handlers are also rejected. URL + attributes use WordPress's allowed protocols; default policy strips + `javascript:` and `data:`. Replace data-URI image sources with permitted + URLs. Pass attribute maps as arrays, Traversables or `AttributeBag`, rather + than arbitrary objects such as `WP_Post`. `CLASS` now merges into `class`. + See [attribute rules](docs/timber-and-twig-authoring.md#attribute-helpers). + +9. **Use canonical names with Emulsify CLI.** Supply a machine name such as + `acme-site`, using lowercase ASCII letters, digits and single hyphens. The + starter rejects `Acme_Site` before rewriting files because the CLI has already + chosen that directory. Rerun with `--machineName acme-site`; WP-CLI continues + normalizing its `--machine-name` option. Nested pattern JSON is now validated + and rewritten by both generators; fix malformed or non-object JSON before + generation. Standalone display names and descriptions must also be plain + text without `<`; WordPress retains its own HTML sanitizer. See the [generation contract](docs/generated-child-theme-contract.md). + +10. **Cast lazy context URLs in PHP consumers.** `wp.logout_url` remains + available to Twig but is now a serializable stringable value to avoid + creating an unused nonce. PHP code passing it to strict string APIs should + use `(string) $context['wp']['logout_url']`. Output-cache JSON serialization + still materializes the URL to preserve the cache key's nonce variation. + +Render representative pages as both an administrator and an anonymous visitor, +check the editor where blocks are used, and inspect `debug.log`. Storybook +alone does not exercise Timber context or WordPress hooks. + +### Optional actions for existing generated themes + +Choose the changes below individually and preserve local customizations. A +parent update does not copy starter files into an existing child theme. + +#### Update Core and the effective Node version + +New child themes use Emulsify Core `^4.5.0`. To adopt it in an existing project, +change the dependency and refresh the project's lockfile with `npm install`: + +```diff + "dependencies": { +- "@emulsify/core": "^4.3.2" ++ "@emulsify/core": "^4.5.0" + } +``` + +Use Node.js 24.13.0 or newer for Core 4.5.0. The generated theme's `>=24` engine +and `.nvmrc` value `24` do not express that effective minor-version floor; check +the resolved Core package's engines after dependency updates. Core 4.5.0 adds +bounded accessibility concurrency and an optional +`@emulsify/core/a11y/wcag22` preset. The preset is not enabled automatically. + +#### Preserve every lint and format failure + +Adopting these copied script fixes is recommended so CI cannot silently pass a +failed first check. Update the existing project's `package.json`; both steps +still run: + +```diff + "scripts": { +- "lint": "npm run lint-js; npm run lint-styles", +- "lint-fix": "npm run lint-js -- --fix; npm run lint-styles -- --fix", +- "format": "npm run lint-fix; npm run prettier-fix", ++ "lint": "sh -c 'status=0; npm run lint-js || status=$?; npm run lint-styles || status=$?; exit $status'", ++ "lint-fix": "sh -c 'status=0; npm run lint-js -- --fix || status=$?; npm run lint-styles -- --fix || status=$?; exit $status'", ++ "format": "sh -c 'status=0; npm run lint-fix || status=$?; npm run prettier-fix || status=$?; exit $status'" + } +``` + +#### Adopt the Core accessibility runner + +The accessibility command stays the same before and after: + +```json +{ + "scripts": { + "a11y": "npm run storybook-build && node config/emulsify-core/run-a11y.js" + } +} +``` + +Update Core to `^4.5.0` first, then replace the copied +`config/emulsify-core/run-a11y.js` with the current starter's thin wrapper. +Changing `package.json` alone does not replace the old runner. The new wrapper +uses Core's bounded concurrency, complete reporting, and static server, while +retaining WordPress's failure when no stories are found. Core loads project +`config/emulsify-core/a11y.config.js` from the working directory and defaults +Storybook output to `.out`; existing `pa11y.wait` settings still apply. Preserve +project configuration and use a sandbox-capable Chrome. Never disable its +sandbox to make a check pass. Choosing the WCAG 2.2 preset remains optional. + +#### Run ESM tests and collect project coverage + +Copy `config/jest.config.js` from a fresh comparison theme and update both test +commands together, preserving project-specific Jest settings: + +```diff + "scripts": { +- "test": "jest --coverage --passWithNoTests --config ./config/jest.config.js", +- "twatch": "jest --no-coverage --watch --verbose --passWithNoTests --config ./config/jest.config.js", ++ "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js --coverage --config ./config/jest.config.js", ++ "twatch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --no-coverage --watch --verbose --config ./config/jest.config.js" + } +``` + +This optional migration makes an empty project's test command fail, matching new +generated themes. Add a real project test before enabling it in existing CI. +The defaults retain `rootDir: '..'` and the existing test locations, add +`transform: {}` and V8 coverage, and exclude dependencies, built files, stories, +and test files from source coverage. Coverage includes eligible project files +that tests do not import. Projects using JSX or TypeScript need their own +transformer that emits ESM. + +#### Keep audit JSON machine-readable + +The copied `audit` and `audit:twig-stories` wrappers now send their documentation +footers to stderr and preserve the underlying audit's exit status. Copy those +two script values from a fresh comparison theme if adopting the fix. If project +automation parses audit JSON, adopt it before relying on stdout as JSON, and +capture diagnostics separately. See the [project audit](#project-audit). + +#### Simplify template overrides + +New generated themes no longer ship `templates/page.twig` or a `templates/` +directory. Existing 2.x children can keep their override: it still inherits +parent fixes when it extends `@emulsify-tpl/page.twig` and calls `parent()`. +Search project CSS for the `.<machine>-page` wrapper, such as `.acme-site-page`, +before deleting the file. Remove it only if the wrapper is unused and the file +has no other project customizations. + +The new `site_header`, `main`, and `page_title` layout blocks are additive and +do not change the default output. Existing `head`, `header`, `content`, and +`footer` names and boundaries remain. Use the +[public template extension contract](docs/template-extension.md) when adding +an override, including preserving the `#content` skip-link target. A same-path +child override extends `@emulsify-tpl/...`; extending `@templates/...` resolves +back to itself. + +#### Enable privacy-friendly video embeds + +YouTube and Vimeo oEmbeds gain optional privacy mode and JavaScript-free +click-to-load posters. Both are off by default. Existing child themes inherit +the runtime and parent poster fallback without copying starter files. Enable +them with `emulsify_theme_media_embed_options` only after reviewing the site's +Content Security Policy. The `srcdoc` document inherits that policy, including +inline-style restrictions; the poster's CSS is confined to its iframe. + +Provider posters still request a third-party thumbnail before activation; +choose `poster: 'neutral'` to avoid that request. The provider receives data once +the player loads, and Back returns to the poster. A child can override +`templates/partials/oembed-poster.twig`. See [media embeds](docs/media-embeds.md) +for the options, override contract, metadata cache, and CSP requirements. + +#### Adopt project-local AI guidance + +New generated themes include `AGENTS.md`, `docs/wordpress-integration.md`, and +`.agents/skills/emulsify-wordpress-integration/SKILL.md`. Existing projects can +copy these token-free files from a fresh comparison theme and adapt them. Keep +the hidden `.agents/` directory when copying, and resolve the guide's links +within the project. Start assistant sessions in the child theme directory for +skill discovery. Generation does not change site-root agent instructions. + +### Release maintainers + +The release-tooling changes need no site runtime or generated-theme edits. +Maintainers need a full Git checkout with stable tags to run release checks. +Prepare root `package.json` and every derived version together in a release PR, +then confirm semantic-release computes that exact version. A checkout still at +the latest tagged version verifies GitHub publication in CI before skipping. +Use the [local dry-run requirements](docs/release-process.md#local-release-dry-runs) +for pushed branches and token setup. Follow the +[release PR procedure](docs/release-process.md#release-pr-procedure), including +re-syncing the standalone starter before release. + ## Upgrading from 1.x to 2.0.0 2.0.0 is a full rebuild of the WordPress theme around Timber, Emulsify Core 4, @@ -13,10 +312,10 @@ Step-by-step guidance lives in ### Requirements -- WordPress 6.7 or newer. +- WordPress 6.8 or newer. - PHP 8.3 or newer. - Timber 2.3 or newer, available to the parent theme. -- Node.js 24 or newer for generated child theme frontend tooling. Root release +- Node.js 24.13.0 or newer for generated child theme frontend tooling. Root release tooling requires Node.js 24.10 or newer. - Generated child themes keep `Template: emulsify` in `style.css` so WordPress loads the parent runtime. @@ -45,7 +344,7 @@ Step-by-step guidance lives in ### Package changes - Added: `timber/timber` `^2.3` as a parent theme requirement. -- Added: `@emulsify/core` `^4.3.2` in generated child themes. +- Added: `@emulsify/core` `^4.5.0` in generated child themes. - Added: PHPCS, PHPStan, WPCS, and WordPress/ACF/WP-CLI stubs as parent theme development requirements. - Removed: Webpack-era build dependencies from the starter. diff --git a/archive.php b/archive.php index b20c875..eff13f3 100644 --- a/archive.php +++ b/archive.php @@ -18,7 +18,7 @@ $page_title = __( 'Archive', 'emulsify' ); if ( is_day() ) { /* translators: %s is the archive date. */ - $page_title = sprintf( __( 'Archive: %s', 'emulsify' ), get_the_date( 'D M Y' ) ); + $page_title = sprintf( __( 'Archive: %s', 'emulsify' ), get_the_date( (string) get_option( 'date_format' ) ) ); } elseif ( is_month() ) { /* translators: %s is the archive month and year. */ $page_title = sprintf( __( 'Archive: %s', 'emulsify' ), get_the_date( 'M Y' ) ); @@ -31,9 +31,14 @@ $page_title = single_cat_title( '', false ); } elseif ( is_post_type_archive() ) { $page_title = post_type_archive_title( '', false ); - // Allow child themes to provide archive-{post_type}.twig before the generic - // archive fallback without adding more PHP template files. - array_unshift( $templates, '@templates/archive-' . get_post_type() . '.twig' ); + // Like WordPress' archive hierarchy, only a single queried type gets its + // own template. This also works when the archive has no current post. + $archive_post_types = array_filter( (array) get_query_var( 'post_type' ) ); + $archive_post_type = count( $archive_post_types ) === 1 ? reset( $archive_post_types ) : ''; + + if ( is_string( $archive_post_type ) && '' !== $archive_post_type ) { + array_unshift( $templates, '@templates/archive-' . $archive_post_type . '.twig' ); + } } $context = Timber::context( diff --git a/docs/README.md b/docs/README.md index efedea1..23a2baf 100644 --- a/docs/README.md +++ b/docs/README.md @@ -3,14 +3,19 @@ ## Getting started - [Generated-theme upgrade guide](../UPGRADE.md) +- [Required and optional 2.0.0 to 2.1.0 upgrade actions](../UPGRADE.md#upgrading-from-200-to-210) - [Upgrading from 1.x to 2.x](upgrading-1x-to-2x.md) - [Parent and child theme architecture](parent-child-architecture.md) - [WP-CLI child theme generation](wp-cli-child-theme-generation.md) - [Generated child theme contract](generated-child-theme-contract.md) +- [Dependency audit: October 23, 2026](dependency-audit-2026-10-23.md) ## Authoring - [Timber and Twig authoring](timber-and-twig-authoring.md) +- [Parent Twig extension points](template-extension.md) +- [Accessibility checks and project responsibilities](accessibility.md) +- [Privacy and click-to-load media embeds](media-embeds.md) - [Component recipes](component-recipes.md) - [Emulsify Core 4 and Vite workflow](core-4-vite-workflow.md) - [Design token integration](design-token-integration.md) @@ -29,10 +34,13 @@ - [Asset loading](asset-loading.md) - [Release process](release-process.md) -- [Next release notes draft](release-notes-next.md) +- [2.1.0 release notes (unreleased)](release-notes-next.md) +- [2.1.0 release PR checklist](release-notes-next.md#release-pr-checklist) - [Sister-project parity contract](sister-project-parity.md) +- [Drupal 7.3.0 sync log](sister-project-parity.md#sync-log) +- [How to run a sister-project sync](sister-project-parity.md#how-to-run-a-sync) - [Post-2.x optimization roadmap](post-2x-optimization-roadmap.md) ## Continuous integration -Every configured pull request runs practical smoke coverage and a dedicated PHPCS/PHPStan job. Pull requests targeting `main` or `release-2.x` additionally run the required MySQL/WP-CLI WordPress rendering fixture and a CI-seeded Whisk Storybook accessibility audit. Weekly scheduled runs repeat both extended fixtures. Manual readiness runs use the `wordpress_fixture` and `extended_checks` inputs to select those extended jobs. The release process documents commands, route coverage, and merge-gate details. +Every configured pull request runs practical smoke coverage and a dedicated PHPCS/PHPStan job. Pull requests targeting `main` or `release-2.x` additionally run the required MySQL/WP-CLI WordPress rendering fixture and a CI-seeded Whisk Storybook accessibility audit. The WordPress job also audits seven rendered routes, including YouTube and Vimeo posters, with explicit WCAG 2.2 AA tags and retains per-route evidence; see [accessibility checks](accessibility.md) for the sole target-size exception and project responsibilities. Weekly scheduled runs repeat both extended fixtures. Manual readiness runs use the `wordpress_fixture` and `extended_checks` inputs to select those extended jobs. The release process documents commands, route coverage, and merge-gate details. diff --git a/docs/accessibility.md b/docs/accessibility.md new file mode 100644 index 0000000..c6ae314 --- /dev/null +++ b/docs/accessibility.md @@ -0,0 +1,158 @@ +# Accessibility checks + +The parent theme supplies semantic fallback markup and WordPress integration. +It ships no stylesheet, but its `theme.json` produces WordPress global styles +on the frontend: h1–h6 color and typography, visited-link color, root padding, +button border radius/width and padding, and quote/cite typography and margins +plus cite color. It also produces preset custom properties and `.has-*` +classes, which style nothing until content uses them. Projects own the final +visual presentation, target sizes, focus indicators, and any visually hidden +text helpers their pages need. + +## Check Storybook and WordPress + +Run `npm run a11y` from a generated child theme to build and audit its Storybook +stories through Emulsify Core. The CI-seeded story exercises the component +toolchain without adding a component library to the committed starter. + +Stories do not execute WordPress route selection, Timber context, menus, ACF, +plugins, or the parent layout. The separate rendered WordPress audit checks +actual HTTP pages from a disposable generated and activated child theme. Its +Puppeteer and axe dependencies come from that child's installed Emulsify Core +dependency tree, rather than a separate root accessibility stack. + +From a maintainer checkout, install Composer and root npm dependencies, configure +the fixture's `WP_SMOKE_DB_HOST`, `WP_SMOKE_DB_PORT`, `WP_SMOKE_DB_USER`, and +`WP_SMOKE_DB_PASSWORD`, and provide a sandbox-capable Chrome: + +```sh +WP_SMOKE_REQUIRED=1 WP_SMOKE_A11Y=1 \ + PUPPETEER_EXECUTABLE_PATH="/path/to/google-chrome" \ + npm run release:check +``` + +WP-CLI, PHP with mysqli, and MySQL are required. `WP_SMOKE_A11Y=1` opts into the +browser audit; `WP_SMOKE_REQUIRED=1` prevents missing WordPress prerequisites +from producing a skip. The normal runtime fixture without the accessibility +flag does not establish browser-audit coverage. `--skip-smoke` skips the fixture +and its browser audit. See [the release process](release-process.md) for setup. + +The fixture calls the `auditRenderedPages` API exported by +`.github/scripts/rendered-a11y.cjs` while its HTTP server is live. A separate +CLI is available for an already running site: + +```text +node .github/scripts/rendered-a11y.cjs <generated-theme-dir> <routes.json> <output-dir> +``` + +The WordPress readiness job enables the browser audit and verifies the runner's +installed Chrome can launch with its sandbox. Do not disable Chrome's sandbox +to make an audit pass. + +## Rendered route and navigation coverage + +The fixture uses plain permalinks and audits these anonymous routes: + +| Route | Fixture request | +| --- | --- | +| Home | `/` | +| Page | `/?page_id=<page-id>` | +| Single post | `/?p=<post-id>` | +| Category archive | `/?cat=<category-id>` | +| Search | `/?s=Smoke%20post%20content` | +| Category archive, page 2 | `/?cat=<category-id>&paged=2` | +| Media embeds | `/?page_id=<media-page-id>` | + +During these audits, `posts_per_page` is 1 and at least 12 posts belong to the +category. The second archive page therefore exercises the actual current page, +numbered links, previous/next links, and a non-interactive ellipsis with the +fallback's `mid_size: 3` and `end_size: 2` settings. + +Navigation assertions supplement axe. The runtime fixture follows a search +pagination link and verifies its destination. The rendered audit checks +meaningful content and, on the second archive page, exactly one +`aria-current="page"` in its pager, current page 2, and a literal non-interactive +ellipsis without `aria-current`. The fixture assigns a primary menu with page, +post, and category links and checks the matching current link on those routes. +Current-state counts are scoped to each navigation region: a menu and pager +may each correctly have a current item. The fallback marks current menu items +only, leaving ancestors unmarked. + +The media page opts into privacy mode and neutral click-to-load posters for a +classic YouTube embed and a Vimeo `core/embed` block. Axe also runs inside both +`srcdoc` documents, and neutral posters must make no third-party requests. +Separate browser checks disable page JavaScript, activate each player by +keyboard inside the same frame, preserve Vimeo's unlisted `h` parameter, and +check focus visibility, compact controls, thumbnail referrers, and Back history. +The opt-in poster's styles live only inside its iframe document; see +[media embeds](media-embeds.md) for the options and CSP requirements. + +Numbered pagination links include a translated `Page ` prefix in a +`span.screen-reader-text`, giving a link such as `Page 2` an explicit name. +Only linked page numbers receive the prefix. The current-page span, ellipsis, +and already named Previous/Next links retain their existing text and BEM +classes. This markup change adds no stylesheet. + +## Axe policy and artifacts + +The rendered audit explicitly selects these axe tags: + +```text +wcag2a, wcag2aa, wcag21a, wcag21aa, wcag22aa +``` + +This includes WCAG 2.2 AA rules rather than relying on a runner's default tag +selection. Failed HTTP responses, browser or audit execution errors, failed +render/navigation assertions, and any reported violation of the enabled rules +fail the audit. + +The sole disabled axe rule is `target-size`. This is a narrow test-policy +exception for parent fallbacks without target-size styling: the retained +global styles do not enlarge or space navigation links for this criterion. +It is not an exemption from WCAG or a claim that +the rendered site meets Target Size (Minimum). No other selected rule is +disabled. + +Results go to `.artifacts/wordpress-a11y` by default; set +`WP_SMOKE_A11Y_OUTPUT` to choose another directory. Each route saves rendered +HTML, full axe JSON including incomplete checks, and computed-style evidence +for screen-reader text. CI retains them as +`wordpress-rendered-a11y-<matrix-version>`, including on failure. Inspect +incomplete results manually; an automatic pass cannot resolve those checks. + +The parent document shell preserves WordPress's trusted language attributes as +markup so the browser parses `lang` correctly. Normal link colors now fall +through to WordPress core, browser, or project styles rather than the former +pale-blue theme rule that failed contrast on white. The existing visited-link +rule is retained. Projects must verify their final colors against actual +backgrounds. + +## Project responsibilities + +Projects must meet [WCAG 2.2 SC 2.5.8, Target Size (Minimum)](https://www.w3.org/WAI/WCAG22/Understanding/target-size-minimum.html): +provide pointer targets of at least 24 by 24 CSS pixels or satisfy an applicable +criterion exception, such as sufficient spacing. Audit the styled project with +`target-size` enabled; the parent fixture's exclusion must not hide project +regressions. + +Ensure `screen-reader-text` remains available to assistive technology while +being visually hidden where intended. Do not use `display: none` or +`visibility: hidden` for spoken link labels. Verify the actual loaded WordPress +and project styles: a class name alone does not hide text. Projects must supply +a compatible helper if their asset policy does not provide one. + +In the WordPress 6.8 fixture, core's loaded +`wp-includes/css/dist/block-library/style.min.css` supplies `.screen-reader-text`. +Before focus, both the skip link and pagination prefix measure 1 by 1 CSS +pixels, with absolute positioning, hidden overflow, and `clip-path: inset(50%)`. +The parent adds no helper CSS. Projects that disable the core stylesheet must +provide an equivalent accessible helper and verify its focus behavior. + +Preserve a visible keyboard focus indicator on every interactive control, as +required by [SC 2.4.7, Focus Visible](https://www.w3.org/WAI/WCAG22/Understanding/focus-visible.html). +Check the skip link reveals itself on focus and reaches `#content`, menu and +pagination operation, heading structure, zoom/reflow, contrast, and screen +reader announcements on real project content. Test anonymous and relevant +signed-in states, editor previews, and plugin integrations. Automated axe +results are useful evidence, not complete WCAG conformance or a replacement +for keyboard and assistive-technology testing. diff --git a/docs/acf-twig-blocks.md b/docs/acf-twig-blocks.md index db4ef67..e2863ed 100644 --- a/docs/acf-twig-blocks.md +++ b/docs/acf-twig-blocks.md @@ -106,3 +106,11 @@ Scoped asset records can be adjusted before registration with `emulsify_theme_ac The child theme is scanned before the parent theme. Duplicate component paths, duplicate component slugs, and duplicate final ACF block `name` values are skipped instead of being registered twice. When `WP_DEBUG` is enabled, skipped duplicates are logged and shown as admin-only notices to users who can edit themes. Normal frontend visitors do not see duplicate diagnostics. + +### Scoped assets in subfolders + +Asset paths declared by `*.component.json` remain component-scoped even when +CSS or JavaScript lives in nested folders. The parent reuses its component +metadata index and asset scan, including custom asset-only roots. Editor-only +files are excluded from global frontend enqueueing; components without a Twig +template retain that exclusion too. diff --git a/docs/component-recipes.md b/docs/component-recipes.md index 54ed823..86e3f14 100644 --- a/docs/component-recipes.md +++ b/docs/component-recipes.md @@ -159,3 +159,9 @@ add_filter( ``` Keep this opt-in narrow. Replacing core block markup can affect block validation, editor expectations, accessibility, and plugin integrations. + +Mapped templates read block data from `block_attributes`, for example +`block_attributes.level` for a heading. The context's `attributes` starts as an +empty array reserved for HTML attributes; do not copy block data into it because +`bem()` and `add_attributes()` merge it into markup. See +[the mapped template context](core-block-twig-rendering.md#twig-context). diff --git a/docs/core-4-vite-workflow.md b/docs/core-4-vite-workflow.md index 644a70c..8d7e1b6 100644 --- a/docs/core-4-vite-workflow.md +++ b/docs/core-4-vite-workflow.md @@ -60,7 +60,7 @@ Run these from the generated child theme directory: | `npm run audit:twig-stories` | Check Twig story compatibility. | | `npm run inspect:components` | Discover components and report metadata, dependencies, configuration issues, and orphaned files. | | `npm run a11y` | Build Storybook and run the Core accessibility check. | -| `npm run test` | Run Jest with `--passWithNoTests` for starter projects. | +| `npm run test` | Run project Jest tests with coverage; fails when no tests exist. | ### Component inspector diff --git a/docs/core-block-twig-rendering.md b/docs/core-block-twig-rendering.md index 284bf27..059d620 100644 --- a/docs/core-block-twig-rendering.md +++ b/docs/core-block-twig-rendering.md @@ -26,22 +26,50 @@ add_filter( ); ``` -Mapped template paths are child/parent theme relative. The active child theme is checked first, then the parent theme. If a block is not mapped, or the mapped Twig file is not readable, WordPress' original rendered block content is returned unchanged. +Mapped template paths are child/parent theme relative. The active child theme is checked first, then the parent theme. If a block is not mapped, or the mapped Twig file is not a readable file, WordPress' original rendered block content is returned unchanged. ## Twig context -Mapped templates receive the normal Timber context plus these values: +Mapped templates receive Timber's global context plus these values: +- `post`: the Timber post identified by the block context's `postId`, or the + current global WordPress post when no `postId` was supplied. An explicitly + missing or invalid `postId` produces `null`. - `block`: parsed block metadata from `render_block`. - `block_metadata`: alias for `block`. - `block_name`: block name such as `core/paragraph`. -- `attributes`: parsed block attributes. +- `attributes`: an empty array reserved for HTML attributes. +- `block_attributes`: the parsed block attributes, also available as + `block.attrs` and `block_metadata.attrs`. - `content`: WordPress' original rendered block content. -- `inner_content`: rendered inner content fallback for templates. +- `inner_content`: saved string fragments for a leaf block; the full rendered + `content` when fragments contain child placeholders or no usable text. - `inner_blocks`: parsed inner block records when available. - `wp_block`: the `WP_Block` instance when WordPress passes one. - `twig_template`: the mapped Twig template. +`inner_content` includes the saved block's wrapper. For a group, quote or other +block containing children, it deliberately equals `content`, including every +child's final rendered output. Children are never rendered again. Capturing +generic `render_block` output would miss later block-name filters and children +replaced through `pre_render_block`, so the renderer uses WordPress's assembled +HTML. Print either `content` or `inner_content` once; printing both duplicates +the block. Neither value promises wrapper-free children for a replacement +component wrapper. + +The shared renderer builds its global base once during the request with +`Timber::context_global()`. It creates each block's `post` without calling +`setup()`, preserving Query Loop globals and avoiding extra `the_post` actions. +Route-specific values that `Timber::context()` adds, such as `posts`, `term`, +`author` or `search_query`, are not added automatically; supply them through the +block context filter when needed. + +Keep block data separate from HTML attributes: `bem()` and `add_attributes()` +merge the context's `attributes` into their output. Never put block data or +untrusted user input there. The renderer does not copy `anchor` or `className` +into this array; WordPress' rendered `content` already carries those values, +and copying an anchor would duplicate its ID. + Use `emulsify_theme_core_block_twig_context` to add project-specific values: ```php @@ -49,7 +77,7 @@ add_filter( 'emulsify_theme_core_block_twig_context', function ( array $context, array $block ): array { if ( 'core/heading' === ( $block['blockName'] ?? '' ) ) { - $context['heading_level'] = $context['attributes']['level'] ?? 2; + $context['heading_level'] = $context['block_attributes']['level'] ?? 2; } return $context; @@ -59,6 +87,11 @@ add_filter( ); ``` +The context and template-selection filters still run for every mapped block. +The template-map filter also runs for each block, preserving dynamic callbacks +and filters added or removed after rendering starts. Only normalization of an +unchanged map result is cached; callback results are not frozen for the request. + ## Optional class cleanup The renderer does not strip `wp-block` classes by default. If a project needs class cleanup, opt in separately: @@ -73,6 +106,12 @@ Cleanup uses `WP_HTML_Tag_Processor` when available and otherwise leaves Twig ou If a mapped template throws an exception or Timber is unavailable, normal frontend visitors receive WordPress' original block output. Diagnostics are only appended for users who can edit posts or edit theme options, and debug logging only runs when `WP_DEBUG` is enabled. +If Twig or a mapping/context filter re-enters mapped block rendering, that +nested call returns WordPress's original markup. This bounds recursion from a +template that prints `post.content`. Use `content` for the current block instead. +Ordinary parsed inner blocks have already rendered before the parent template +runs and are unaffected by this guard. + ## Filters - `emulsify_theme_core_block_twig_rendering_enabled` diff --git a/docs/dependency-audit-2026-10-23.md b/docs/dependency-audit-2026-10-23.md new file mode 100644 index 0000000..517fc59 --- /dev/null +++ b/docs/dependency-audit-2026-10-23.md @@ -0,0 +1,142 @@ +# Dependency audit — October 23, 2026 + +The targeted root npm update reduces the audit from **10 vulnerable package +entries (1 critical, 8 high, 1 moderate)** to **7 (6 high, 1 moderate)**. +The root runtime audit, `npm audit --omit=dev`, reports zero findings. All +remaining entries belong to development-only release tooling; this audit does +not cover dependencies installed separately by generated child themes. + +## Compatible updates + +| Lockfile entry | Before → after | Dependency owner | +| --- | --- | --- | +| `handlebars` | 4.7.9 → 4.7.10 | `conventional-changelog-writer` | +| `js-yaml` | 4.3.0 → 4.3.2 | Root YAML contract checks and release tooling | +| `fast-uri` | 3.1.5 → 3.1.9 | `ajv` | +| `@actions/http-client` → `undici` | 6.27.0 → 6.29.1 | `@semantic-release/npm` → `@actions/core` | +| Root `undici` | 7.28.0 → 7.30.1 | `@semantic-release/github` | + +The direct `js-yaml` pin changes from `4.3.0` to `4.3.2`; its exact pin otherwise +prevents `npm update` from selecting the fix. All other manifest ranges stay +unchanged. There are no overrides, dependency major upgrades, engine changes, +or theme version changes. npm also removes a redundant optional peer copy of +`conventional-commits-filter` 6.0.1 from the lockfile. + +Fast URI 3.1.9 includes the fix for +[GHSA-hrr3-gc8f-f4qj](https://github.com/advisories/GHSA-hrr3-gc8f-f4qj), whose +affected range includes 3.1.7. The independently resolved Handlebars, JS-YAML, +Fast URI and Undici copies are absent from the final audit findings. + +## Remaining findings and ownership + +Every remaining finding is inside +`semantic-release` → `@semantic-release/npm` 13.1.5 → `npm` 11.18.0. npm bundles +these dependencies, so updating the independent packages above does not replace +them. + +| Bundled package | Installed version | Audit severity | Follow-up owner | +| --- | --- | --- | --- | +| `brace-expansion` | 5.0.7 | High | npm bundle; root maintainers can evaluate a separate npm lock update. | +| `http-cache-semantics` | 4.2.0 | High | npm bundle; root maintainers can evaluate a separate npm lock update. | +| `ip-address` | 10.2.0 | High | npm bundle; root maintainers can evaluate a separate npm lock update. | +| `postcss-selector-parser` | 7.1.4 | Moderate | npm bundle; root maintainers can evaluate a separate npm lock update. | +| `tar` | 7.5.19 | High | npm bundle; root maintainers can evaluate a separate npm lock update. | +| `undici` | 6.27.0 | High | npm bundle; root maintainers can evaluate a separate npm lock update. | + +The seventh entry is the propagated high finding on `npm` itself, via `tar`; +these are package entries, not seven independent vulnerabilities. The installed +`@semantic-release/npm` accepts npm `^11.6.2`, so a separate compatible npm update +can be assessed without changing the release plugin's major version. It was +outside this four-package update; no bundled leaf was replaced manually. + +Root `micromatch` 4.0.8 also depends on `braces` 3.0.3. Neither is reported by +this audit response. If that path is flagged by a future audit, the dependency +owners are `braces`/`micromatch` and their release-tooling consumers; a generated +theme's Core/Stylelint tree must be assessed separately. A clean runtime audit +does not establish that development tooling or generated projects are free of +security issues. + +## Reproduction + +Commands ran with Node 24.22.1 and npm 11.19.1: + +```sh +npm audit --json +# Update the existing exact js-yaml pin to 4.3.2 first. +npm update handlebars js-yaml fast-uri undici --ignore-scripts +npm ci --ignore-scripts +npm audit --json +npm audit --omit=dev --json +npm run test:generated-theme +``` + +The clean install succeeds. Both full audits exit 1 because findings remain; +the runtime audit exits 0. The generated-theme contract tests verify the YAML +guidance checks with the updated parser. Results are point-in-time registry +observations, and should be refreshed before the release. + +## October 28 release-tooling refresh + +The snapshots above remain the October 23 observations. On October 28, the +root tooling was refreshed to the baselines in the published Drupal 7.3.0 +release, using Node 24.22.1 and npm 11.19.1: + +| Direct development dependency | Range before → after | Locked version before → after | +| --- | --- | --- | +| `semantic-release` | `^25.0.8` → `^25.0.9` | 25.0.8 → 25.0.9 | +| `@semantic-release/github` | `^12.0.9` → `^12.0.10` | 12.0.9 → 12.0.10 | +| `@commitlint/cli` | `^21.2.1` → `^21.2.4` | 21.2.1 → 21.2.4 | +| `@commitlint/config-conventional` | `^21.2.0` → `^21.2.4` | 21.2.0 → 21.2.4 | +| `lint-staged` | `^17.3.0` → `^17.6.0` | 17.3.0 → 17.6.0 | + +Only those five `devDependencies` and their lockfile resolutions change. +`js-yaml` stays pinned and locked at 4.3.2. Theme versions, Composer dependencies, +Whisk dependency ranges, release plugins and the prepared-version policy are +unchanged. The update uses `npm install --save-dev --ignore-scripts`, followed +by a clean `npm ci --ignore-scripts`; no audit fix or overrides were applied. + +### Before and after findings + +| Audit | Before refresh | After clean installation | Exit status | +| --- | --- | --- | --- | +| `npm audit --json` | 6 package entries: 5 high, 1 moderate | Same 6 entries and severities | 1 both times | +| `npm audit --omit=dev --json` | 0 findings | 0 findings | 0 both times | + +The before snapshot already differs from October 23's seven entries; that +point-in-time registry difference is not a result of this refresh. None of the +six October 28 findings was fixed by the five targeted updates: + +| Package | Installed before and after | Severity | Dependency owner | Ships in parent ZIP? | +| --- | --- | --- | --- | --- | +| `brace-expansion` | 5.0.7 | High | npm 11.18.0's bundled dependencies | No | +| `ip-address` | 10.2.0 | High | npm 11.18.0's bundled dependencies | No | +| `postcss-selector-parser` | 7.1.4 | Moderate | npm 11.18.0's bundled dependencies | No | +| `tar` | 7.5.19 | High | npm 11.18.0's bundled dependencies | No | +| `undici` | 6.27.0 | High | npm 11.18.0's bundled dependencies | No | +| `npm` | 11.18.0 | High, propagated via `tar` | `@semantic-release/npm` 13.1.5 | No | + +All six paths are under `semantic-release` → `@semantic-release/npm` 13.1.5 → +its bundled npm 11.18.0. The npm plugin still accepts npm `^11.6.2`; evaluating +a separate update of that bundle remains a maintainer follow-up. This plugin +is installed as a semantic-release dependency, but WordPress's explicit release +plugin list does not use it to write or publish npm version metadata. The npm +entry is propagated, so these counts are package entries, not six independent +vulnerabilities. + +The parent ZIP excludes root npm manifests, `node_modules`, and release tools; +it contains production Composer dependencies instead. A before/after ZIP +comparison at the same Git HEAD confirmed 616 identical entry paths and +byte-identical runtime/vendor files; only documentation changed. This audit +covers the root npm tree, not Composer +packages or dependencies installed separately by generated child themes. + +Reproduce the targeted update and audit with: + +```sh +npm audit --json +npm audit --omit=dev --json +npm install --save-dev --ignore-scripts 'semantic-release@^25.0.9' '@semantic-release/github@^12.0.10' '@commitlint/cli@^21.2.4' '@commitlint/config-conventional@^21.2.4' 'lint-staged@^17.6.0' +npm ci --ignore-scripts +npm audit --json +npm audit --omit=dev --json +``` diff --git a/docs/generated-child-theme-contract.md b/docs/generated-child-theme-contract.md index 42c54ce..47004d0 100644 --- a/docs/generated-child-theme-contract.md +++ b/docs/generated-child-theme-contract.md @@ -11,21 +11,43 @@ Emulsify WordPress supports two ways to create a child theme: - **In-site WP-CLI.** `wp emulsify "Acme Site" --machine-name=acme-site` copies the bundled Whisk starter from the installed parent theme and applies targeted metadata updates. - **Standalone starter.** Emulsify CLI clones [`emulsify-wordpress-starter`](https://github.com/emulsify-ds/emulsify-wordpress-starter), installs dependencies, and runs the starter's `.cli/init.js` hook. -These are separate implementations in different languages, so the release checks generate the same identities through both paths and require their file trees to match. The only expected difference is the lockfile the standalone path creates during `npm install`. +Machine names use lowercase ASCII letters, digits and single hyphens, with no +leading or trailing hyphen. WP-CLI normalizes `--machine-name=Acme_Site` to +`acme-site`. Emulsify CLI currently chooses its destination before the starter +hook runs, so pass `--machineName acme-site`; the hook rejects noncanonical +names with a suggested correction instead of renaming a directory behind the +CLI. Upstream CLI normalization must happen before directory creation. + +These are separate implementations in different languages, so the release checks generate the same identities through both paths and require their file trees to match. For accepted plain-text input, the only expected difference is the lockfile the standalone path creates during `npm install`. ## What the contract guarantees -- The machine name, display name, and description are applied consistently to `style.css` headers, `package.json`, `project.emulsify.json`, `functions.php`, `templates/`, and `patterns/`. +- The machine name, display name, and description are applied consistently to `style.css` headers, `package.json`, `project.emulsify.json`, `functions.php`, and `patterns/`. +- A fresh generated theme ships no Twig templates or `templates/` directory; + the parent renders page fallbacks. Consumers can add their own overrides + later using the [template extension contract](template-extension.md). - `style.css` keeps `Template: emulsify` so WordPress loads the Emulsify parent runtime, and preserves the starter's license metadata. - `package.json` is valid JSON, uses the generated machine name, retains every Emulsify Core npm script, and keeps the starter's `@emulsify/core` range. - `project.emulsify.json` is valid JSON and retains `platform`, the generated `machineName`, `generatedFrom`, `generatedFromVersion`, and the `starter` repository block. - `README.md`, `docs/development.md`, `docs/upgrading.md`, and `docs/support-information.md` are present. The README contains the requested display name, machine name, description, source project, source version, and Emulsify Core range, and the guides document only npm commands that the generated `package.json` exposes. +- `AGENTS.md`, `docs/wordpress-integration.md`, and + `.agents/skills/emulsify-wordpress-integration/SKILL.md` ship unchanged from + the generation source, including the hidden skill directory. The skill has + valid YAML frontmatter, and guidance links resolve inside the child theme. + These files contain no identity placeholders; projects can customize their + copies after generation. - No `%%EMULSIFY_*%%` documentation token survives generation. An unreplaced token fails generation rather than shipping to a project. - No starter identity survives: the machine name `whisk`, the display name `Whisk`, and legacy `EMULSIFY_NAME` placeholders are all absent. - Generation-only tooling and build output are absent, including `.cli`, `node_modules`, `dist`, `.out`, and `.coverage`. - Generated files are self-contained: no symbolic links, no documentation links that resolve outside the theme, and no script paths that point outside the theme except published packages under `node_modules/`. - Generated Markdown uses current terminology; retired Webpack and "subtheme" language fails the check. -- Both generation paths write JSON with two-space indentation, so generated metadata is byte-identical regardless of path. +- Both generation paths preserve JSON objects and lists, write two-space + indentation, and rewrite nested `patterns/` namespaces. Malformed or + non-object pattern JSON fails with its relative path before installation or + metadata rewrites. Accepted plain-text labels and descriptions remove + percent-encoded octets consistently. Standalone init rejects `<` in either + field before writing; WordPress retains its native HTML stripping. Supply + plain text to Emulsify CLI rather than depending on PHP's tag parser. ## Outside the contract @@ -52,6 +74,26 @@ npm run release:check -- --skip-smoke `npm run test:generated-theme` runs focused contract tests that generate a throwaway theme and then mutate it to prove each class of failure is detected. `npm run smoke:generation-parity` generates through both paths and compares them; it requires a PHP binary and skips with a warning when none is available. +The validator's `--check-built-assets` mode checks an installed, built consumer +theme: it requires `dist/`, allows dependency/build directories and customized +guidance, and still rejects `.cli/`. Guidance presence, skill metadata, local +links, and documented commands remain checked; only the fresh-copy byte +comparison is relaxed. + +To verify generated audit wrappers against an actual packed Core artifact, run: + +```sh +EMULSIFY_CORE_TARBALL=/absolute/path/emulsify-core-4.5.0.tgz npm run test:audit-wrappers +``` + +This opt-in test generates a temporary child theme and installs that package +without installer hooks. It compares both wrappers with the installed Core +executables, checks complete JSON stdout, stderr footers, exit codes 0/1/2, and +arguments containing spaces. Negative controls prove that stdout footers, +masked failures, and dropped arguments are detected. It requires Node 24 and +registry access for the packed package's dependencies; it leaves the source +theme and dependency ranges unchanged. + The full release check additionally exercises a real WordPress fixture: ```bash @@ -66,6 +108,11 @@ That requires Node.js, PHP, Composer, MySQL, WP-CLI, and network access. - **WordPress metadata:** A `style.css` header does not match the requested identity, or `functions.php` still describes the starter. - **Frontend metadata:** `package.json` or `project.emulsify.json` lost a required key, an npm script, or the Emulsify Core range. - **Documentation:** A required generated guide is missing, still contains a source token, lost project-specific metadata, or documents an npm command the generated package does not expose. Fix the Whisk documentation template or the generation post-processors. +- **AI guidance:** A guidance file is missing or changed during generation, + skill frontmatter is invalid, or a guidance link is missing or escapes the + theme. Fix the source or copy path; byte comparison applies to fresh + generation, while built/customized themes may edit their guidance. Skill + metadata and links must remain valid. - **Placeholder replacement:** A starter name or token survived. Both generators must be updated together; a token added to the templates without a matching replacement in each generator fails the release check. - **File references:** A documentation link or script path escapes the generated theme. diff --git a/docs/media-embeds.md b/docs/media-embeds.md new file mode 100644 index 0000000..e7cb387 --- /dev/null +++ b/docs/media-embeds.md @@ -0,0 +1,172 @@ +# Media embeds + +The parent theme can apply privacy mode and a click-to-load poster to WordPress +YouTube and Vimeo oEmbeds. Both options are off by default, so existing embeds +keep their original HTML. Other providers, unsupported player URLs, and +malformed embed HTML are left untouched. +Embeds with an existing `srcdoc` or `sandbox` attribute also remain unchanged, +preserving another integration's document and restrictions. + +## Options + +Use the `emulsify_theme_media_embed_options` filter in the child theme or a +project plugin. There is no settings screen: + +```php +add_filter( + 'emulsify_theme_media_embed_options', + function ( array $options ): array { + $options['privacy_mode'] = true; + $options['click_to_load'] = true; + $options['poster'] = 'neutral'; + + return $options; + } +); +``` + +The filter also receives the original `$url`, embed attributes `$attr`, and +`$post_id`; register the callback with four accepted arguments to use them. +The post ID is a positive `int`, or `null` outside a post (for example, an embed +rendered outside the loop). Non-string URLs normalize to `''`, and non-array +attributes normalize to `array()`. String post IDs must contain only decimal +digits and fit a positive PHP integer; whitespace and a leading `+` are rejected. + +| Option | Default | Behavior | +| --- | --- | --- | +| `privacy_mode` | `false` | Uses YouTube's `www.youtube-nocookie.com` player host and adds Vimeo's `dnt=1`. Other parameters remain intact, including Vimeo's `h` for unlisted videos. | +| `click_to_load` | `false` | Replaces the player with a native **Play video** link that opens the player inside the same frame with `autoplay=1`, without JavaScript. | +| `poster` | `'provider'` | Uses a provider thumbnail when available; `'neutral'` omits third-party images. This option takes effect only when click to load is enabled. | + +Privacy mode by itself still loads the player when the page is viewed. Click to +load prevents a visitor's browser from requesting the player before activation. +Provider posters still contact the thumbnail host before activation, revealing +the visitor's network address. Their images use native lazy loading and async +decoding, but the browser decides when to fetch them; lazy loading is not a +privacy guarantee. Choose a neutral poster to avoid that image request too. +The provider receives data once the player loads, and its cookies, consent +behavior, and browser autoplay restrictions still apply. + +The parent transforms the `embed_oembed_html` output at render time, after +WordPress retrieves its cached oEmbed HTML. This covers classic-content embeds +and `core/embed` blocks. Changing these options does not require flushing the +oEmbed cache. Hand-written iframe HTML that bypasses WordPress oEmbed is outside +this filter. + +YouTube posters use the video's provider thumbnail; playlist players use a +neutral poster because `videoseries` is not a video ID. Vimeo posters use +cached `thumbnail_url` metadata captured from WordPress oEmbed responses only +when click to load and provider posters are enabled. For that metadata capture, +the options filter receives the original URL, `array()` attributes, and a +`null` post ID; filters that depend on a post must handle this context too. + +On a Vimeo cache miss, rendering immediately falls back to a neutral poster +and schedules a background WP-Cron lookup; it does not wait for Vimeo. +Successful metadata is cached for one day. A separate one-hour retry marker +backs off failed or overlapping lookups without replacing valid cached +metadata with an empty entry. If WP-Cron is disabled or delayed, the neutral +poster still provides a working play link. These server-side metadata requests +do not expose the visitor's browser to the provider. +WordPress still performs its normal oEmbed lookup when its HTML cache is cold. + +## Poster behavior and overrides + +The poster is a complete iframe `srcdoc` document rendered through +`@templates/partials/oembed-poster.twig`. A child can add +`templates/partials/oembed-poster.twig` to replace that document. To extend the +document, copy and adapt the fallback, or refer to its parent copy through +`@emulsify-tpl/partials/oembed-poster.twig`; using the same `@templates` path +from the override would resolve back to itself. See the +[template namespace contract](template-extension.md). + +The template receives a `media_embed` map: + +| Variable | Contents | +| --- | --- | +| `player_url` | Validated player URL with `autoplay=1` and the selected privacy behavior. | +| `title` | Video title from the iframe or cached Vimeo metadata, falling back to a translated provider label; used in the document and hidden link label. | +| `provider` | `YouTube` or `Vimeo`. | +| `thumbnail_url` | HTTPS image URL, or an empty string for a neutral poster. | +| `language_code` | WordPress locale used for the poster's translated strings, formatted for the document's `lang`. | +| `language_direction` | `rtl` or `ltr` for that locale, used for the document's `dir`. | +| `play_label` | Translated `Play video` text. | + +Language and direction are computed for each render and follow WordPress locale +switching with `switch_to_locale()`. Poster overrides must keep both `lang` and +`dir` on the document's `<html>` element. + +The fallback supplies its own inline CSS inside the frame. It adds no stylesheet +to the surrounding page. Its translated play link has a visible focus ring, a +visually hidden video title, and a document language and direction. Controls +become compact in frames 160 pixels high or shorter. Keep these accessibility +details and Twig autoescaping in an override; provider titles and URLs are not +trusted HTML. +The parent preserves the rendered document exactly across supported WordPress +HTML API versions, including nested entities inside single-quoted attributes. +Keep autoescaping enabled even with that outer `srcdoc` boundary. + +If Timber is missing, an override is empty or invalid, or poster rendering +throws, the embed becomes an escaped plain link to the original video with its +title as the link text. It contains no iframe or thumbnail, so it makes no +provider request before the visitor follows it. The parent reports the failure +through WordPress's `_doing_it_wrong()` diagnostic action. With `WP_DEBUG` off, +the request continues; with `WP_DEBUG` on, WordPress also warns and the original +exception is rethrown so developers can fix the override. This behavior applies +to embed filtering in frontend, REST, and editor content rendering. The theme's +separate missing-Timber frontend error page still applies; this safeguard keeps +admin and REST requests from failing inside the embed filter too. + +The link uses `referrerpolicy="strict-origin-when-cross-origin"` so the player +receives the site's origin without its page path or query. Thumbnail images use +`referrerpolicy="no-referrer"`. The containing iframe permits autoplay, +fullscreen, picture-in-picture, and encrypted media for the recognized player +origins, including after the poster navigates the frame. Other provider +permissions without an explicit origin list receive the same origins; +directives with an explicit list keep it. Activation adds an iframe navigation +to browser history; the first Back returns to the poster. + +## Content Security Policy + +A `srcdoc` document inherits the embedding page's Content Security Policy, as +described by the [CSP inheritance rules](https://www.w3.org/TR/CSP/). +Deployments must account for both the poster and the player: + +- Allow the selected YouTube player host in `frame-src`: + `https://www.youtube-nocookie.com` with privacy mode, or + `https://www.youtube.com` without it. Allow `https://player.vimeo.com` for + Vimeo. Existing accepted `https://youtube.com` embeds also need that origin + when privacy mode is off. The initial blank/`srcdoc` poster does not require + adding `'self'` to `frame-src`. +- Provider posters need their thumbnail hosts in `img-src`, typically + `https://i.ytimg.com` for YouTube and the host of Vimeo's cached + `thumbnail_url`. Neutral posters need no thumbnail host. +- The fallback's inline `<style>` must be allowed by the inherited `style-src` + policy. A site can allow the exact CSS hash, or override the poster template + to use a matching site nonce or an allowed stylesheet. A restrictive policy + does not automatically exempt styles just because they are inside `srcdoc`. + +The fallback includes a `<meta http-equiv="Content-Security-Policy" +content="script-src 'none'">` before its content. The poster needs no scripts; +this extra policy blocks scripts and inline event handlers in that document. +Keep it near the start of `<head>` in child overrides. It adds to the inherited +policy and applies only to the poster document; navigating to the provider +loads a new document and does not carry this meta policy into the player. + +Browser verification used `style-src 'self' 'unsafe-inline'` to authorize the +fallback's inline CSS. Projects can instead use its exact CSS hash or a template +override with their existing nonce; `'unsafe-inline'` is not required by the +feature. + +Test the deployed policy before enabling click to load. The parent leaves +iframes with an existing `sandbox` or `srcdoc` unchanged, so those embeds keep +the other integration's behavior instead of receiving this poster. + +## Verification + +With browser network tools open, check a YouTube and a Vimeo embed, including an +unlisted Vimeo video. Before activation, expect no player request; with neutral +posters, expect no provider image request either. Tab to **Play video**, activate +it with Enter, check playback and fullscreen, then use Back to return to the +poster. Confirm the hidden title distinguishes the two links for a screen +reader, and check the controls in 200 × 113 and 320 × 180 frames. Browser or +provider policies can still require another click inside the player. diff --git a/docs/parent-child-architecture.md b/docs/parent-child-architecture.md index 6ba8355..3fcfa28 100644 --- a/docs/parent-child-architecture.md +++ b/docs/parent-child-architecture.md @@ -37,7 +37,10 @@ The bundled Whisk starter is an example child theme. Real projects can generate ## Template fallback model -The parent `templates/` directory contains complete minimal fallbacks. The generated child theme only ships a small example override at `whisk/templates/page.twig`. +The parent `templates/` directory contains complete minimal fallbacks. Generated +child themes ship no Twig templates or `templates/` directory. Pages render +through the parent's `page.php` and Twig fallback until the project creates an +intentional override. See the [public Twig extension points](template-extension.md). Timber resolves the `@templates` namespace child-first: @@ -52,6 +55,10 @@ Built child theme components are discovered before built parent theme components Discovery is memoized for the current PHP request. ACF/Twig and native block registration share one filesystem scan by default. +Recursive discovery skips unreadable or disappearing directories so one broken +component folder cannot interrupt the request. With `WP_DEBUG` enabled, the +runtime reports skipped unreadable roots and traversal failures for diagnosis. + ## Asset resolution priority Built assets are resolved child-first. When `dist/emulsify-assets.json` exists and is valid, the manifest is used before recursive scanner fallback for each asset scope. If a child manifest is valid, it takes priority over the parent manifest; if a scope is missing or invalid, that scope falls back to scanning built child and parent directories. @@ -66,9 +73,33 @@ Persistent component discovery caching is enabled by default in production and s add_filter( 'emulsify_theme_component_discovery_cache_enabled', '__return_false' ); ``` -The transient cache key includes the active stylesheet, parent template, child theme version, parent theme version, WordPress environment type, and `dist/emulsify-assets.json` filemtime when that manifest exists. The runtime also calls `clear_discovery_cache` on WordPress' `switch_theme` hook so changing themes invalidates the active cache key. - -Projects that customize component roots dynamically can add their own invalidation token with `emulsify_theme_component_discovery_cache_key_parts`. The default cache lifetime can be adjusted with `emulsify_theme_component_discovery_cache_ttl`. +The transient cache key includes the active stylesheet, parent template, both +theme versions and directories, the WordPress environment type, the effective +component roots and their filesystem state, and `dist/emulsify-assets.json` +filemtime when that manifest exists. Directory identity and timestamps invalidate +the index after a release-directory deploy or a standard Emulsify Core build, +which empties the output tree before writing it. The runtime also calls +`clear_discovery_cache` on WordPress' `switch_theme` hook. + +Only JSON metadata is indexed; ACF/Twig template candidates are checked directly +when building component records. Cached file paths are relative to their +component root and resolved against the current roots. Before reusing an index, +the runtime checks that every cached file +is still readable and inside its root. If any record is stale or invalid, it +discards the index and scans again. A warm cache performs filesystem checks but +does not recursively scan the component tree. A scan that skips an unreadable or +disappearing directory is not persisted, so the next request can discover the +recovered branch. + +Projects that customize component roots dynamically can add their own +invalidation token with +`emulsify_theme_component_discovery_cache_key_parts`. Preserve the existing key +parts when adding a token. Custom builds that update nested directories in place +must change a build token or clear the discovery cache: a nested addition need +not change the component root's timestamp. This also applies when forcing +persistent caching on during Core's watch builds, which preserve the output tree +after their first cycle. The default cache lifetime can be adjusted with +`emulsify_theme_component_discovery_cache_ttl`. To clear the current cache key from project code, a maintenance command, or custom deployment logic, call: diff --git a/docs/post-2x-optimization-roadmap.md b/docs/post-2x-optimization-roadmap.md index ed719b3..32394e4 100644 --- a/docs/post-2x-optimization-roadmap.md +++ b/docs/post-2x-optimization-roadmap.md @@ -20,6 +20,12 @@ Emulsify WordPress 2.0 should stay focused on the parent and generated child the - `switch_theme` cache invalidation and cache-key parts for theme versions, environment, and manifest mtime. - Safer WP-CLI `--force` replacement checks using generated child theme metadata. +The 2.1 hardening adds theme and component directory identity and build-state +signals to the persistent discovery key, with relative cached paths and stale +file validation. Custom builds that change nested output in place still need a +build token or explicit cache clear; see the +[cache invalidation guidance](parent-child-architecture.md#optional-persistent-discovery-cache). + ## Recommended implementation order 1. Keep the 2.0 release branch focused on release readiness only. diff --git a/docs/release-notes-next.md b/docs/release-notes-next.md index 4eee136..0d3dd1e 100644 --- a/docs/release-notes-next.md +++ b/docs/release-notes-next.md @@ -1,80 +1,259 @@ -# 2.0.0 Release Notes Draft +# 2.1.0 Release Notes Draft -Status date: 2026-08-02 +Status date: 2026-10-29. WordPress 2.1.0 remains unreleased; the parity work and +release preparation must merge before publication. These notes describe changes +since `2.0.0`, including the sync with [Drupal 7.3.0, published on October 28](https://github.com/emulsify-ds/emulsify-drupal/releases/tag/7.3.0). +The [sync log](sister-project-parity.md#sync-log) records the published tag and +the platform-specific classifications. ## Version strategy -Latest published tag: none on the stable line. The `release-2.x` branch prepares -the first stable release as `2.0.0`. +Latest published tag: `2.0.0`. This draft tracks the upcoming `2.1.0` release. -Until the `2.0.0` tag exists, `release.config.js` forces the first `main` publish -to a major release type and verifies the computed version is exactly `2.0.0`. -After that tag exists, normal Conventional Commit analysis drives later releases -and this file should be rewritten for the next version. +The release PR prepares `2.1.0` in root `package.json` together with every +derived version surface. The version contract accepts the +latest stable tag or an untagged next patch, minor, or major, and requires full +Git history and tags. It rejects already-tagged draft versions and stale claims +about the latest release. -## Compatibility notes +Publishing skips successfully when no version is prepared after CI verifies +that the latest tag has a published GitHub release and its ZIP. Once `2.1.0` is +prepared, semantic-release must compute exactly `2.1.0` from Conventional +Commits before publishing the committed theme headers, ZIP, and generated-theme +lineage. See the [release process](release-process.md). -- WordPress 6.7 or newer; PHP 8.3 or newer. -- Timber `^2.3` is required by the parent theme. -- Generated child themes use Emulsify Core `^4.3.2` and the Vite build workflow. -- Generated child themes keep `Template: emulsify`; `whisk` remains a - generation-only starter source and must not be activated directly. -- Root release tooling requires Node.js `>=24.10`; generated child theme tooling - requires Node.js `>=24`. +## Added -## Draft GitHub release notes +- Optional privacy mode and JavaScript-free click-to-load posters for YouTube + and Vimeo oEmbeds. Both default to off. The + `emulsify_theme_media_embed_options` filter controls privacy, activation, and + provider or neutral posters; children can override the accessible `srcdoc` + document. Posters declare the document's language and direction. See + [media embeds](media-embeds.md) for CSP and privacy requirements. +- Public `site_header`, `main`, and `page_title` Twig blocks let children extend + the parent layout without copying it. Existing block names, boundaries, and + default output are preserved and tested. See + [template extension](template-extension.md). +- Generated themes include portable `AGENTS.md` guidance, a WordPress + integration guide, and an optional integration skill. Both generators retain + identical guidance, including the hidden `.agents/` directory. The root + contributor guide documents maintainer ownership and validation. +- Rendered WordPress accessibility checks cover seven fixture routes, including + paginated content and video posters. They retain HTML and axe reports, check + current menu/pager items, and use five WCAG tags through WCAG 2.2 AA. Only + `target-size` is disabled because projects style the fallbacks; see + [accessibility](accessibility.md). +- A shared fixture characterizes PHP Twig helpers against installed Emulsify + Core JavaScript helpers, recording known differences explicitly. Run + `npm run test:twig-helpers`; see + [Twig authoring](timber-and-twig-authoring.md). -Title: `2.0.0` +## Changed -### Added +- Release publishing waits for the full reusable readiness workflow and reuses + its tested ZIP with a SHA-256 checksum. Readiness audits the shipped Composer + dependencies and logs Whisk dependency findings. Release credentials remain + scoped to the commands that need them; all concrete release jobs have time + limits. The root npm package is private, and Husky 9 installs a real commit + message hook in clones and worktrees. +- Root development-only release tooling adopts Drupal 7.3.0's refreshed + semantic-release, GitHub plugin, commitlint, and lint-staged baselines. + WordPress retains its prepared, committed release-version model. +- New generated themes use Emulsify Core `^4.5.0`, with an effective Node.js + minimum of 24.13.0. Existing child manifests and lockfiles remain + project-owned. +- New generated themes ship no Twig overrides or `templates/` directory. Pages + use parent fallbacks; projects create overrides only when needed. +- Project tests execute native ESM, collect project coverage including untested + source, and fail when no tests exist. Lint, lint-fix, and format run all steps + while preserving any failure. The accessibility wrapper uses Core's bounded + runner, preserves the empty-audit failure, honors `pa11y.wait`, and keeps + Chrome's sandbox enabled. +- CI pins all actions to commit SHAs, updates them through Dependabot, and + protects the blocking WordPress/PHP matrix with a contract check. Compatible + release-tooling lockfile updates address independently resolved dependency + findings; remaining development findings and upstream owners are recorded in + the [October 23 audit](dependency-audit-2026-10-23.md). -- Timber-first WordPress parent theme with Twig route fallbacks, global context, - namespace registration, and Emulsify-compatible switch tags. -- `wp emulsify` WP-CLI child theme generation with `--machine-name`, - `--description`, `--parent`, `--dry-run`, `--force`, and `--activate`. -- Standalone starter generation through +## Fixed + +- Contributor updates no longer commit directly to `main`. The release runner + detects `main` moving during readiness and gives recovery steps for a new + `workflow_dispatch` on `main`. + +- Global context reuses its body-class calculation and creates logout URLs + only when read or JSON-serialized. Both body-class keys and `wp.logout_url` + remain available; PHP context caches can serialize the lazy URL. + +- Component templates follow Twig's strict modification-time freshness check, + including files changed within the compiled template's timestamp. + +- `get_footer` runs before footer markup and `wp_footer`, matching WordPress + while preserving both hooks when a child replaces the footer block. + +- WP-CLI skips symlinked starter directories with a warning, instead of + silently creating empty destination directories. + +- Component-scoped CSS and JavaScript in subfolders, including editor-only + files, no longer load globally when no asset manifest is present. + +- Installable ZIPs contain only committed inputs from one Git revision and + refuse symlinks instead of packaging their targets. + +- Both child-theme generators preserve JSON object/list types, rewrite nested + patterns, apply matching sanitization to accepted plain-text metadata, and + stop on invalid JSON without installing a partially processed starter. + Standalone generation rejects noncanonical machine names and display names + or descriptions containing `<` before changing files. + +- Native robots, favicon, feed, trackback and sitemap responses remain + available when Timber is missing, while theme pages retain a clear error. + +- PHP attribute helpers reject script-bearing URLs, `srcdoc`, framework event + and expression directives, and arbitrary object attribute sources. Class + names are handled case-insensitively while SVG name case is preserved. + +- Mapped group and quote blocks retain children in `inner_content` without + rendering them again. Mapped blocks reuse global context, select their own + post without resetting Query Loop globals, reject directory templates, and + fall back to WordPress markup on recursive rendering. Dynamic and late-added + template-map filters remain active. +- Optional `front-page.twig` now serves the actual front page for both static + pages and posts. A separate posts page uses `home.twig`, then `index.twig`; + protected static front pages retain password-form routing. +- Empty custom post type archives select their queried type's template, and + day archive titles use the site's configured date format. +- Release reruns report an incomplete tagged GitHub release or missing ZIP with + recovery commands, before stale release-draft documentation can mask it. +- Release test fixtures ignore maintainer commit/tag signing settings, and the + organization-project workflow skips fork and Dependabot pull requests. +- Recursive file discovery skips unreadable or disappearing directories and + reports failures when debugging, so a broken component folder no longer makes + frontend or admin requests fatal. +- Persistent component discovery invalidates after release-directory deploys + and standard builds without requiring a theme-version bump or asset manifest. + Cached paths resolve against the current roots, and stale or unreadable files + trigger a fresh scan instead of reusing a dead index. +- Click-to-load media failures produce an escaped video link without contacting + the provider before activation. Poster `srcdoc` escaping is exact on the + minimum WordPress version, with a script-blocking meta CSP. Provider + permissions survive activation, thumbnails lazy-load, and Vimeo metadata + caching runs only when provider posters need it while preserving valid data + on failed refreshes. +- Parent templates use WordPress escapers for formatted titles, site/menu and + author names, archive/search headings, and thumbnail alt text, so encoded + punctuation and ampersands display once without weakening Twig autoescaping. +- Security: password-protected pages and listing excerpts no longer expose + content without a valid post-password cookie, fixing an issue present in + `2.0.0`. Timber content reads now show the password form, and protected pages + and posts use WordPress's filtered form with the correct site URL, including + installations in a subdirectory. +- The media embed filter accepts missing post IDs and normalizes public-filter + inputs, including embeds rendered outside a post, without interrupting the + request. +- Security: experimental mapped core-block rendering keeps parsed block data in + `block_attributes` and starts HTML `attributes` as an empty array, preventing + block comment data from becoming executable HTML attributes through Twig + helpers. The PHP attribute bag also drops all case-insensitive `on*` + event-handler attribute names. +- Pagination marks only the actual current page, renders a translated ellipsis + character as non-interactive text, and preserves query arguments in numbered, + previous, and next links. Numbered links now include a translated `Page ` + prefix in a `screen-reader-text` span, with no added frontend CSS. +- Localized pagination numbers decode HTML entities before autoescaping, so + non-breaking thousands separators render correctly instead of literal ` `. +- Fallback menus mark the current item with `aria-current="page"`, leaving + ancestors unmarked. +- Project and `@components` references follow Core's direct candidates and + breadth-first grouped discovery, including `.html.twig` and unregistered + explicit prefixes, while registered namespaces retain their scope. + `structureImplementations` selects the child component root as Core does. + Component discovery, hit/miss results, and project configuration are shared + across the request's Timber loaders; CLI processes bypass those caches by + default. Ordered WordPress legacy/parent fallbacks and containment remain. +- In `2.0.0`, Timber 2.5 passed Twig only a function's `callable` and `options` + keys, so the helpers' top-level `needs_context` and `is_safe` settings were + ignored. Every `bem()` and `add_attributes()` call printed escaped attribute + markup, such as `<h2 class="heading">`, and never received context + attributes. The options are now registered correctly; `2.0.0` projects can + drop any `|raw` or other workaround they added. Argumentless `bem()` and + `add_attributes()` calls no longer consume unrelated context as arguments or + expose it as attributes. +- The document shell preserves trusted WordPress language attributes as markup, + producing a valid `lang` attribute. +- Parent `theme.json` no longer sets the failing pale-blue normal link color or + invalid hover, focus, and active color declarations. Quote text now inherits + the page's text color instead of the same failing pale blue; review project + quote presentation. The removed button color object never applied, and + quote spacing is unchanged: previously unresolved bottom quote and top cite + margins are now explicitly `0`. Other global styles and editor presets + remain; review project link presentation after updating. +- Generated audit wrappers keep JSON stdout clean by sending documentation + footers to stderr, while preserving arguments and Core's exit status. +- Release tooling accepts prepared versions after `2.0.0`, rejects stale draft + versions and release claims, and prevents publishing mismatched metadata. + `npm run release:check -- --skip-smoke` now honors its documented behavior. + +## Compatibility + +- **WordPress 6.8 or newer is required**, raised from 6.7 to match locked Timber + 2.5.1. Update WordPress before updating the theme. PHP remains 8.3 or newer; + the PHP and Timber package constraints are unchanged. +- The minimum WordPress version and current stable release are blocking CI + legs. `Tested up to` is 7.1 after a passing fixture on 7.1.3; nightly remains + advisory. Practical checks block on PHP 8.3, 8.4, and 8.5. +- Generated child tooling advertises Node.js `>=24`, while Core sets the + effective minimum at 24.13.0. Root maintainer tooling requires `>=24.10`. +- Existing children keep `Template: emulsify` and their copied files. Parent + updates do not replace their scripts, Jest config, guidance, or dependencies. + Existing parent-extending page overrides continue receiving parent fixes. + +## Consumer action + +Before updating, sites on WordPress 6.7 must upgrade WordPress to at least 6.8. +After updating, check menus, long archives, filtered searches, link colors, and +language markup. Projects own target size, `screen-reader-text`, and focus +styles; confirm the new pager prefix is visually hidden by the site's styles. + +Adopting copied tooling fixes, Core `^4.5.0`, AI guidance, or the new extension +blocks in an existing child is optional. Copy the relevant changes into the +child deliberately; refreshing the parent does not change those files. An old +page wrapper can remain, or be removed after checking project CSS. Privacy and +click-to-load embeds remain off until enabled; review CSP and playback behavior +before opting in. See the required and optional actions in +[UPGRADE.md](../UPGRADE.md#upgrading-from-200-to-210). + +## Release PR checklist + +- [ ] Merge the parity implementation PRs and review the + [sync log](sister-project-parity.md#sync-log) against the final changes. +- [x] Prepare committed `2.1.0` metadata following the + [release procedure](release-process.md): root `package.json`, both theme + `Version` headers, `whisk/package.json`, `whisk/project.emulsify.json` lineage, + and applicable lockfile metadata agree. +- [ ] Re-sync [`emulsify-wordpress-starter`](https://github.com/emulsify-ds/emulsify-wordpress-starter) - and its `.cli/init.js` hook. -- Project-specific documentation in generated child themes: `README.md`, - `docs/development.md`, `docs/upgrading.md`, and `docs/support-information.md`, - resolved from `%%EMULSIFY_*%%` tokens at generation time. -- A generated child theme contract with focused tests, plus a cross-path parity - smoke that requires both generation paths to produce the same file tree. -- ACF/Twig block registration, native `block.json` registration, block pattern - registration, editor policy controls, and editor enhancements. -- Asset discovery and enqueuing for built child theme output under `dist/`. - -### Changed - -- Root `package.json` is now the single source of truth for the release version. - Theme headers, starter metadata, generated lineage, and smoke assertions all - derive from it instead of restating a literal. -- Both generation paths emit two-space JSON so generated metadata is identical - regardless of which path a project used. -- Generation-only tooling is no longer left in generated child themes. The - WP-CLI generator excludes `.cli`, and the standalone starter hook removes - itself after a successful run. -- `docs-command-check.cjs` now exports a reusable validator and can validate a - real generated child theme directory, not just repository documentation. - -### Fixed - -- `style.css` header replacement no longer warns when a header already holds the - requested value; only a genuinely missing header is reported. - -### Internal - -- Added `npm run test:generated-theme` and `npm run smoke:generation-parity`. -- Added release checks for generated documentation sections, the documentation - token list across both generators, and the generated child theme contract. + from `whisk/`, including hidden `.agents/` guidance and the standalone + `.cli/init.js` generator; confirm both generation paths still agree. +- [x] Confirm a published `@emulsify/core` version satisfies `^4.5.0`: + [4.5.0](https://www.npmjs.com/package/@emulsify/core/v/4.5.0) was verified in + the npm registry on 2026-10-23 and requires Node.js 24.13.0 or newer. +- [ ] Confirm the version resolved by a fresh generated theme lockfile still + satisfies that range and the effective Node requirement. +- [ ] Run the readiness checks below on the prepared committed files and + confirm semantic-release computes exactly `2.1.0`. Have the maintainer review + and push the release PR, then confirm CI passes before merging. Rotate this + draft after publication. ## Validation notes -- Run `npm run release:check -- --skip-smoke` for static validation. -- Run `npm run test:generated-theme` and `npm run smoke:generation-parity` for - generation coverage. +- Run `npm run docs:check-commands` and `npm run lint:php`. +- Run `npm run pr:check`, `npm run test:generated-theme`, and + `npm run smoke:generation-parity`. - Run `npm run release:check` with WP-CLI and MySQL available for the full - WordPress fixture path. -- Run `npm run publish-test -- --no-ci` before publishing. -- Publish the compatible `@emulsify/core` release before Emulsify WordPress - `2.0.0`. + WordPress fixture path; set `WP_SMOKE_REQUIRED=1` so missing prerequisites fail. +- Run `npm run release:check -- --skip-smoke` only for static validation; it + does not replace the full release gate. +- Push the branch, then follow the + [local dry-run requirements](release-process.md#local-release-dry-runs) before + `npm run publish-test -- --no-ci` to verify the prepared version calculation. diff --git a/docs/release-process.md b/docs/release-process.md index 4c9296f..24043ca 100644 --- a/docs/release-process.md +++ b/docs/release-process.md @@ -2,11 +2,13 @@ This repository uses semantic-release with Conventional Commits. Releases are prepared from `main`, and Git tags use non-prefixed SemVer such as `2.0.0`. -## Release branch target +## Repository history -The `release-2.x` branch prepares the next stable release as `2.0.0`. Until that stable tag exists, the semantic-release config forces the first `main` publish to use a major release type and then verifies the computed release is exactly `2.0.0`. After the `2.0.0` tag exists, normal Conventional Commit analysis drives later releases. - -Semantic-release excludes prerelease tags when it determines the previous release on a stable branch. The repository publish scripts therefore use a guarded runner that temporarily aliases the latest merged `1.0.0` alpha tag as a local `1.0.0` baseline. The release guard removes that temporary tag before semantic-release can push tags, so only the computed `2.0.0` tag is published. The runner verifies the tag target and also removes the alias on failure. +Release checks require full Git history and tags. Use a full clone, run +`git fetch origin --tags` before preparing a release, and use +`git fetch --unshallow --tags origin` first if the checkout is shallow. CI jobs +that run release checks use `fetch-depth: 0`. The version contract fails clearly +if no stable tag is available; it does not invent a release baseline. ## Commit messages @@ -39,8 +41,89 @@ other version surface is compared against it rather than restating a literal: `release:check` fails when any of these disagree, so a missed bump cannot ship inconsistent generated-theme lineage metadata. -Before publishing a release, update root `package.json`, then run -`npm run release:check -- --skip-smoke` and fix any surface it reports. +The root version must be stable `x.y.z`: either the latest stable tag, or an +untagged next patch, minor, or major of it. For example, after `2.0.0`, the +prepared version may be `2.0.1`, `2.1.0`, or `3.0.0`. Skipped versions, older +tagged versions, and prereleases are rejected. Release-note draft headings must +name an untagged version, and claims about the latest or current release must +match the latest stable tag. + +## Release PR procedure + +1. Start a release PR from an up-to-date `origin/main` with full history and + tags. Review the Conventional Commits since the latest stable tag to choose + the upcoming version. +2. Bump root `package.json` to that prepared version. Update `style.css` + `Version`, `whisk/package.json` version, `whisk/style.css` `Version`, and + `whisk/project.emulsify.json` `project.generatedFromVersion` to match. Keep + lockfile package metadata aligned when applicable. No release plugin writes + these versions for you. +3. Update `docs/release-notes-next.md` and `UPGRADE.md`, then run the local + readiness checks below, leaving `publish-test` for step 4. Include the full + `npm run release:check` with WP-CLI and + MySQL available. The release job packages these committed files, including + their version strings, into the ZIP. +4. Push the release PR branch, then follow the + [local dry-run requirements](#local-release-dry-runs) and run + `npm run publish-test -- --no-ci`. Publishing remains restricted to `main`. + Semantic-release must compute exactly + the prepared version from the Conventional Commits. A mismatch fails with + an actionable message; resolve the version or commit classification before + merging. +5. Merge the release PR to `main` after readiness checks pass. The publishing + workflow repeats the checks and publishes only when its computed version + matches the prepared version. +6. After publishing, rotate `docs/release-notes-next.md` to an untagged draft + heading and release title, and update or remove its latest-tag claim. The + contract rejects the shipped draft on subsequent runs until it is rotated. + +Keep `main` at the merge commit until the release finishes. Do not merge or +push other changes while release readiness and publishing are running. +Contributor updates are maintained by hand in reviewed pull requests; the +contributors bot workflow has been removed so it cannot advance `main`. + +For a prepared release in CI, the runner compares its checkout with the live +`origin/main` before invoking semantic-release, including during its dry run. +If `main` moved, start a new **WordPress Release** workflow +(`semantic-release.yml`) run with `workflow_dispatch`, selecting **main**. +This runs readiness and publishing against the new tip. Do not use **Re-run +jobs** on the old run: it retains the old commit. The preflight detects drift +but cannot prevent a later push, so keep `main` unchanged for the new run too. +Local dry runs on release branches and valid unprepared-release skips are +unaffected. + +When `package.json` still equals the latest stable tag, no release is prepared. +In CI, the guarded runner first verifies that the tag has a published stable +GitHub release with a nonempty, uploaded `emulsify.zip`. It then skips publishing +successfully, even if newer commits would otherwise trigger semantic-release. +Local unprepared-release skips need no GitHub token. Ordinary change PRs do not +need to bump versions; the release PR prepares them together. + +## Recovering a partial release + +Semantic-release pushes the tag before uploading and publishing the GitHub +release. The release workflow checks publication state with read-only access +before readiness, so stale draft documentation cannot hide a missing release or +ZIP. A failure prints the relevant `gh release upload` or `gh release edit` +commands. A read-only token may also see a draft as missing; inspect it with a +maintainer account before creating anything. + +Use the ZIP and checksum from the successful readiness run for that exact tag. +Verify the checksum before uploading. If that artifact has expired, check out +the tag in a full clone and rebuild it with `npm run build:dist`. With WP-CLI, +MySQL, Chrome and the `WP_SMOKE_DB_*` settings configured, validate that ZIP: + +```sh +WP_SMOKE_REQUIRED=1 WP_SMOKE_A11Y=1 WP_SMOKE_THEME_ARCHIVE=dist-artifact/emulsify.zip node .github/scripts/wordpress-fixture-smoke.cjs +``` + +Use the standalone fixture for this already-tagged recovery: the unreleased-draft +contract intentionally rejects the historical draft notes at the tag. Do not +edit the tag's sources, rebuild from a newer branch tip, move the tag, or prepare +another version to hide a partial release. +Review release notes before publishing a recovered draft. After recovery, +rotate the release draft as described above and start a new workflow dispatch +on `main`; the publication check should pass and publishing should skip. ## Release checks @@ -76,7 +159,8 @@ npm run lint:php npm run test:generated-theme npm run smoke:generation-parity npm run pr:check -npm run release:check +npm run build:dist +WP_SMOKE_REQUIRED=1 WP_SMOKE_THEME_ARCHIVE=dist-artifact/emulsify.zip npm run release:check npm run publish-test -- --no-ci ``` @@ -105,15 +189,58 @@ commands still exist in the package where readers are instructed to run them. `release:check` adds static release-readiness checks and the full WordPress fixture smoke path. In CI, the fixture extracts the built `emulsify.zip` into an isolated WordPress site, confirms the packaged `wp emulsify` command, generates and activates a child theme from the packaged Whisk source, adds neutral built asset and block fixtures, renders frontend routes through Timber, fetches those built child assets, and checks ACF/Twig and native `block.json` discovery. It requires WP-CLI and MySQL. It skips gracefully when WP-CLI or database settings are unavailable unless `WP_SMOKE_REQUIRED=1` is set. +Use `npm run release:check -- --skip-smoke` for static checks and focused +contract tests without runtime smoke commands. This is a quick local check; +the release PR and publishing workflow still require the full fixture path. + +## Local release dry runs + +Before `npm run publish-test -- --no-ci`: + +- Use an attached local branch with full history and tags. Detached `HEAD` + checkouts cannot supply the release branch. +- Push that branch to `origin` first, fetch it, and make sure the checkout is + not behind its remote branch. Push new commits before repeating the dry run. +- Set `GH_TOKEN` or `GITHUB_TOKEN` to a GitHub token with push permission for + this repository. The GitHub plugin verifies that permission even in dry runs; + an authenticated Git CLI alone does not supply the environment variable. +- Build `dist-artifact/emulsify.zip` with `npm run build:dist` and test that exact + archive with `WP_SMOKE_THEME_ARCHIVE=dist-artifact/emulsify.zip`. Configure the + disposable database with the `WP_SMOKE_DB_*` variables used in + `.github/workflows/theme-readiness.yml`. + +The dry run analyzes the current pushed release branch and must compute the +prepared version exactly. It creates no tags or releases. Use the guarded +`publish-test` command; the root npm package is private and exposes no raw +`semantic-release` script. A missing or empty ZIP fails release verification +before any tag is created, including during dry runs. + ## Installable release artifact -Run `npm run build:dist` to create `dist-artifact/emulsify.zip`. The build stages an explicit parent-theme runtime file list under a top-level `emulsify/` directory, copies only tracked Whisk generator files, and installs the versions pinned in `composer.lock` with `--no-dev --optimize-autoloader` directly into that staged tree. The ZIP therefore bundles `vendor/` and can be installed without running Composer after download. +Run `npm run build:dist` to create `dist-artifact/emulsify.zip`. Commit source +changes before building: the build reads one immutable `HEAD` commit, including +Composer metadata and Whisk payload, and excludes staged or working-tree edits. +It refuses committed symlinks before installing dependencies. Git objects are +read explicitly so `export-ignore` cannot omit the lockfile needed for the build. + +The build stages an explicit parent-theme runtime file list under a top-level +`emulsify/` directory and installs the committed versions pinned in +`composer.lock` with `--no-dev --optimize-autoloader` directly into that tree. +The ZIP bundles `vendor/` and can be installed without running Composer after +download. The archive includes the runtime PHP entry points, `includes/`, `templates/`, `src/`, `style.css`, `theme.json`, the screenshot, license, README, linked user documentation, production Composer dependencies, and the tracked `whisk/` child starter required by `wp emulsify`. It excludes repository metadata, `.github/`, root npm and Composer metadata, `node_modules/`, development configuration, smoke tests, and Whisk's standalone `.cli` hook, caches, dependencies, and build output. Composer/GitHub distributions are a separate channel. They retain `composer.json` so the consuming application can resolve dependencies, and `.gitattributes` removes repository-only CI, release scripts, and root npm tooling while retaining user documentation. A direct Git clone remains a full development checkout. For a manual WordPress upload, always use the named `emulsify.zip` release asset rather than GitHub's automatic **Source code** archive. -The semantic-release publish job sets up PHP 8.3 and Composer, builds this archive, and lets `@semantic-release/github` attach it to the GitHub release as **Emulsify WordPress theme (with dependencies)**. WordPress.org SVN deployment remains a future step after the project has a WordPress.org profile; it is not performed by this workflow. +Read-only readiness builds the archive once in its PHP 8.3 practical lane. +WordPress fixture jobs download that archive and verify its SHA-256 checksum +before testing it. The publishing job downloads the same artifact and checks +the checksum before its dry run and publish command. It installs no PHP or +Composer and does not rebuild the ZIP. `@semantic-release/github` attaches it +as **Emulsify WordPress theme (with dependencies)**. WordPress.org SVN +deployment remains a future step after the project has a WordPress.org profile; +it is not performed by this workflow. For pre-release client testing, the PHP 8.3 `Practical theme readiness` lane also builds the archive and uploads `emulsify.zip` directly for 14 days. This provides the packaged theme before a public GitHub Release exists without publishing an untagged stable release or wrapping the installable ZIP inside another archive. @@ -123,30 +250,76 @@ The WordPress Theme Readiness workflow runs on pull requests, manual dispatch, a Every configured pull request runs two independently visible fast jobs: -- `Practical theme readiness`: clean root npm installation, Composer validation, npm audits, the practical `pr:check` suite, and static `release:check` assertions. +- `Practical theme readiness`: clean root npm installation, Composer validation, + blocking `composer audit --locked --no-dev` for the dependencies bundled in + the ZIP, root npm audits, the practical `pr:check` suite, and static + `release:check` assertions. The root runtime npm audit alone covers no shipped + packages because the root package contains only development dependencies. - `PHP coding standards and static analysis`: PHP 8.3, Composer development dependencies, PHPCS, and PHPStan through `npm run lint:php`. +The practical matrix blocks on PHP 8.3, 8.4, and 8.5. PHP 8.5 was promoted +after the locked Composer install, PHP analysis, and practical suite passed on +8.5.11. No platform-requirement bypass is used for these blocking jobs. + Pull requests targeting `main` or `release-2.x` additionally run the two extended jobs: - `WordPress fixture smoke`: the built installable ZIP, MySQL, WP-CLI, Timber, packaged generator/Whisk coverage, generated-child activation, block discovery, assets, and home/page/single/archive/search/author/404 rendering with `WP_SMOKE_REQUIRED=1`. - `Extended Whisk Storybook and a11y`: an explicit Chrome setup, a CI-only component seed, the Core 4 Vite and Storybook builds, and an axe audit of the discovered story. +The WordPress matrix blocks on the declared minimum (6.8) and `latest`. +WP-CLI resolves `latest` at run time and the fixture logs the actual downloaded +version. Nightly is advisory coverage for the next release. On October 23, +2026, the packaged fixture and all seven rendered accessibility audits passed +on WordPress 7.1.3; `Tested up to` therefore names 7.1. Raise that header only +after a green fixture run for the newer stable line. The +`readiness-matrix-contract.cjs` check and its negative tests run in `pr:check` +and `release:check`, preventing required legs from becoming advisory or +silently bypassing fixture checks. + +Every action is pinned to a full commit SHA with a release-version comment; +weekly GitHub Actions Dependabot updates maintain those pins. Validation jobs +use read-only credentials and disable persisted checkout credentials. Only +the publishing job receives release writes. Its checkout also disables +persisted credentials, npm lifecycle scripts stay disabled, and the token is +provided only to the release commands. Its dry run runs immediately +before publishing because semantic-release verifies push permission even in +dry-run mode. Contributor updates use reviewed pull requests rather than a +bot with repository-content write permission. Adding issues to the organization +project still requires the configured Projects token. See the +[dated dependency audit](dependency-audit-2026-10-23.md) for remaining +development-tool findings and their owners. + +The Whisk job creates an ephemeral lock during its dependency install and logs +`npm audit` findings without blocking readiness. This covers the installed +dependency tree; `whisk:install` intentionally does not commit a starter lockfile. +Every concrete release job has an explicit timeout. The reusable-workflow call +uses the limits on its called jobs, since GitHub does not accept a timeout on a +job that only calls another workflow. + Weekly scheduled runs repeat both extended jobs. Manual dispatch runs the WordPress fixture when `wordpress_fixture` is enabled and the Whisk build/audit when `extended_checks` is enabled. The workflow concurrency group cancels superseded pull-request runs, and both extended jobs have explicit runtime limits. -## 2.0 merge and release gate +## Merge and release gate -The two fast pull-request jobs run automatically for every configured target branch. All four jobs run for changes targeting `main` or `release-2.x`. For an additional final rerun before merging the 2.0 release branch: +The two fast pull-request jobs run automatically for every configured target branch. All four jobs run for changes targeting `main` or `release-2.x`. For an additional final rerun before merging a release PR: 1. Open GitHub Actions for `emulsify-ds/emulsify-wordpress`. 2. Select the `WordPress Theme Readiness` workflow. 3. Choose `Run workflow`. -4. Select the `release-2.x` branch. +4. Select the release PR branch. 5. Keep `wordpress_fixture` enabled. It defaults to enabled for manual runs. 6. Enable `extended_checks` to rerun the CI-seeded Storybook and accessibility audit. -Success means `Practical theme readiness`, `PHP coding standards and static analysis`, `WordPress fixture smoke`, and `Extended Whisk Storybook and a11y` pass. The fixture job installs WP-CLI, starts MySQL, sets `WP_SMOKE_REQUIRED=1`, and runs `npm run release:check` against the isolated WordPress fixture. Record the successful workflow run in the 2.0 release PR before merging. - -The semantic-release workflow remains release-gated. It runs release readiness, requires the full WordPress fixture smoke path with WP-CLI and MySQL, runs a semantic-release dry run, and then allows the final publish job only after the readiness job succeeds. Release publishing must not proceed when the full fixture path is skipped or failed. +Success means `Practical theme readiness`, `PHP coding standards and static analysis`, `WordPress fixture smoke`, and `Extended Whisk Storybook and a11y` pass. The fixture job installs WP-CLI, starts MySQL, sets `WP_SMOKE_REQUIRED=1`, and runs `npm run release:check` against the isolated WordPress fixture. Record the successful workflow run in the release PR before merging. + +The semantic-release workflow calls the full WordPress Theme Readiness workflow +with release coverage enabled. It waits for PHP 8.3, 8.4 and 8.5 practical checks, +PHP analysis, required generation parity, `pr:check`, minimum/latest WordPress +fixtures with rendered accessibility, and the Whisk tests/Storybook/accessibility +job. Nightly WordPress runs too and retains its advisory policy. Release dispatch +always enables this coverage regardless of the ordinary manual-input defaults. +After readiness succeeds, the publishing job verifies the tested artifact and +runs a semantic-release dry run before publishing. Parsed YAML contracts and +negative tests reject skipped smoke paths, failure bypasses and weakened needs. ## License diff --git a/docs/sister-project-parity.md b/docs/sister-project-parity.md index 846dfd0..ed47d13 100644 --- a/docs/sister-project-parity.md +++ b/docs/sister-project-parity.md @@ -81,6 +81,90 @@ Emulsify CLI uses the standalone `https://github.com/emulsify-ds/emulsify-wordpr This file may also hold Emulsify Core metadata such as `variant.structureImplementations`. `theme.json` remains the WordPress site and editor configuration surface, not a component-library or Twig namespace registry. +## Sync log + +| Sister reference | WordPress target | Status | +| --- | --- | --- | +| Drupal [7.3.0 tag](https://github.com/emulsify-ds/emulsify-drupal/tree/7.3.0), [published release](https://github.com/emulsify-ds/emulsify-drupal/releases/tag/7.3.0) on 2026-10-28, pinned at [`1f0f679`](https://github.com/emulsify-ds/emulsify-drupal/commit/1f0f679f4c1acd510d68391e952b3f29a1817a69) | WordPress 2.1.0 | Implemented in [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); pending merge and release. | + +The published Drupal tag merges [PR #382](https://github.com/emulsify-ds/emulsify-drupal/pull/382) +at [`adc588c`](https://github.com/emulsify-ds/emulsify-drupal/commit/adc588c54cbde80a32324c845f702f7d7467cdc8). +This sync includes the 7.2.2 fixes and classifies all nine commits after the +previous [`1bc8fb3`](https://github.com/emulsify-ds/emulsify-drupal/commit/1bc8fb3bb64ae7014f50349930216b863976a5b2) +review pin. The WordPress work is collected in one release branch by maintainer decision. +[PR #42](https://github.com/emulsify-ds/emulsify-wordpress/pull/42)'s audit-wrapper +change is incorporated into PR #47; its separate PR is still open. These are +implementation references; WordPress 2.1.0 still awaits merge and release. + +### Ported or adapted + +| Area | Classification and reason | Implementation | +| --- | --- | --- | +| Release-version contracts and stale release claims | Adapt: WordPress publishes prepared, committed version metadata, and semantic-release must calculate the same version. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [release procedure](release-process.md). | +| Root development-tool refresh ([`97eff27`](https://github.com/emulsify-ds/emulsify-drupal/commit/97eff270177f90726527cec674cd58de45f89d81)) | Adapt: refresh semantic-release, its GitHub plugin, commitlint, and lint-staged without changing theme runtime dependencies or WordPress's prepared-version model. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [October 28 dependency audit](dependency-audit-2026-10-23.md#october-28-release-tooling-refresh). | +| Core 4.5, lint/format exit status, ESM tests and coverage, audit JSON, and sandboxed accessibility runner | Port/adapt: shared frontend tooling retains WordPress's failures for empty test suites and empty accessibility audits. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47), including [audit-wrapper PR #42](https://github.com/emulsify-ds/emulsify-wordpress/pull/42). | +| Pager/menu current items, hidden Page prefix, and rendered accessibility audit | Adapt: Timber fallbacks and seven WordPress fixture routes replace Drupal render templates and routes. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [accessibility contract](accessibility.md). | +| Public Twig extension blocks and removal of the starter page override | Adapt: additive parent blocks preserve WordPress template inheritance and existing child overrides. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [template extension contract](template-extension.md). | +| Generated AI guidance and root contributor guidance | Adapt: library-neutral instructions describe Timber, WordPress hooks, blocks, and verification. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [generated-theme contract](generated-child-theme-contract.md). | +| PHP/JavaScript Twig helper characterization | Port/adapt: a shared corpus records intentional helper differences and catches runtime bugs without silently changing contracts. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [Twig authoring](timber-and-twig-authoring.md). | +| Action pins, blocking readiness matrix, dependency maintenance, and README assets | Port/adapt: shared validation policy uses WordPress versions and the supported PHP matrix. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [dependency audit](dependency-audit-2026-10-23.md). | +| Privacy video embeds | Adapt, implemented for 2.1.0: render-time oEmbed filters, overridable iframe `srcdoc`, and cached background Vimeo metadata replace Drupal's same-origin embed document. Both options default to off. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [media embeds](media-embeds.md). | +| Poster language and direction ([`dac2e49`](https://github.com/emulsify-ds/emulsify-drupal/commit/dac2e49), [`a2bcdc1`](https://github.com/emulsify-ds/emulsify-drupal/commit/a2bcdc1)) | Adapt: poster `lang` and `dir` follow the WordPress locale used for translated strings, with a non-default Arabic RTL regression and default-locale restoration. | [PR #47](https://github.com/emulsify-ds/emulsify-wordpress/pull/47); [poster override contract](media-embeds.md#poster-behavior-and-overrides). | + +The narrower settings help text in +[`dac2e49`](https://github.com/emulsify-ds/emulsify-drupal/commit/dac2e49) +needs no WordPress change: there is no media settings screen, and the +[media guide](media-embeds.md) already limits these options to YouTube and Vimeo. + +WordPress companion fixes in the same PR align grouped component discovery with +Core, raise the minimum WordPress version to 6.8 to match locked Timber, and +correct fallback language markup and failing link-color declarations. See the +[2.1.0 notes](release-notes-next.md) and [upgrade actions](../UPGRADE.md#upgrading-from-200-to-210). + +### Intentional differences + +| Sister feature | WordPress decision and reason | +| --- | --- | +| 24 px target-size rule and Drupal's parent asset build | Skip: the parent ships no stylesheet; its retained `theme.json` global styles are listed below, and projects own target size, `screen-reader-text`, and focus styles. Admin-only CSS is allowed. | +| Regions: `status`, `breadcrumb`, `highlighted`, `sidebar_first`, `sidebar_second` | Skip: WordPress uses menus, block patterns, and template parts; the parent registers no widget areas. Maintainers may revisit this choice. | +| Container and form template suggestions, inline form-error IDs, status-message/feed/progress template moves, and select option attributes | Skip: these belong to Drupal's render and Form APIs. | +| Favicon dark-mode icons, SVG sanitization, and generated social share image | Skip: WordPress uses core Site Icon and `custom-logo`; SEO plugins own `og:image`. | +| Social-share settings, previews, resizing, fallback metadata, and related favicon previews ([`b312b4c`](https://github.com/emulsify-ds/emulsify-drupal/commit/b312b4c5fe964d533b245fb2fbef6def6ea419f4), [`66ac7ab`](https://github.com/emulsify-ds/emulsify-drupal/commit/66ac7abf8baa9658b019bbaf177a33addd117fc5), [`1b0a439`](https://github.com/emulsify-ds/emulsify-drupal/commit/1b0a439c1c2fb0fced3be431e2096e3d6d799dcf), [`96695b9`](https://github.com/emulsify-ds/emulsify-drupal/commit/96695b988980d101fb3955dc3b26c41ab05172a6), [`bf6cc80`](https://github.com/emulsify-ds/emulsify-drupal/commit/bf6cc800e05b0c55490658073543e29099d2e186), [`dec4732`](https://github.com/emulsify-ds/emulsify-drupal/commit/dec47321958d094adc0dc0c6991c0c002f6b4ea4)) | Skip: SEO plugins own WordPress `og:image` and sharing metadata; core Site Icon owns the favicon behavior. The parent adds neither settings system. | +| Favicon colors and clean-state notice ([`145c676`](https://github.com/emulsify-ds/emulsify-drupal/commit/145c67617be67336fbb8dd24eb4758bc69aed2d9)) | Skip: WordPress uses Site Icon, not Drupal's favicon settings and preview UI. | +| Configured admin theme in the upgrade smoke ([`adc588c`](https://github.com/emulsify-ds/emulsify-drupal/commit/adc588c54cbde80a32324c845f702f7d7467cdc8)) | Skip: this tests Drupal's admin-theme configuration and has no WordPress equivalent. | +| semantic-release-owned package version ([`97eff27`](https://github.com/emulsify-ds/emulsify-drupal/commit/97eff270177f90726527cec674cd58de45f89d81)) | Skip: Drupal uses `@semantic-release/npm` with `npmPublish: false`, then `@semantic-release/git`, to write and commit npm version metadata. By maintainer decision, WordPress keeps its prepared, committed `package.json` version and matching theme headers and starter lineage; semantic-release must compute that exact version. The commit's Drupal legacy-settings fixtures are also platform-specific. See the [release procedure](release-process.md). | +| Default parent logo, library/breakpoint contract, Drupal.org channel-skew validation, Stable 9 parity, and the `dr` CLI | Skip: these are Drupal-only runtime and distribution contracts. | +| Favicon SVG processing fixes ([`6cb1101`](https://github.com/emulsify-ds/emulsify-drupal/commit/6cb1101), [`16ecce0`](https://github.com/emulsify-ds/emulsify-drupal/commit/16ecce0), [`4a10b74`](https://github.com/emulsify-ds/emulsify-drupal/commit/4a10b74)) | Skip: WordPress uses core Site Icon. | +| Favicon preview styling in dark admin themes ([`6b8b922`](https://github.com/emulsify-ds/emulsify-drupal/commit/6b8b922)) | Skip: WordPress has no favicon generator. | +| PostCSS development dependency for parent asset tests ([`88bf3d9`](https://github.com/emulsify-ds/emulsify-drupal/commit/88bf3d9)) | Skip: the WordPress parent has no asset build. | +| Wider strict-types check, favicon dark-mode test, and hook-contract documentation edits ([`1bc8fb3`](https://github.com/emulsify-ds/emulsify-drupal/commit/1bc8fb3bb64ae7014f50349930216b863976a5b2)) | Skip: these are Drupal-only conventions. | + +Although the parent ships no stylesheet, its `theme.json` produces WordPress +global styles on the frontend: h1–h6 color and typography, visited-link color, +root padding, button border radius/width and padding, and quote/cite typography +and margins plus cite color. These remaining style rules are retained in 2.1.0 +and planned for removal in 3.0.0. Preset custom properties and `.has-*` classes +are also generated; they style nothing until content uses them. Presets and +editor configuration remain separate from that style-removal plan. + +The opt-in video poster is a separate iframe document with its own inline +accessibility styles, as approved for that feature. It adds no stylesheet to +the surrounding page; its CSP and override contract are documented in +[media embeds](media-embeds.md#poster-behavior-and-overrides). + +## How to run a sync + +- [ ] Read the sister release's notes and upgrade guide from a full clone with + history and tags; record the exact tag and PR head used as the reference. +- [ ] Classify every change as port, adapt, or skip, with a reason grounded in + the shared project model and native WordPress behavior. +- [ ] Open one PR per area, link the source changes, and keep both child-theme + generators and their contracts aligned where applicable. +- [ ] Run the relevant readiness checks, including the full WordPress fixture + for rendering or generation changes, and document consumer actions. +- [ ] Update this sync log, release notes, and upgrade guide with implementation + links, intentional differences, and the actual merge/release status. + ## Parity guardrails Use this contract when evaluating future changes: @@ -90,4 +174,12 @@ Use this contract when evaluating future changes: - Keep Whisk small enough to work as a starter. - Keep generated child theme source aligned with Emulsify Core 4 conventions. - Keep WordPress-specific behavior explicit rather than hiding it behind Drupal naming or assumptions. +- The parent ships no stylesheet, but its `theme.json` produces frontend + WordPress global styles: h1–h6 color and typography, visited-link color, + root padding, button border radius/width and padding, and quote/cite + typography and margins plus cite color. These rules are retained in 2.1.0 + and planned for removal in 3.0.0. Preset custom properties and `.has-*` + classes style nothing until content uses them. Admin-only CSS is allowed; + projects own target size, `screen-reader-text`, and focus styles. Opt-in + video posters confine their accessibility styles to the iframe document. - Keep `project.emulsify.json` on `"platform": "wordpress"` and `generatedFrom: "emulsify-wordpress"` so generated child themes advertise the WordPress platform adapter and starter lineage. diff --git a/docs/template-extension.md b/docs/template-extension.md new file mode 100644 index 0000000..e4c28d2 --- /dev/null +++ b/docs/template-extension.md @@ -0,0 +1,123 @@ +# Extend parent Twig templates + +New generated child themes ship no Twig templates or `templates/` directory. +WordPress falls back to the parent's PHP route controllers, and the parent +`@templates` namespace supplies the corresponding Twig fallback. Create a child +`templates/` directory only when the project needs an override. + +## Extend the parent explicitly + +In a child `templates/page.twig`, extend the parent-only namespace: + +```twig +{% extends '@emulsify-tpl/page.twig' %} + +{% block content %} + {{ parent() }} + <p class="project-notice">Thank you for visiting.</p> +{% endblock %} +``` + +For pages that do not require a password, WordPress selects the parent's +`page.php`, which renders `@templates/page.twig` unless the page is the static +front page and a `@templates/front-page.twig` exists. +That child-first lookup selects the child's override. Its `@emulsify-tpl` extends +then selects the parent explicitly, so surrounding layout and later parent fixes +continue to reach the child. `parent()` preserves the selected block's default +contents; omit it when intentionally replacing that block. + +Using `{% extends '@templates/page.twig' %}` inside the child file with that same +path resolves back to itself and can recurse. Use `@templates` for normal +child-first includes, and `@emulsify-tpl` for same-path parent inheritance. The +same rule applies to a child `templates/layouts/base.twig`. + +## Front page and posts page + +The parent controllers follow WordPress's front-page hierarchy: + +- Front page showing posts: `front-page.twig`, then `home.twig`, then `index.twig`. +- Static front page: `front-page.twig`, then `page.twig`. +- Separate posts page: `home.twig`, then `index.twig`. + +These optional names use the normal child-first `@templates` lookup. A missing +front-page or home template falls through to the next name. A protected static +front page uses `single-password.twig` until its password is accepted, before +trying a custom front-page template. Existing Timber render filters continue +to receive the selected file. + +Custom post type archives use `archive-{post_type}.twig` when the query names +one type, including one-element arrays and empty archives. Multiple queried +types use `archive.twig`, then `index.twig`. Day archive headings use the site's +`date_format`; month and year formatting is unchanged. + +## Public extension points + +The layout and route blocks below are a public contract. Their names and +boundaries are stable: renaming, removing, or changing a boundary incompatibly +is a breaking change. The existing `head`, `header`, `content`, and `footer` +blocks retain their original names and boundaries. + +| Parent template | Block | Default contents | +| --- | --- | --- | +| `layouts/base.twig` | `head` | The head partial, including metadata, the `get_header` action, and `wp_head()` | +| `layouts/base.twig` | `site_header` | The complete site `<header>`, its inner div, brand link, and optional primary navigation | +| `layouts/base.twig` | `header` | Brand link and optional navigation inside the site header's inner div | +| `layouts/base.twig` | `main` | The complete `<main id="content" tabindex="-1">`, including `page_title` and `content` | +| `layouts/base.twig` | `page_title` | The conditional page-title header and its h1; empty when `title` is unset or empty | +| `layouts/base.twig` | `content` | Empty; route templates provide the page-specific contents | +| `layouts/base.twig` | `footer` | The footer partial and copyright markup | +| `page.twig` | `content` | Page article with title/content, or the empty-page message | +| `single.twig` | `content` | Post article, metadata, content, and comments | +| `single-password.twig` | `content` | WordPress password form for protected posts and pages | +| `index.twig`, `archive.twig`, `author.twig`, `search.twig` | `content` | Teasers, pagination, or the route's empty-result message | +| `404.twig` | `content` | Not-found heading and message | + +Replacing `site_header` replaces its nested `header` unless the override calls +`parent()`. Replacing `main` similarly replaces its nested `page_title` and +`content`. Preserve `id="content"` and `tabindex="-1"` on your main element so +the skip link remains usable. Keep `wp_head()` when replacing the `head` block, +usually by calling `parent()`. + +The base layout keeps `wp_body_open()`, the skip link, `wp_footer()`, and the +`get_footer` action outside every overridable block. Block overrides therefore +preserve these WordPress hooks and the skip link. + +## Password-protected content + +When `post_password_required()` is true, the parent page and single controllers +render `@templates/single-password.twig`. This remains a child-first extension +point for both posts and pages. A same-path child override can extend +`@emulsify-tpl/single-password.twig` and call `parent()` in its `content` block. + +The parent fallback sets its title with `get_the_title()` and prints +`get_the_password_form( post.id )`, preserving WordPress's protected-title +format, site URL, password-cookie flow, and `the_password_form` filter. Use that +WordPress filter to customize the form; core's form uses `.post-password-form` +rather than the former custom `.password-form` markup. + +The parent enables Timber's password-form handling for `post.content` even in +child templates. Empty filtered forms stay hidden without falling through to +protected content. Excerpts and raw `post.post_content` do not have that +protection. Check `post.password_required` before rendering them, including in +overrides of `partials/tease.twig` and `partials/tease-post.twig`. A correct +post-password cookie makes that check false and restores normal rendering. + +## Verification + +Run `npm run smoke:template-extension` after `composer install`. It compares +literal output bytes with goldens captured before the added blocks, including +title/menu presence and populated/empty content. The harness uses real parent +namespaces and helpers with deterministic WordPress stubs and a frozen footer +clock. It also checks a temporary child's parent-only inheritance and verifies +that overriding one block preserves every surrounding byte. + +The full WordPress fixture verifies a generated child renders pages without a +local Twig template, then temporarily adds a one-block page override, compares +HTTP response bytes, and restores the child afterward. Run it through +`npm run release:check` with WP-CLI and MySQL available. + +### Footer hook order + +`get_footer` fires before the public `footer` block renders, matching WordPress's +classic template loading order. `wp_footer` follows the block. Both hooks stay +outside it, so replacing footer markup preserves plugin hooks. diff --git a/docs/timber-and-twig-authoring.md b/docs/timber-and-twig-authoring.md index e3149d3..563c654 100644 --- a/docs/timber-and-twig-authoring.md +++ b/docs/timber-and-twig-authoring.md @@ -13,7 +13,10 @@ composer install In Bedrock, prefer the application-level Composer project when that is where PHP dependencies are managed. Either approach works as long as WordPress loads the Composer autoloader before the theme renders. -If Timber is missing, the parent theme shows an admin notice and stops frontend rendering with a clear runtime error. +If Timber is missing, the parent theme shows an admin notice and stops theme +page rendering with a clear runtime error. Native WordPress robots, favicon, +feed, trackback, sitemap and sitemap-stylesheet responses remain available, +as do admin, AJAX and JSON requests. ## Twig namespaces @@ -25,6 +28,11 @@ The parent theme registers these namespaces: Use `@templates` for normal includes. Use `@emulsify-tpl` when a child override extends the parent template with the same relative path. +New generated themes inherit parent fallbacks without local Twig templates. +Create `templates/` when an override is needed. The [template extension +contract](template-extension.md) documents layout blocks, stable boundaries, +and the same-path inheritance recursion pitfall. + ```twig {% extends '@emulsify-tpl/page.twig' %} @@ -46,8 +54,90 @@ Install or author project components in the structure defined by the selected Em ``` The general form is `project_machine_name:component_name`. - -This reference resolves child-first compatibility roots, including `src/components/example-card/example-card.twig`, `src/components/example-card.twig`, `components/example-card/example-card.twig`, and `components/example-card.twig`. One-level grouped names such as `project_machine_name:ui/heading` resolve to paths like `src/components/ui/heading/heading.twig`. +Project references such as `project_machine_name:button` and +`@project_machine_name/button` use Core's direct-then-grouped resolution. So do +`@components/button` and `@components/button/button.twig`; the component +namespace also accepts `components:button`, `components::button`, and +`components/button`. + +Without `variant.structureImplementations`, WordPress retains these +compatibility roots in order: + +1. Child theme `src/components`. +2. Child theme `components`. +3. Parent theme `src/components`. +4. Parent theme `components`. + +With accepted structure implementations, the entry named `components` supplies +the child component root. If none has that name, the first accepted +implementation supplies it, matching Core's `components` namespace. That root +replaces both default child paths; it does not combine every implementation's +directory. Other implementation names register separate Twig namespaces. +Parent fallback roots remain available for theme inheritance. + +Core resolves one standalone project's component root. WordPress's ordered +legacy and parent fallbacks are intentional compatibility extensions; within +each root, candidate and group ordering match Core. + +Each root is searched completely before moving to the next. For a requested path `x`, direct candidates are tried in this order: + +1. `x`. +2. `x.twig`. +3. `x.html.twig`. +4. `<x without a final .twig>/<stem>.twig`. +5. `<x without a final .twig>/<stem>.html.twig`. + +Here, `stem` is the last segment after removing a final `.twig`; an explicit `.html.twig` therefore keeps `.html` in the nested stem. For example, `example-card` can resolve to `example-card.twig`, `example-card.html.twig`, `example-card/example-card.twig`, or `example-card/example-card.html.twig`. + +If no direct candidate exists, the same candidates are tried below group directories in breadth-first order. Sibling directories are sorted by UTF-16 code unit, matching Core's JavaScript ordering. Thus `project_machine_name:button` can find `src/components/atoms/button/button.twig` or a component inside deeper groups. A grouped child component takes precedence over a direct parent component. + +Duplicate names resolve deterministically: the first root wins, direct candidates precede grouped candidates, and shallower groups precede deeper groups. Use an explicit group or template path, such as `project_machine_name:atoms/button/button.twig`, to select an otherwise ambiguous component. + +Group discovery skips `node_modules`, `.git`, `.cache`, `.vite`, `.out`, `.coverage`, and `dist`. It does not follow directory symlinks discovered during the walk. Explicit file or directory symlinks can resolve when both their lexical and real paths remain inside the component root. Internal `.` and `..` segments are normalized like Core. WordPress rejects a leading `..` segment before trying groups, even if Core could find a contained candidate from a deeper group. + +Explicit unregistered prefixes also follow Core's fallback: `project:button`, +`anything:button`, and `@organisms/button` can resolve a component when no +registered Twig namespace owns the prefix. The resolver tries the literal +reference as a direct component path first, then removes the unregistered +prefix and tries direct and grouped candidates. + +Registered namespaces always keep their scope, including plugin namespaces +and a namespace that happens to match the project machine name. A missing +`@templates/button.twig`, for example, never falls back to a component named +`button`. Registered single- and double-colon aliases delegate to the same +namespace as `@namespace/path`. Only the `components` namespace uses grouped +component lookup. Custom loaders must expose their namespace inventory through +`getNamespaces()` and namespace paths through `getPaths()` for this fallback +integration; loaders without those APIs keep their own resolution unchanged. + +Other bare paths and bare `@name` references without a slash stay with the normal +WordPress/Twig loader. This differs from Core's bare component-file fallback +and preserves existing controller template lookup. Every path segment remains +intact: a missing `atoms/button` never falls back to `molecules/button`. + +Group directories, successful and missing component resolutions, and decoded +project configuration are shared across loader instances for an HTTP request. +Timber can create several loaders during one compile; each canonical root is +scanned once, and direct hits do not scan groups. Cache keys distinguish the +project machine name and ordered canonical roots. Namespace ownership is +checked before using component results, so a registered namespace cannot be +shadowed by a cached fallback. + +CLI processes, including WP-CLI and typical queue workers, bypass these caches +by default so file and configuration changes remain visible. The +`emulsify_theme_twig_request_cache_enabled` filter can change that policy. A +long-running process that enables caching must call +`\Emulsify\Theme\Runtime\Twig::clear_request_cache()` between jobs or after +changing component files or project configuration, then create fresh loaders +and Twig environments. Custom persistent HTTP workers must do the same at +request boundaries. This clears component/configuration memoization and PHP's +filesystem caches; Twig's own compiled-template cache is separate. + +Group directories are not added to the persistent discovery cache: new groups +inside existing groups can leave the root directory's modification time, theme +version, and build manifest unchanged, so a persisted index could miss their +components. The existing persistent cache continues to serve built +`dist/components` discovery. The legacy `@components/example-card/example-card.twig` namespace remains supported for compatible component libraries, existing projects, shared templates, and migration work: @@ -57,10 +147,40 @@ The legacy `@components/example-card/example-card.twig` namespace remains suppor } only %} ``` -Use `emulsify_theme_project_component_roots` to adjust roots for `project_machine_name:component_name` references. Use `emulsify_theme_twig_namespaces` for advanced runtime-only `@namespace/path.twig` paths. +The filtered `@components` namespace paths supply the default component roots. +`emulsify_theme_project_component_roots` runs afterward and can replace their +order for every component reference form. Later loader `addPath()` or +`prependPath()` calls for `components` update that order for all aliases too. Its machine-name argument is `''` +when project metadata is missing or invalid; `@components` and unregistered +prefix fallback still work in that case. Use `emulsify_theme_twig_namespaces` +for advanced runtime-only `@namespace/path.twig` paths. Root-level `components` and `src/components` directories are compatibility paths, not starter requirements. Do not remove existing `@components` includes during migration; both forms are supported. +Maintainers can compare fixture paths with the installed Core 4.5.0 resolver +and count filesystem work across actual Timber compiles from this repository +checkout: + +```sh +npm run test:component-resolution +npm run smoke:component-request-cache +``` + +The differential check records intentional WordPress compatibility differences +with reasons. Run `npm run smoke:component-request-cache -- --benchmark` for +the repeatable large-tree benchmark; it enables request caching explicitly to +model HTTP rendering from a CLI process. + +A local PHP 8.3.36 run used 500 synthetic groups (about 1,500 added directory +and file entries), ten real Timber compiles per batch, and seven batches with a +warm filesystem cache. Median per-compile times fell from 93.9 ms to 3.84 ms +for a grouped target and from 0.470 ms to 0.291 ms for a direct target. Each +batch began with cleared request caches: the first grouped lookup still scans +the tree, and later compiles reuse it. A separate three-compile counting test +reduced child-root scans from nine to one, parent-root scans from three to one, +and project JSON reads from eighteen to one. Timings depend on the component +tree and filesystem; these are synthetic workload measurements. + See [Component recipes](component-recipes.md) for a small Twig component and Storybook story example that can be added to a generated child theme. ## Component-system namespaces @@ -76,6 +196,10 @@ For legacy `@namespace/path/to/template.twig` references that should work in bot }, "variant": { "structureImplementations": [ + { + "name": "components", + "directory": "src/components" + }, { "name": "atoms", "directory": "src/components/atoms" @@ -89,6 +213,12 @@ For legacy `@namespace/path/to/template.twig` references that should work in bot } ``` +The explicit `components` entry keeps project aliases scoped to the full +component tree; group namespaces remain independent. WordPress trims and +lowercases implementation names, accepts plain ASCII letter/digit/underscore/ +hyphen identifiers, and supplies `structure-N` for unnamed entries. Unsafe or +duplicate namespace names are skipped. + Then includes such as this resolve through the configured child-theme-relative root: ```twig @@ -97,6 +227,12 @@ Then includes such as this resolve through the configured child-theme-relative r } only %} ``` +WordPress keeps its existing configuration containment rules: implementation +paths must be relative to the child theme and cannot contain `..` segments. +Absolute paths, including absolute paths inside the project, remain rejected; +Core accepts some of these contained paths. This restriction applies to +configuration paths, not safe internal dot segments in component references. + Do not use `theme.json` for Twig namespaces. `theme.json` is WordPress configuration for editor settings, global styles, presets, templates, and style variations; it is not a Twig loader configuration file. ## Escaping and trusted HTML @@ -116,6 +252,40 @@ Use `|raw` only for already-rendered, trusted WordPress HTML. Do not use it to p The `bem()` and `add_attributes()` helpers build and escape their own attribute values and are registered as safe HTML. Print them directly without `|raw`. +### WordPress-formatted text + +WordPress can return text that already contains HTML entities. Post and page +titles pass through `the_title`, which texturizes punctuation; site and term +names can be stored escaped; `get_search_query()` escapes its result by default. +Menu titles and author names can contain encoded characters too. Plain Twig +autoescaping would encode those entities again. + +Use Timber's WordPress escaper filters at the output boundary. They handle both +raw text and existing entities and tell Twig that the result is safe HTML: + +| Output | Filter | +| --- | --- | +| Post/page titles in headings and teaser links | `post.title\|wp_kses_post` | +| Site name, archive/search/author heading, menu title, author or comment-author name | `value\|esc_html` | +| Thumbnail alt text, including a post-title fallback | `function('wp_strip_all_tags', value)\|esc_attr` | + +`wp_kses_post` preserves WordPress's allowed post markup and removes disallowed +tags, event handlers, and unsafe URL protocols. Its allowlist is broader than +inline markup. `esc_html` displays tag-looking text literally, without creating +elements. Strip literal tags and script/style contents from alt text before +`esc_attr`; encoded tag-looking text remains inert text in the attribute. + +```twig +<h1>{{ post.title|wp_kses_post }}</h1> +<span>{{ site.name|esc_html }}</span> +<img src="{{ post.thumbnail.src }}" alt="{{ function('wp_strip_all_tags', post.thumbnail.alt|default(post.title))|esc_attr }}"> +``` + +The parent keeps `get_search_query()`'s default escaping and prints the composed +search title with `esc_html`. Do not decode these values or use `|raw` as a +double-escaping workaround. Keep ordinary autoescaping for ACF values, parsed +block data, and other strings that do not have a WordPress formatting contract. + ## Attribute helpers The parent theme registers Core-style helpers for class and attribute handling: @@ -132,6 +302,112 @@ The parent theme registers Core-style helpers for class and attribute handling: The helpers return an attribute bag that serializes safely in Twig string contexts. +Both helpers merge the context's `attributes` with their explicit attributes. +Keep that context value for intentional HTML attributes, never raw block data +or arbitrary user input. Mapped core-block templates receive parsed block data +in `block_attributes`; see [core-block context](core-block-twig-rendering.md#twig-context). + +The PHP attribute bag rejects `srcdoc`, case-insensitive `on*` event names, +`@` shorthand, leading `:` bindings, Alpine `x-*`, and Vue `v-*` directives. +It also rejects htmx `hx-on*`, `hx-vals`, `hx-vars`, `hx-headers`, `hx-request`, +and `hx-trigger`, including their `data-hx-*` aliases. These attributes can +interpret expressions or HTML; escaping their values alone is insufficient. +Static htmx attributes such as `hx-get`, ordinary `data-*` and `aria-*`, and +SVG names such as `viewBox` remain supported. `CLASS` receives the same class +cleaning and merging as `class`; other names retain their authored case. + +WordPress URI attributes, plus `xlink:href`, pass through +`wp_kses_bad_protocol()` with `wp_allowed_protocols()`. Relative URLs, +fragments, `mailto:` and `tel:` remain usable. WordPress's default policy +strips `javascript:` and `data:`; use a permitted URL for images rather than a +data URI. Attribute sources must be arrays, Traversables or another +`AttributeBag`. Arbitrary objects, including `WP_Post`, are ignored so public +properties cannot accidentally expose private data. + +Construction, `set()`, `merge()`, and serialization enforce these rules. They +are intentional PHP differences: Core's JavaScript helpers and Emulsify Drupal +still accept these values and directive names. Projects should review shared +components in both runtimes. + +Argumentless Twig calls such as `{{ add_attributes() }}` and `{{ bem() }}` use +only the context's `attributes`. Other context variables are not attributes or +BEM options. The registered callbacks keep that injected context separate from +explicit arguments; direct PHP helper calls retain their existing API. + +## Helper characterization + +The parent implements `bem()` and `add_attributes()` in PHP; Storybook uses +Emulsify Core's JavaScript helpers. Their shared API does not guarantee identical +behavior for every input. The maintainer contract records each implementation's +observed behavior separately in +`.github/fixtures/twig-helper-contract.json` in the repository checkout. +It uses the WordPress parent's own `AttributeBag`; Core's +[4.5.0 PHP corpus](https://github.com/emulsify-ds/emulsify-core/blob/v4.5.0/docs/twig-php-parity.md) +instead records a pinned Emulsify Tools counterpart. That corpus's portable +subset is not a guarantee about this WordPress implementation. + +This check is for a maintainer checkout; its `.github` scripts and fixtures are +excluded from released parent ZIPs. Install the parent Composer dependencies +and the starter's declared Core dependency, then run it from the repository root: + +```sh +composer install +npm run whisk:install +npm run test:twig-helpers +``` + +The command uses `whisk/` by default. To characterize the Core version installed +in another generated theme, pass its directory: + +```sh +npm run test:twig-helpers -- "/path/to/generated-theme" +``` + +Each case compares three observations against that runtime's own expectations: +the exact serialized HTML string, the returned attribute map, and +`contextAfter`, the attributes remaining in the caller's context. Whitespace, +escaping, attribute types and order, and context mutation remain visible. The +check does not trim output, rewrite escaping, or normalize known differences +to make the PHP and JavaScript results appear equal. + +The recorded ordinary positional/object BEM cases, aliases, nested lists, class +sanitization, list replacement, scalar number serialization, and escaping agree. +Selected differences remain explicit: + +| Recorded input | WordPress PHP | Core 4.5.0 JavaScript | +| --- | --- | --- | +| A `true` BEM modifier | `card--1` | `card--true` | +| Numeric `0` as an extra class | `_0` | Omitted | +| `true` in an `add_attributes()` class list | `_1` | `true` | +| `true` in a non-class attribute list | `1` | `true` | +| Event names, expression directives and `srcdoc` | Dropped | Accepted | +| Disallowed URI protocols | WordPress protocol filtering | Unchanged | +| Uppercase `CLASS` | Cleaned and merged as `class` | Separate attribute | +| Arbitrary object attribute sources | Ignored | Public properties used | +| Caller attributes supplied as an array or attribute bag | Copied; remain in caller context | Consumed from invocation context | + +The fixture cases `bem-boolean-and-numeric-values`, +`add-booleans-aria-and-falsy-classes`, and +`add-invalid-names-and-nested-values` record the coercion differences. +`add-repeated-context-consumption` demonstrates that WordPress prints caller +attributes again on a second call, whereas Core has consumed them. WordPress's +own `AttributeBag` preserves the caller context too; changing from an array to +that bag does not provide print-once behavior. +The event, framework, URL, uppercase-class and object-source cases record +intentional hardening differences in both the returned map and serialized HTML. + +Both implementations currently treat boolean ARIA values like HTML booleans: +`true` can produce a bare attribute, and `false` can be omitted rather than +replacing an existing value. Supply explicit strings such as +`{ 'aria-expanded': 'false' }` for ARIA state values. This describes the tested +inputs, not equivalence for arbitrary attributes or Twig expressions. + +Review changed expectations when updating a helper or Core dependency. A +characterization fixture records compatibility evidence; it does not decide +which runtime should change or promise universal PHP/JavaScript parity. The +check does not replace Twig autoescaping coverage or rendering the affected +template in WordPress with its actual Timber context and hooks. + ## Switch statements The parent theme registers the Emulsify-compatible `switch`, `case`, `default`, and `endswitch` tags used by Emulsify Core in Storybook and Emulsify Tools in Drupal. Use `or` to match more than one value in a case: @@ -163,3 +439,11 @@ add_filter( } ); ``` + +The parent computes its native body-class string once when extending context; +`body_class` and `wp.body_class` remain available. `wp.logout_url` is a lazy, +serializable string value: Twig prints it normally, and PHP consumers should +cast it with `(string)` before passing it to a strict string API. JSON +serialization, including Timber's optional output-cache key, materializes the +URL so cache keys retain their nonce-sensitive value. Default uncached renders +that never request it do not create the logout nonce. diff --git a/docs/upgrading-1x-to-2x.md b/docs/upgrading-1x-to-2x.md index 57b11c7..2976142 100644 --- a/docs/upgrading-1x-to-2x.md +++ b/docs/upgrading-1x-to-2x.md @@ -46,7 +46,10 @@ When a child template extends the parent template with the same relative path, u {% extends '@emulsify-tpl/page.twig' %} ``` -Using `@templates/page.twig` from `whisk/templates/page.twig` would resolve back to the child file. +Using `@templates/page.twig` from a child `templates/page.twig` would resolve +back to the child file. New generated themes ship no Twig templates or +`templates/` directory; create one only when needed. See the [template extension +contract](template-extension.md) for the supported blocks and boundaries. ## Block metadata changes diff --git a/docs/wp-cli-child-theme-generation.md b/docs/wp-cli-child-theme-generation.md index 47e37b3..75b3568 100644 --- a/docs/wp-cli-child-theme-generation.md +++ b/docs/wp-cli-child-theme-generation.md @@ -122,9 +122,11 @@ The hook deliberately mirrors the parent WP-CLI generator's targeted updates: - `package.json` name and generated package lockfile root name. - `project.emulsify.json` project name, machine name, generated source metadata, and `"platform": "wordpress"`. - Visible Whisk labels in known starter files. -- `templates/page.twig` class from `whisk-page` to the generated machine-name class. - JSON pattern names from the `whisk/*` namespace to the generated machine-name namespace. +No Twig templates or `templates/` directory are generated. Create project +overrides only as needed, using the [template extension contract](template-extension.md). + The generated child theme must keep `Template: emulsify`; the parent theme remains installed separately as `emulsify`. ## After generation diff --git a/husky.config.js b/husky.config.js deleted file mode 100644 index 76e1875..0000000 --- a/husky.config.js +++ /dev/null @@ -1,7 +0,0 @@ -module.exports = { - hooks: { - // Retained for projects still using Husky's JS config loader; package.json - // exposes the same hook command for current installs. - 'commit-msg': 'commitlint -E HUSKY_GIT_PARAMS', - }, -}; diff --git a/includes/Blocks/AcfBlocks.php b/includes/Blocks/AcfBlocks.php index 8fa1e9e..f7410ba 100644 --- a/includes/Blocks/AcfBlocks.php +++ b/includes/Blocks/AcfBlocks.php @@ -225,7 +225,12 @@ public function render_block( $block, $content = '', $is_preview = false, $post_ * @return array|null Component metadata, or null when invalid. */ private function metadata( string $path ): ?array { - $contents = file_get_contents( $path ); + if ( ! is_file( $path ) || ! is_readable( $path ) ) { + return null; + } + + // A build can remove metadata between the readability check and the read. + $contents = @file_get_contents( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- Expected deploy race after the guarded check above. if ( ! is_string( $contents ) ) { return null; diff --git a/includes/Blocks/ComponentLocator.php b/includes/Blocks/ComponentLocator.php index b14e608..0e12191 100644 --- a/includes/Blocks/ComponentLocator.php +++ b/includes/Blocks/ComponentLocator.php @@ -7,6 +7,7 @@ namespace Emulsify\Theme\Blocks; +use Emulsify\Theme\Support\AssetManifest; use Emulsify\Theme\Support\AssetRecord; use Emulsify\Theme\Support\Diagnostics; use Emulsify\Theme\Support\FileDiscovery; @@ -29,18 +30,18 @@ final class ComponentLocator { private const COMPONENTS_DIRECTORY = 'dist/components'; /** - * Theme-relative built asset manifest path. + * Transient key prefix for optional persistent discovery caching. * * @var string */ - private const DEFAULT_MANIFEST_PATH = 'dist/emulsify-assets.json'; + private const CACHE_TRANSIENT_PREFIX = 'emulsify_component_discovery_'; /** - * Transient key prefix for optional persistent discovery caching. + * Root-relative cache payload format. * - * @var string + * @var int */ - private const CACHE_TRANSIENT_PREFIX = 'emulsify_component_discovery_'; + private const CACHE_SCHEMA = 2; /** * Default persistent cache lifetime in seconds. @@ -56,6 +57,13 @@ final class ComponentLocator { */ private $component_roots; + /** + * Memoized root identities and build signals for this locator. + * + * @var array|null + */ + private $component_root_state; + /** * Memoized component file records. * @@ -84,6 +92,23 @@ final class ComponentLocator { */ private $skipped_duplicates = array(); + /** + * Gets component metadata files, including components without a Twig template. + * + * @return array Absolute metadata paths in child-first discovery order. + */ + public function component_metadata_files(): array { + $paths = array(); + + foreach ( $this->component_files() as $file ) { + if ( preg_match( '/\.component\.json$/', basename( $file['path'] ) ) ) { + $paths[] = $file['path']; + } + } + + return $paths; + } + /** * Clears the optional persistent discovery cache for the current theme state. * @@ -288,8 +313,13 @@ private function component_files(): array { return $this->component_files; } - $this->component_files = FileDiscovery::file_records( $this->component_roots() ); - $this->cache_component_files( $this->component_files ); + // Both consumers inspect JSON metadata; Twig candidates are checked directly. + $complete = true; + $this->component_files = FileDiscovery::file_records( $this->component_roots(), array( 'json' ), true, $complete ); + + if ( $complete ) { + $this->cache_component_files( $this->component_files ); + } return $this->component_files; } @@ -306,11 +336,25 @@ private function cached_component_files(): ?array { $cached = get_transient( $this->component_files_cache_key() ); - if ( ! is_array( $cached ) || ! isset( $cached['files'] ) || ! is_array( $cached['files'] ) ) { + if ( ! is_array( $cached ) ) { return null; } - return $this->normalize_cached_component_files( $cached['files'] ); + $files = null; + + if ( + self::CACHE_SCHEMA === ( $cached['schema'] ?? null ) + && $this->component_roots_signature() === ( $cached['roots'] ?? null ) + && isset( $cached['files'] ) && is_array( $cached['files'] ) + ) { + $files = $this->normalize_cached_component_files( $cached['files'] ); + } + + if ( null === $files ) { + $this->delete_component_files_cache(); + } + + return $files; } /** @@ -324,10 +368,27 @@ private function cache_component_files( array $files ): void { return; } + $roots = $this->component_roots(); + $relative = array(); + + foreach ( $files as $file ) { + foreach ( $roots as $index => $root ) { + if ( $file['root_path'] === $root['path'] ) { + $relative[] = array( + 'root' => $index, + 'relative' => $file['relative'], + ); + break; + } + } + } + set_transient( $this->component_files_cache_key(), array( - 'files' => $files, + 'schema' => self::CACHE_SCHEMA, + 'roots' => $this->component_roots_signature(), + 'files' => $relative, ), $this->component_files_cache_ttl() ); @@ -376,24 +437,29 @@ private function persistent_cache_enabled(): bool { * @return string Transient key. */ private function component_files_cache_key(): string { + clearstatcache( true ); $stylesheet = $this->stylesheet(); $template = $this->template(); $stylesheet_directory = function_exists( 'get_stylesheet_directory' ) ? get_stylesheet_directory() : ''; $template_directory = function_exists( 'get_template_directory' ) ? get_template_directory() : ''; $key_parts = array( - 'stylesheet' => $stylesheet, - 'template' => $template, - 'stylesheet_version' => $this->theme_version( $stylesheet, $stylesheet_directory ), - 'template_version' => $this->theme_version( $template, $template_directory ), - 'environment' => $this->environment_type(), - 'manifest' => $this->manifest_file_signature(), + 'stylesheet' => $stylesheet, + 'template' => $template, + 'stylesheet_version' => $this->theme_version( $stylesheet, $stylesheet_directory ), + 'template_version' => $this->theme_version( $template, $template_directory ), + 'environment' => $this->environment_type(), + 'manifest' => $this->manifest_file_signature(), + 'stylesheet_directory' => array( $stylesheet_directory, realpath( $stylesheet_directory ) ), + 'template_directory' => array( $template_directory, realpath( $template_directory ) ), + 'roots' => $this->component_root_state(), ); /** * Filters the component discovery persistent cache key parts. * - * Projects that alter component roots dynamically can add their own - * version token here, or change it to invalidate cached discovery. + * Defaults include theme directories, canonical component roots and root + * build timestamps/identity. Custom builds that modify nested directories + * in place should add a build token here or clear the discovery cache. * * @param array $key_parts Cache key parts. * @param ComponentLocator $locator Component locator instance. @@ -413,6 +479,45 @@ private function component_files_cache_key(): string { return self::CACHE_TRANSIENT_PREFIX . md5( $encoded ); } + /** + * Gets ordered root identities and stable filesystem build signals. + * + * Core production builds recreate dist/components. Statting each root avoids + * walking the tree on warm requests; access times deliberately stay out. + * + * @return array Root state. + */ + private function component_root_state(): array { + if ( is_array( $this->component_root_state ) ) { + return $this->component_root_state; + } + + $this->component_root_state = array(); + + foreach ( $this->component_roots() as $root ) { + clearstatcache( true, $root['path'] ); + $stat = @stat( $root['path'] ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- A build can remove the root after normalization. + $this->component_root_state[] = array( + 'path' => $root['path'], + 'canonical' => realpath( $root['path'] ), + 'source' => $root['source'], + 'priority' => $root['priority'], + 'build' => is_array( $stat ) ? array_intersect_key( $stat, array_flip( array( 'dev', 'ino', 'mtime', 'ctime', 'size' ) ) ) : null, + ); + } + + return $this->component_root_state; + } + + /** + * Binds relative cache records to the active roots even with a custom key. + * + * @return string Root state fingerprint. + */ + private function component_roots_signature(): string { + return md5( serialize( $this->component_root_state() ) ); + } + /** * Gets the optional persistent cache lifetime. * @@ -440,32 +545,43 @@ private function component_files_cache_ttl(): int { */ private function normalize_cached_component_files( array $files ): ?array { $normalized = array(); + $roots = $this->component_roots(); foreach ( $files as $file ) { if ( ! is_array( $file ) - || empty( $file['path'] ) - || empty( $file['relative'] ) - || empty( $file['root_path'] ) - || empty( $file['root_source'] ) - || ! is_scalar( $file['path'] ) - || ! is_scalar( $file['relative'] ) - || ! is_scalar( $file['root_path'] ) - || ! is_scalar( $file['root_source'] ) + || ! isset( $file['root'], $file['relative'] ) + || ! is_int( $file['root'] ) || ! isset( $roots[ $file['root'] ] ) + || ! is_string( $file['relative'] ) || '' === $file['relative'] + || AssetRecord::normalize_relative_path( $file['relative'] ) !== $file['relative'] + ) { + return null; + } + + $root = $roots[ $file['root'] ]; + $path = $root['path'] . '/' . $file['relative']; + clearstatcache( true, $path ); + $canonical = realpath( $path ); + $canonical_root = realpath( $root['path'] ); + + if ( + false === $canonical || false === $canonical_root + || 0 !== strpos( $canonical, rtrim( $canonical_root, '/\\' ) . DIRECTORY_SEPARATOR ) + || ! is_file( $path ) || ! is_readable( $path ) ) { return null; } $record = array( - 'path' => (string) $file['path'], - 'priority' => isset( $file['priority'] ) ? (int) $file['priority'] : 0, - 'relative' => (string) $file['relative'], - 'root_path' => (string) $file['root_path'], - 'root_source' => (string) $file['root_source'], + 'path' => $path, + 'priority' => $root['priority'], + 'relative' => $file['relative'], + 'root_path' => $root['path'], + 'root_source' => $root['source'], ); - if ( isset( $file['root_uri'] ) && is_scalar( $file['root_uri'] ) ) { - $record['root_uri'] = (string) $file['root_uri']; + if ( isset( $root['uri'] ) ) { + $record['root_uri'] = $root['uri']; } $normalized[] = $record; @@ -589,7 +705,7 @@ private function style_css_version( string $directory ): string { * @return string Manifest signature. */ private function manifest_file_signature(): string { - $relative_path = $this->manifest_relative_path(); + $relative_path = AssetManifest::relative_path(); if ( '' === $relative_path ) { return ''; @@ -619,31 +735,6 @@ private function manifest_file_signature(): string { return implode( '|', $signatures ); } - /** - * Gets the theme-relative asset manifest path. - * - * @return string Manifest path, or empty string when disabled. - */ - private function manifest_relative_path(): string { - $relative_path = self::DEFAULT_MANIFEST_PATH; - - /** - * Filters the theme-relative asset manifest path. - * - * This mirrors asset loading so changing the manifest path also changes - * the optional component discovery cache key. - * - * @param string $relative_path Theme-relative manifest path. - */ - $filtered = apply_filters( 'emulsify_theme_asset_manifest_path', $relative_path ); - - if ( ! is_scalar( $filtered ) ) { - return ''; - } - - return AssetRecord::normalize_relative_path( (string) $filtered ); - } - /** * Gets child theme component roots first, then parent theme fallbacks. * @@ -675,6 +766,8 @@ private function component_roots(): array { $candidates = $filtered; } + // Release symlinks can change in a long-running WP-CLI process too. + clearstatcache( true ); $this->component_roots = FileDiscovery::normalize_roots( $candidates, array( @@ -712,7 +805,12 @@ private function component_record( array $file, string $directory, string $relat * @return string Native block name, or an empty string when unavailable. */ private function native_block_name( string $path ): string { - $contents = file_get_contents( $path ); + if ( ! is_file( $path ) || ! is_readable( $path ) ) { + return ''; + } + + // A build can remove metadata between the readability check and the read. + $contents = @file_get_contents( $path ); // phpcs:ignore WordPress.PHP.NoSilencedErrors.Discouraged -- Expected deploy race after the guarded check above. if ( ! is_string( $contents ) ) { return ''; diff --git a/includes/Blocks/CoreBlockTwigRenderer.php b/includes/Blocks/CoreBlockTwigRenderer.php index 711fb96..45ba84b 100644 --- a/includes/Blocks/CoreBlockTwigRenderer.php +++ b/includes/Blocks/CoreBlockTwigRenderer.php @@ -12,6 +12,34 @@ */ final class CoreBlockTwigRenderer { + /** + * Global context reused by the request's shared renderer. + * + * @var array|null + */ + private $base_context; + + /** + * Last filtered map and its normalized result. + * + * @var array|null + */ + private $filtered_template_map; + + /** + * Normalized map for the last filter result. + * + * @var array + */ + private $normalized_template_map = array(); + + /** + * Whether this renderer is already resolving or compiling a mapped block. + * + * @var bool + */ + private $rendering = false; + /** * Registers block rendering hooks when explicitly enabled. * @@ -34,40 +62,47 @@ public function register(): void { * @return string Rendered block content. */ public function render_block( string $block_content, array $block, $instance = null ): string { + if ( $this->rendering ) { + return $block_content; + } + $block_name = $this->block_name( $block ); if ( '' === $block_name ) { return $block_content; } - $template = $this->template_for_block( $block_name, $block ); + $this->rendering = true; + $template = ''; + try { + $template = $this->template_for_block( $block_name, $block ); - if ( '' === $template ) { - // Unmapped blocks keep WordPress' original HTML, which protects block - // validation and frontend output unless a project opts in block-by-block. - return $block_content; - } + if ( '' === $template ) { + // Unmapped blocks keep every byte of WordPress' original markup. + return $block_content; + } - if ( ! class_exists( '\Timber\Timber' ) ) { - return $this->render_error( $block_content, $this->translate( 'Timber is not available for mapped block rendering.', 'emulsify' ), $block, $template ); - } + if ( ! class_exists( '\Timber\Timber' ) ) { + return $this->render_error( $block_content, $this->translate( 'Timber is not available for mapped block rendering.', 'emulsify' ), $block, $template ); + } - try { $context = $this->context( $block, $block_content, $instance, $template ); $html = \Timber\Timber::compile( $template, $context ); + + if ( ! is_string( $html ) || '' === $html ) { + return $block_content; + } + + return $this->cleanup_classes_enabled( $block, $template ) + ? $this->cleanup_classes( $html, $block ) + : $html; } catch ( \Throwable $throwable ) { // Rendering failures should not blank content. Editors get diagnostics // when allowed; visitors continue to receive WordPress' rendered block. return $this->render_error( $block_content, $throwable->getMessage(), $block, $template ); + } finally { + $this->rendering = false; } - - if ( ! is_string( $html ) || '' === $html ) { - return $block_content; - } - - return $this->cleanup_classes_enabled( $block, $template ) - ? $this->cleanup_classes( $html, $block ) - : $html; } /** @@ -97,11 +132,21 @@ private function enabled(): bool { * @return array Twig context. */ private function context( array $block, string $block_content, $instance, string $template ): array { - $context = array(); + if ( null === $this->base_context ) { + $timber_context = \Timber\Timber::context_global(); + $this->base_context = is_array( $timber_context ) ? $timber_context : array(); + } + + $context = $this->base_context; + $block_context = is_object( $instance ) && isset( $instance->context ) && is_array( $instance->context ) ? $instance->context : array(); - if ( class_exists( '\Timber\Timber' ) ) { - $timber_context = \Timber\Timber::context(); - $context = is_array( $timber_context ) ? $timber_context : array(); + // Do not call setup(): it resets WordPress' loop globals and fires the_post. + // Always replace any post cached by a global Timber context filter. + if ( array_key_exists( 'postId', $block_context ) ) { + $post_id = $block_context['postId']; + $context['post'] = is_numeric( $post_id ) && (int) $post_id > 0 ? \Timber\Timber::get_post( (int) $post_id ) : null; + } else { + $context['post'] = \Timber\Timber::get_post( $GLOBALS['post'] ?? false ); } $attributes = isset( $block['attrs'] ) && is_array( $block['attrs'] ) ? $block['attrs'] : array(); @@ -109,19 +154,23 @@ private function context( array $block, string $block_content, $instance, string // Keep WordPress' original rendered content available to Twig templates so // mapped blocks can wrap or progressively replace markup instead of being // forced into an all-or-nothing rewrite. - $context['block'] = $block; - $context['block_metadata'] = $block; - $context['block_name'] = $this->block_name( $block ); - $context['attributes'] = $attributes; - $context['content'] = $block_content; - $context['inner_content'] = $this->inner_content( $block, $block_content ); - $context['inner_blocks'] = isset( $block['innerBlocks'] ) && is_array( $block['innerBlocks'] ) ? $block['innerBlocks'] : array(); - $context['wp_block'] = $instance; - $context['twig_template'] = $template; + $context['block'] = $block; + $context['block_metadata'] = $block; + $context['block_name'] = $this->block_name( $block ); + $context['block_attributes'] = $attributes; + $context['attributes'] = array(); + $context['content'] = $block_content; + $context['inner_content'] = $this->inner_content( $block, $block_content ); + $context['inner_blocks'] = isset( $block['innerBlocks'] ) && is_array( $block['innerBlocks'] ) ? $block['innerBlocks'] : array(); + $context['wp_block'] = $instance; + $context['twig_template'] = $template; /** * Filters Twig context for mapped block rendering. * + * The attributes array is reserved for HTML attributes only and must + * never hold block data or user input. Read block_attributes for block data. + * * @param array $context Twig context. * @param array $block Parsed block metadata. * @param string $block_content Rendered WordPress block content. @@ -148,6 +197,12 @@ private function inner_content( array $block, string $block_content ): string { $content = ''; foreach ( $block['innerContent'] as $piece ) { + if ( null === $piece ) { + // Children have already rendered. Their final filtered output cannot + // be recovered from parsed fragments without rendering them again. + return $block_content; + } + if ( is_scalar( $piece ) ) { $content .= (string) $piece; } @@ -208,6 +263,12 @@ private function template_map(): array { return array(); } + // Keep callbacks dynamic and honor late registration/removal. Reuse only + // normalization when their result is unchanged, not the filter invocation. + if ( $filtered === $this->filtered_template_map ) { + return $this->normalized_template_map; + } + $map = array(); foreach ( $filtered as $block_name => $template ) { @@ -223,7 +284,16 @@ private function template_map(): array { } } - return $map; + // Snapshot values, including scalars returned by reference from a filter. + $this->filtered_template_map = array_map( + static function ( $value ) { + return $value; + }, + $filtered + ); + $this->normalized_template_map = $map; + + return $this->normalized_template_map; } /** @@ -241,7 +311,8 @@ private function resolve_template( string $template ): string { } foreach ( $this->theme_roots() as $root ) { - if ( is_readable( rtrim( $root, '/\\' ) . '/' . $template ) ) { + $path = rtrim( $root, '/\\' ) . '/' . $template; + if ( is_file( $path ) && is_readable( $path ) ) { // Return the theme-relative path because Timber resolves templates // through its configured child/parent loaders. return $template; diff --git a/includes/Blocks/Patterns.php b/includes/Blocks/Patterns.php index 3181a3e..0e487fc 100644 --- a/includes/Blocks/Patterns.php +++ b/includes/Blocks/Patterns.php @@ -36,10 +36,6 @@ public function register(): void { * @return void */ public function register_patterns(): void { - if ( ! function_exists( 'register_block_pattern' ) ) { - return; - } - $patterns = $this->pattern_records(); if ( empty( $patterns ) ) { @@ -463,7 +459,7 @@ private function is_category_metadata_file( string $relative ): bool { * @return void */ private function register_categories( array $categories, array $patterns ): void { - if ( empty( $patterns ) || ! function_exists( 'register_block_pattern_category' ) ) { + if ( empty( $patterns ) ) { return; } @@ -500,13 +496,7 @@ static function ( string $value ): bool { * @return bool TRUE when the pattern is already registered. */ private function pattern_registered( string $name ): bool { - if ( ! class_exists( '\WP_Block_Patterns_Registry' ) ) { - return false; - } - - $registry = \WP_Block_Patterns_Registry::get_instance(); - - return method_exists( $registry, 'is_registered' ) && $registry->is_registered( $name ); + return \WP_Block_Patterns_Registry::get_instance()->is_registered( $name ); } /** @@ -516,19 +506,7 @@ private function pattern_registered( string $name ): bool { * @return bool TRUE when the category is already registered. */ private function category_registered( string $name ): bool { - foreach ( array( '\WP_Block_Pattern_Categories_Registry', '\WP_Block_Pattern_Category_Registry' ) as $class ) { - if ( ! class_exists( $class ) ) { - continue; - } - - $registry = $class::get_instance(); - - if ( method_exists( $registry, 'is_registered' ) && $registry->is_registered( $name ) ) { - return true; - } - } - - return false; + return \WP_Block_Pattern_Categories_Registry::get_instance()->is_registered( $name ); } /** diff --git a/includes/Blocks/Registry.php b/includes/Blocks/Registry.php index c61cea0..3f8646d 100644 --- a/includes/Blocks/Registry.php +++ b/includes/Blocks/Registry.php @@ -21,13 +21,22 @@ final class Registry { */ private $manifest; + /** + * Shared component metadata index. + * + * @var ComponentLocator + */ + private $components; + /** * Constructor. * - * @param AssetManifest|null $manifest Asset manifest reader. + * @param AssetManifest|null $manifest Asset manifest reader. + * @param ComponentLocator|null $components Shared component metadata index. */ - public function __construct( ?AssetManifest $manifest = null ) { - $this->manifest = $manifest ?? new AssetManifest(); + public function __construct( ?AssetManifest $manifest = null, ?ComponentLocator $components = null ) { + $this->manifest = $manifest ?? new AssetManifest(); + $this->components = $components ?? new ComponentLocator(); } /** @@ -43,11 +52,9 @@ static function (): void { } ); - $components = new ComponentLocator(); - // Share one locator so ACF/Twig and native block registration use the same // request-local child-first component index and duplicate diagnostics. - ( new AcfBlocks( $components, $this->manifest ) )->register(); - ( new NativeBlocks( $components ) )->register(); + ( new AcfBlocks( $this->components, $this->manifest ) )->register(); + ( new NativeBlocks( $this->components ) )->register(); } } diff --git a/includes/Bootstrap.php b/includes/Bootstrap.php index 4b609fd..94b2c25 100644 --- a/includes/Bootstrap.php +++ b/includes/Bootstrap.php @@ -13,6 +13,7 @@ use Emulsify\Theme\Cli\GenerateChildThemeCommand; use Emulsify\Theme\Editor\Enhancements; use Emulsify\Theme\Editor\Policy; +use Emulsify\Theme\Media\Embeds; use Emulsify\Theme\Runtime\Assets; use Emulsify\Theme\Runtime\Context; use Emulsify\Theme\Runtime\MissingTimber; @@ -63,19 +64,21 @@ private function register(): void { $this->load_classes(); $asset_manifest = new AssetManifest(); + $components = new Blocks\ComponentLocator(); // These services use WordPress APIs directly and must stay available even // when Timber is missing. The MissingTimber service owns frontend failure // handling later in this method. ( new Setup() )->register(); - ( new Assets( $asset_manifest ) )->register(); + ( new Assets( $asset_manifest, $components ) )->register(); ( new LocalJson() )->register(); ( new CoreBlockTwigRenderer() )->register(); ( new Enhancements( $asset_manifest ) )->register(); ( new Policy() )->register(); ( new Patterns() )->register(); - ( new Blocks\Registry( $asset_manifest ) )->register(); + ( new Blocks\Registry( $asset_manifest, $components ) )->register(); ( new GenerateChildThemeCommand() )->register(); + ( new Embeds() )->register(); $timber = new TimberIntegration(); diff --git a/includes/Cli/GenerateChildThemeCommand.php b/includes/Cli/GenerateChildThemeCommand.php index 2b3afe3..f18f381 100644 --- a/includes/Cli/GenerateChildThemeCommand.php +++ b/includes/Cli/GenerateChildThemeCommand.php @@ -195,6 +195,7 @@ private function generate( array $args, array $assoc_args ): void { $staged = $this->apply_metadata_updates( $staging, $metadata_updates ); } } catch ( \Throwable $exception ) { + $staged = false; \WP_CLI::warning( sprintf( 'Could not finish staging the child theme: %s', $exception->getMessage() ) ); } @@ -252,6 +253,11 @@ private function copy_theme( string $source, string $destination ): bool { $target = $this->join_path( $destination, $relative ); + if ( $item->isLink() ) { + \WP_CLI::warning( sprintf( 'Skipping symlink in starter theme: %s', $path ) ); + continue; + } + if ( $item->isDir() ) { if ( ! $this->make_directory( $target ) ) { \WP_CLI::warning( sprintf( 'Could not create directory: %s', $target ) ); @@ -261,11 +267,6 @@ private function copy_theme( string $source, string $destination ): bool { continue; } - if ( $item->isLink() ) { - \WP_CLI::warning( sprintf( 'Skipping symlink in starter theme: %s', $path ) ); - continue; - } - if ( ! $this->make_directory( dirname( $target ) ) || ! copy( $path, $target ) ) { \WP_CLI::warning( sprintf( 'Could not copy %s to %s.', $path, $target ) ); return false; @@ -313,9 +314,9 @@ function ( string $contents ) use ( $source_label, $machine_name, $parent, $desc $updates, $root, 'package.json', - function ( array $data ) use ( $machine_name, $description ): array { - $data['name'] = $machine_name; - $data['description'] = $this->one_line( $description ); + function ( \stdClass $data ) use ( $machine_name, $description ): \stdClass { + $data->name = $machine_name; + $data->description = $this->one_line( $description ); return $data; } ); @@ -324,18 +325,18 @@ function ( array $data ) use ( $machine_name, $description ): array { $updates, $root, 'project.emulsify.json', - function ( array $data ) use ( $theme_label, $machine_name, $version, $description ): array { - if ( ! isset( $data['project'] ) || ! is_array( $data['project'] ) ) { - $data['project'] = array(); + function ( \stdClass $data ) use ( $theme_label, $machine_name, $version, $description ): \stdClass { + if ( ! isset( $data->project ) || ! $data->project instanceof \stdClass ) { + $data->project = new \stdClass(); } // phpcs:ignore WordPress.WP.CapitalPDangit.MisspelledInText -- project.platform is a machine-readable adapter key. - $data['project']['platform'] = 'wordpress'; - $data['project']['name'] = $theme_label; - $data['project']['machineName'] = $machine_name; - $data['project']['generatedFrom'] = self::GENERATED_FROM; - $data['project']['generatedFromVersion'] = $version; - $data['project']['description'] = $this->one_line( $description ); + $data->project->platform = 'wordpress'; + $data->project->name = $theme_label; + $data->project->machineName = $machine_name; + $data->project->generatedFrom = self::GENERATED_FROM; + $data->project->generatedFromVersion = $version; + $data->project->description = $this->one_line( $description ); return $data; } @@ -350,15 +351,6 @@ function ( string $contents ) use ( $source_label ): string { } ); - $this->collect_text_update( - $updates, - $root, - 'templates/page.twig', - function ( string $contents ) use ( $machine_name ): string { - return str_replace( self::STARTER_SLUG . '-page', $machine_name . '-page', $contents ); - } - ); - $this->collect_pattern_updates( $updates, $root, $machine_name ); $this->collect_documentation_updates( @@ -442,24 +434,29 @@ private function collect_pattern_updates( array &$updates, string $root, string return; } - $files = glob( $pattern_dir . '/*.json' ); + $iterator = new \RecursiveIteratorIterator( + new \RecursiveDirectoryIterator( $pattern_dir, \RecursiveDirectoryIterator::SKIP_DOTS ) + ); + $files = array(); - if ( ! is_array( $files ) ) { - return; + foreach ( $iterator as $item ) { + if ( ! $item->isLink() && $item->isFile() && 'json' === $item->getExtension() ) { + $files[] = $item->getPathname(); + } } sort( $files ); foreach ( $files as $path ) { - $relative = 'patterns/' . basename( $path ); + $relative = $this->relative_path( $root, $path ); $this->collect_json_update( $updates, $root, $relative, - function ( array $data ) use ( $machine_name ): array { - if ( isset( $data['name'] ) && is_string( $data['name'] ) && 0 === strpos( $data['name'], self::STARTER_SLUG . '/' ) ) { - $data['name'] = $machine_name . '/' . substr( $data['name'], strlen( self::STARTER_SLUG ) + 1 ); + function ( \stdClass $data ) use ( $machine_name ): \stdClass { + if ( isset( $data->name ) && is_string( $data->name ) && 0 === strpos( $data->name, self::STARTER_SLUG . '/' ) ) { + $data->name = $machine_name . '/' . substr( $data->name, strlen( self::STARTER_SLUG ) + 1 ); } return $data; @@ -510,6 +507,8 @@ private function collect_text_update( array &$updates, string $root, string $rel * @param string $relative Relative file path. * @param callable $callback Data updater. * @return void + * + * @throws \RuntimeException When JSON is invalid or is not an object. */ private function collect_json_update( array &$updates, string $root, string $relative, callable $callback ): void { $path = $this->join_path( $root, $relative ); @@ -526,11 +525,11 @@ private function collect_json_update( array &$updates, string $root, string $rel return; } - $data = json_decode( $contents, true ); + $data = json_decode( $contents ); - if ( ! is_array( $data ) ) { - \WP_CLI::warning( sprintf( 'Could not decode starter JSON file: %s', $path ) ); - return; + if ( ! $data instanceof \stdClass ) { + // phpcs:ignore WordPress.Security.EscapeOutput.ExceptionNotEscaped -- Internal generator path, not rendered HTML. + throw new \RuntimeException( sprintf( 'Starter JSON file must contain a valid JSON object: %s', $relative ) ); } $updated_data = $callback( $data ); @@ -765,10 +764,10 @@ private function get_core_range( string $source ): string { * Whisk sources all use two. Re-indenting here keeps generated JSON identical * no matter which generation path a project used. * - * @param array $data Data to encode. + * @param \stdClass $data Data to encode. * @return string|null Encoded JSON, or NULL on failure. */ - private function encode_json( array $data ): ?string { + private function encode_json( \stdClass $data ): ?string { // JSON_UNESCAPED_UNICODE matches JSON.stringify, which never escapes // non-ASCII. Without it a non-ASCII theme name or description would make // the two generation paths emit different bytes. Do not add diff --git a/includes/Editor/Enhancements.php b/includes/Editor/Enhancements.php index 665876e..8dba541 100644 --- a/includes/Editor/Enhancements.php +++ b/includes/Editor/Enhancements.php @@ -9,6 +9,7 @@ use Emulsify\Theme\Support\AssetEnqueuer; use Emulsify\Theme\Support\AssetManifest; +use Emulsify\Theme\Support\AssetRecord; use Emulsify\Theme\Support\FileDiscovery; /** @@ -319,27 +320,7 @@ private function manifest_asset_files( string $directory, array $extensions ): ? * @return array Built asset records. */ private function scanned_asset_files( string $directory, array $extensions ): array { - $assets = array(); - $seen = array(); - - foreach ( FileDiscovery::file_records( $this->asset_roots( $directory ), $extensions ) as $file ) { - $relative = $file['relative']; - - if ( isset( $seen[ $relative ] ) ) { - continue; - } - - $seen[ $relative ] = true; - $assets[] = array( - 'path' => $file['path'], - 'priority' => $file['priority'], - 'relative' => $relative, - 'uri' => $file['root_uri'] . '/' . $relative, - 'version' => $this->version( $file['path'] ), - ); - } - - return FileDiscovery::sort_by_priority_and_relative( $assets ); + return AssetRecord::from_discovered_files( FileDiscovery::file_records( $this->asset_roots( $directory ), $extensions ) ); } /** @@ -349,8 +330,6 @@ private function scanned_asset_files( string $directory, array $extensions ): ar * @return array Asset root records. */ private function asset_roots( string $directory ): array { - $directories = FileDiscovery::theme_roots( $directory, true ); - /** * Filters built editor asset directories before discovery. * @@ -361,18 +340,7 @@ private function asset_roots( string $directory ): array { * @param array $directories Built editor asset directory records. * @param string $directory Theme-relative asset directory being scanned. */ - $filtered = apply_filters( 'emulsify_theme_editor_asset_directories', $directories, $directory ); - - if ( is_array( $filtered ) ) { - $directories = $filtered; - } - - return FileDiscovery::normalize_roots( - $directories, - array( - 'require_uri' => true, - ) - ); + return FileDiscovery::filtered_theme_roots( $directory, 'emulsify_theme_editor_asset_directories' ); } /** @@ -501,18 +469,6 @@ private function string_list( $values ): array { return array_values( array_unique( $strings ) ); } - /** - * Gets a filemtime-based asset version. - * - * @param string $path Absolute file path. - * @return string|null Asset version. - */ - private function version( string $path ): ?string { - $modified = filemtime( $path ); - - return false === $modified ? null : (string) $modified; - } - /** * JSON encodes a value for inline script output. * diff --git a/includes/Media/Embeds.php b/includes/Media/Embeds.php new file mode 100644 index 0000000..bdb8bb7 --- /dev/null +++ b/includes/Media/Embeds.php @@ -0,0 +1,427 @@ +<?php +/** + * Adds optional privacy and native click-to-load behavior to video oEmbeds. + * + * @package Emulsify + */ + +namespace Emulsify\Theme\Media; + +/** + * Alters recognized players when content is rendered, outside the oEmbed cache. + */ +final class Embeds { + + /** Vimeo thumbnail transient prefix. */ + public const METADATA_PREFIX = 'emulsify_vimeo_poster_'; + + /** Vimeo refresh retry marker prefix. */ + public const BACKOFF_PREFIX = 'emulsify_vimeo_poster_backoff_'; + + /** + * Registers rendering and deferred metadata hooks. + * + * @return void + */ + public function register(): void { + add_filter( 'embed_oembed_html', array( $this, 'filter_html' ), 20, 4 ); + add_filter( 'oembed_dataparse', array( $this, 'cache_oembed_data' ), 20, 3 ); + add_action( 'emulsify_theme_refresh_vimeo_poster', array( $this, 'refresh_vimeo_poster' ) ); + } + + /** + * Changes only supported, complete player iframes. + * + * @param mixed $html Cached provider HTML; non-strings pass through unchanged. + * @param mixed $url Original embed URL, normalized to a string. + * @param mixed $attr Embed attributes, normalized to an array. + * @param mixed $post_id Positive post ID or numeric string, otherwise null. + * @return mixed Rendered embed HTML, or the unchanged non-string input. + * @throws \RuntimeException In debug mode when Timber is missing. + * @throws \UnexpectedValueException In debug mode when the poster is empty. + * @throws \Throwable Rethrows other poster failures only in debug mode. + */ + public function filter_html( $html, $url = '', $attr = array(), $post_id = 0 ) { + if ( ! is_string( $html ) ) { + return $html; + } + $url = is_string( $url ) ? $url : ''; + $attr = is_array( $attr ) ? $attr : array(); + $post_id = $this->normalize_post_id( $post_id ); + $options = $this->options( $url, $attr, $post_id ); + if ( ! $options['privacy_mode'] && ! $options['click_to_load'] ) { + return $html; + } + + $processor = $this->player_iframe( $html ); + if ( null === $processor ) { + return $html; + } + $source = $processor->get_attribute( 'src' ); + $player = is_string( $source ) ? $this->player( $source ) : null; + if ( null === $player ) { + return $html; + } + + $player_url = $source; + if ( $options['privacy_mode'] ) { + $player_url = 'youtube' === $player['provider'] + ? preg_replace( '#^https://[^/?\#]+#i', 'https://www.youtube-nocookie.com', $source ) + : $this->set_parameter( $source, 'dnt' ); + $processor->set_attribute( 'src', $player_url ); + } + if ( $options['click_to_load'] ) { + $title = $processor->get_attribute( 'title' ); + $has_title = is_string( $title ) && '' !== trim( $title ); + $title = $has_title ? $title : ( 'youtube' === $player['provider'] ? __( 'YouTube video', 'emulsify' ) : __( 'Vimeo video', 'emulsify' ) ); + try { + if ( ! class_exists( '\Timber\Timber' ) ) { + throw new \RuntimeException( 'Timber is required to render click-to-load media embeds.' ); + } + $metadata = array(); + $thumbnail = ''; + if ( 'neutral' !== $options['poster'] ) { + if ( 'youtube' === $player['provider'] ) { + $thumbnail = 'videoseries' === $player['id'] ? '' : 'https://i.ytimg.com/vi/' . $player['id'] . '/hqdefault.jpg'; + } else { + $metadata = $this->vimeo_metadata( $source, $player['id'] ); + $thumbnail = $metadata['thumbnail_url'] ?? ''; + } + } + if ( ! $has_title && isset( $metadata['title'] ) && '' !== trim( $metadata['title'] ) ) { + $title = $metadata['title']; + } + $language = get_bloginfo( 'language' ); + $context = array( + 'media_embed' => array( + 'player_url' => $this->set_parameter( $player_url, 'autoplay' ), + 'title' => $title, + 'provider' => 'youtube' === $player['provider'] ? 'YouTube' : 'Vimeo', + 'thumbnail_url' => $thumbnail, + 'language_code' => '' !== $language ? $language : 'en', + 'language_direction' => is_rtl() ? 'rtl' : 'ltr', + 'play_label' => __( 'Play video', 'emulsify' ), + ), + ); + $document = \Timber\Timber::compile( '@templates/partials/oembed-poster.twig', $context ); + if ( ! is_string( $document ) || '' === trim( $document ) ) { + throw new \UnexpectedValueException( 'The media embed poster template must render a non-empty HTML document.' ); + } + // Without src, browsers fall back to about:blank even without srcdoc support. + $processor->remove_attribute( 'src' ); + $processor->set_attribute( 'srcdoc', $this->srcdoc_value( $document ) ); + if ( ! $has_title ) { + $processor->set_attribute( 'title', $title ); + } + } catch ( \Throwable $exception ) { + _doing_it_wrong( __METHOD__, 'The media embed poster could not render. Check Timber and the child poster template.', '2.1.0' ); + if ( defined( 'WP_DEBUG' ) && WP_DEBUG ) { + throw $exception; + } + return '<a href="' . esc_url( $url ) . '">' . esc_html( $title ) . '</a>'; + } + } + $this->player_permissions( $processor ); + return $processor->get_updated_html(); + } + + /** + * Accepts positive integers and digit-only strings within PHP's integer range. + * + * @param mixed $post_id Public filter input. + * @return int|null Positive post ID, otherwise null. + */ + private function normalize_post_id( $post_id ): ?int { + if ( is_string( $post_id ) ) { + $post_id = ctype_digit( $post_id ) ? filter_var( ltrim( $post_id, '0' ), FILTER_VALIDATE_INT ) : null; + } + return is_int( $post_id ) && $post_id > 0 ? $post_id : null; + } + + /** + * Resolves options for rendering or a provider metadata response. + * + * @param string $url Original embed URL. + * @param array $attr Embed attributes. + * @param int|null $post_id Positive post ID, or null outside a post. + * @return array Media options. + */ + private function options( string $url, array $attr = array(), ?int $post_id = null ): array { + $options = array( + 'privacy_mode' => false, + 'click_to_load' => false, + 'poster' => 'provider', + ); + /** + * Filters opt-in media embed behavior without changing cached provider HTML. + * + * @param array $options Media options: privacy_mode, click_to_load, poster. + * @param string $url Original embed URL. + * @param array $attr Embed attributes. + * @param int|null $post_id Positive post ID, or null outside a post. + */ + $filtered = apply_filters( 'emulsify_theme_media_embed_options', $options, $url, $attr, $post_id ); + if ( is_array( $filtered ) ) { + $options = array_merge( $options, $filtered ); + } + return $options; + } + + /** + * Preserves nested document entities across old and new HTML API escaping. + * + * WordPress 6.8 uses esc_attr(), which avoids double-encoding. Newer releases + * correctly escape every ampersand. Probe once rather than assuming a version + * so backports retain the same safe, exactly-once outer attribute boundary. + * + * @param string $document Twig-rendered HTML document. + * @return string Value for the srcdoc setter. + */ + private function srcdoc_value( string $document ): string { + static $escapes_entities = null; + if ( null === $escapes_entities ) { + $probe = new \WP_HTML_Tag_Processor( '<iframe></iframe>' ); + $probe->next_tag(); + $probe->set_attribute( 'srcdoc', '&' ); + $reader = new \WP_HTML_Tag_Processor( $probe->get_updated_html() ); + $reader->next_tag(); + $escapes_entities = '&' === $reader->get_attribute( 'srcdoc' ); + } + return $escapes_entities ? $document : strtr( $document, array( '&' => '&' ) ); + } + + /** + * Saves metadata from WordPress' own provider fetch; no extra request is made. + * + * @param mixed $html Provider HTML; non-strings pass through unchanged. + * @param mixed $data Provider oEmbed data. + * @param mixed $url Original embed URL, normalized to a string. + * @return mixed Unchanged provider HTML for WordPress' cache. + */ + public function cache_oembed_data( $html, $data, $url ) { + if ( ! is_string( $html ) ) { + return $html; + } + $options = $this->options( is_string( $url ) ? $url : '' ); + if ( ! $options['click_to_load'] || 'provider' !== $options['poster'] ) { + return $html; + } + $processor = $this->player_iframe( $html ); + $source = null !== $processor ? $processor->get_attribute( 'src' ) : null; + $player = is_string( $source ) ? $this->player( $source ) : null; + if ( null !== $player && 'vimeo' === $player['provider'] && is_object( $data ) ) { + $canonical = $this->vimeo_url( $source, $player['id'] ); + if ( '' !== $canonical ) { + $this->save_metadata( $canonical, $data ); + } + } + return $html; + } + + /** + * Refreshes Vimeo metadata on WP-Cron, never on the content-rendering path. + * + * @param string $url Validated canonical Vimeo URL. + * @return void + */ + public function refresh_vimeo_poster( string $url ): void { + if ( 1 !== preg_match( '#^https://vimeo\.com/[0-9]+(?:/[A-Za-z0-9]+)?$#D', $url ) ) { + return; + } + $key = self::BACKOFF_PREFIX . md5( $url ); + if ( false !== get_transient( $key ) ) { + return; + } + // Back off failures and overlapping requests without discarding valid data. + set_transient( $key, true, HOUR_IN_SECONDS ); + $data = _wp_oembed_get_object()->get_data( $url, array( 'discover' => false ) ); + if ( is_object( $data ) ) { + $this->save_metadata( $url, $data ); + } + } + + /** + * Parses an entire, empty iframe without repairing malformed/compound HTML. + * + * @param string $html Provider markup. + * @return \WP_HTML_Tag_Processor|null Positioned processor or null. + */ + private function player_iframe( string $html ): ?\WP_HTML_Tag_Processor { + if ( str_contains( $html, "\0" ) ) { + return null; + } + $attribute = '[\t\n\f\r ]+([A-Za-z_:][A-Za-z0-9_.:-]*)(?:[\t\n\f\r ]*=[\t\n\f\r ]*(?:"[^"]*"|\'[^\']*\'|[^\s"\'=<>`]+))?'; + if ( 1 !== preg_match( '~\A[\t\n\f\r ]*<iframe((?:' . $attribute . ')*)[\t\n\f\r ]*>[\t\n\f\r ]*</iframe[\t\n\f\r ]*>[\t\n\f\r ]*\z~i', $html, $matches ) ) { + return null; + } + preg_match_all( '~' . $attribute . '~', $matches[1], $attributes ); + $names = array_map( 'strtolower', $attributes[1] ); + if ( count( $names ) !== count( array_unique( $names ) ) ) { + return null; + } + $processor = new \WP_HTML_Tag_Processor( $html ); + if ( ! $processor->next_tag( array( 'tag_name' => 'IFRAME' ) ) + || null !== $processor->get_attribute( 'srcdoc' ) || null !== $processor->get_attribute( 'sandbox' ) ) { + return null; + } + return $processor; + } + + /** + * Recognizes only HTTPS player hosts and provider-specific ID paths. + * + * @param string $source Player URL. + * @return array|null Provider and ID, or null. + */ + private function player( string $source ): ?array { + $parts = $this->https_url( $source ); + if ( null === $parts || ( isset( $parts['port'] ) && 443 !== $parts['port'] ) ) { + return null; + } + $host = strtolower( $parts['host'] ?? '' ); + $path = $parts['path'] ?? ''; + if ( in_array( $host, array( 'www.youtube.com', 'youtube.com', 'www.youtube-nocookie.com' ), true ) + && 1 === preg_match( '#^/embed/([A-Za-z0-9_-]+)$#D', $path, $matches ) ) { + return array( + 'provider' => 'youtube', + 'id' => $matches[1], + ); + } + if ( 'player.vimeo.com' === $host && 1 === preg_match( '#^/video/([0-9]+)$#D', $path, $matches ) ) { + return array( + 'provider' => 'vimeo', + 'id' => $matches[1], + ); + } + return null; + } + + /** + * Validates HTTPS URLs before parsing provider paths or trusting thumbnails. + * + * @param string $url Candidate URL. + * @return array|null Parsed URL, or null for unsafe input. + */ + private function https_url( string $url ): ?array { + $parts = wp_parse_url( $url ); + if ( ! is_array( $parts ) || 'https' !== strtolower( $parts['scheme'] ?? '' ) || empty( $parts['host'] ) + || isset( $parts['user'] ) || isset( $parts['pass'] ) || preg_match( '/[\x00-\x20\x7f\\\\]/', $url ) ) { + return null; + } + return $parts; + } + + /** + * Replaces one query key while preserving unrelated query bytes and fragments. + * + * @param string $url Player URL. + * @param string $name Parameter name. + * @return string URL with the named parameter set to 1. + */ + private function set_parameter( string $url, string $name ): string { + $fragment = explode( '#', $url, 2 ); + $query = explode( '?', $fragment[0], 2 ); + $pairs = isset( $query[1] ) && '' !== $query[1] ? explode( '&', $query[1] ) : array(); + $replaced = false; + foreach ( $pairs as &$pair ) { + if ( rawurldecode( explode( '=', $pair, 2 )[0] ) === $name ) { + $pair = $name . '=1'; + $replaced = true; + } + } + unset( $pair ); + if ( ! $replaced ) { + $pairs[] = $name . '=1'; + } + return $query[0] . '?' . implode( '&', $pairs ) . ( isset( $fragment[1] ) ? '#' . $fragment[1] : '' ); + } + + /** + * Delegates player permissions after the srcdoc frame navigates cross-origin. + * + * @param \WP_HTML_Tag_Processor $processor Positioned iframe processor. + * @return void + */ + private function player_permissions( \WP_HTML_Tag_Processor $processor ): void { + $permissions = array( 'autoplay', 'fullscreen', 'picture-in-picture', 'encrypted-media' ); + $existing = $processor->get_attribute( 'allow' ); + $directives = array(); + $origins = "'src' https://www.youtube.com https://youtube.com https://www.youtube-nocookie.com https://player.vimeo.com"; + foreach ( explode( ';', is_string( $existing ) ? $existing : '' ) as $directive ) { + $directive = trim( $directive ); + if ( '' !== $directive && ! in_array( preg_split( '/\s+/', $directive )[0], $permissions, true ) ) { + $directives[] = 1 === count( preg_split( '/\s+/', $directive ) ) ? $directive . ' ' . $origins : $directive; + } + } + foreach ( $permissions as $permission ) { + $directives[] = $permission . ' ' . $origins; + } + $processor->set_attribute( 'allow', implode( '; ', $directives ) ); + $processor->set_attribute( 'allowfullscreen', true ); + } + + /** + * Derives a safe metadata URL, retaining an unlisted video's access hash. + * + * @param string $source Player URL. + * @param string $id Numeric video ID. + * @return string Canonical Vimeo URL, or empty for an unsupported hash. + */ + private function vimeo_url( string $source, string $id ): string { + $url = 'https://vimeo.com/' . $id; + $query = wp_parse_url( $source, PHP_URL_QUERY ); + foreach ( explode( '&', is_string( $query ) ? $query : '' ) as $pair ) { + $parts = explode( '=', $pair, 2 ); + if ( 'h' === rawurldecode( $parts[0] ) ) { + $hash = rawurldecode( $parts[1] ?? '' ); + return 1 === preg_match( '/^[A-Za-z0-9]+$/D', $hash ) ? $url . '/' . $hash : ''; + } + } + return $url; + } + + /** + * Reads cached metadata, scheduling a refresh and returning immediately on miss. + * + * @param string $source Player URL. + * @param string $id Numeric video ID. + * @return array Cached metadata or an empty array for a neutral poster. + */ + private function vimeo_metadata( string $source, string $id ): array { + $url = $this->vimeo_url( $source, $id ); + if ( '' === $url ) { + return array(); + } + $metadata = get_transient( self::METADATA_PREFIX . md5( $url ) ); + if ( is_array( $metadata ) ) { + return $metadata; + } + if ( false !== get_transient( self::BACKOFF_PREFIX . md5( $url ) ) ) { + return array(); + } + if ( ! wp_next_scheduled( 'emulsify_theme_refresh_vimeo_poster', array( $url ) ) ) { + wp_schedule_single_event( time(), 'emulsify_theme_refresh_vimeo_poster', array( $url ) ); + } + return array(); + } + + /** + * Replaces cached provider metadata only after receiving a safe thumbnail. + * + * @param string $url Canonical Vimeo URL. + * @param object $data Provider data. + * @return void + */ + private function save_metadata( string $url, object $data ): void { + $candidate = isset( $data->thumbnail_url ) && is_string( $data->thumbnail_url ) ? $data->thumbnail_url : ''; + if ( null === $this->https_url( $candidate ) ) { + return; + } + $metadata = array( + 'thumbnail_url' => $candidate, + 'title' => isset( $data->title ) && is_string( $data->title ) ? $data->title : '', + ); + set_transient( self::METADATA_PREFIX . md5( $url ), $metadata, DAY_IN_SECONDS ); + delete_transient( self::BACKOFF_PREFIX . md5( $url ) ); + } +} diff --git a/includes/Runtime/Assets.php b/includes/Runtime/Assets.php index f5280ce..387f629 100644 --- a/includes/Runtime/Assets.php +++ b/includes/Runtime/Assets.php @@ -7,6 +7,7 @@ namespace Emulsify\Theme\Runtime; +use Emulsify\Theme\Blocks\ComponentLocator; use Emulsify\Theme\Support\AssetEnqueuer; use Emulsify\Theme\Support\AssetManifest; use Emulsify\Theme\Support\AssetRecord; @@ -24,6 +25,13 @@ final class Assets { */ private $manifest; + /** + * Shared component metadata index. + * + * @var ComponentLocator + */ + private $components; + /** * Memoized raw asset file records by theme-relative directory. * @@ -34,9 +42,9 @@ final class Assets { /** * Memoized component metadata asset paths. * - * @var array + * @var array|null */ - private $component_asset_paths = array(); + private $component_asset_paths; /** * Memoized manifest-scoped component asset paths. @@ -48,10 +56,12 @@ final class Assets { /** * Constructor. * - * @param AssetManifest|null $manifest Asset manifest reader. + * @param AssetManifest|null $manifest Asset manifest reader. + * @param ComponentLocator|null $components Shared component metadata index. */ - public function __construct( ?AssetManifest $manifest = null ) { - $this->manifest = $manifest ?? new AssetManifest(); + public function __construct( ?AssetManifest $manifest = null, ?ComponentLocator $components = null ) { + $this->manifest = $manifest ?? new AssetManifest(); + $this->components = $components ?? new ComponentLocator(); } /** @@ -181,8 +191,7 @@ private function manifest_scope( string $directory ): ?string { * @return array Built asset records. */ private function scanned_asset_files( string $directory, array $extensions ): array { - $assets = array(); - $seen = array(); + $files = array(); foreach ( $this->raw_asset_file_records( $directory ) as $file ) { if ( ! $this->extension_allowed( $file, $extensions ) ) { @@ -204,24 +213,10 @@ private function scanned_asset_files( string $directory, array $extensions ): ar continue; } - if ( isset( $seen[ $relative ] ) ) { - // Discovery roots are child-first. Once a relative path is seen, - // later parent files with the same name are intentional fallbacks - // and should not be enqueued twice. - continue; - } - - $seen[ $relative ] = true; - $assets[] = array( - 'path' => $file['path'], - 'priority' => $file['priority'], - 'relative' => $relative, - 'uri' => $file['root_uri'] . '/' . $relative, - 'version' => $this->version( $file['path'] ), - ); + $files[] = $file; } - return FileDiscovery::sort_by_priority_and_relative( $assets ); + return AssetRecord::from_discovered_files( $files ); } /** @@ -234,7 +229,9 @@ private function raw_asset_file_records( string $directory ): array { $key = trim( $directory, '/\\' ); if ( ! array_key_exists( $key, $this->asset_file_records ) ) { - $this->asset_file_records[ $key ] = FileDiscovery::file_records( $this->asset_roots( $directory ), array( 'css', 'js' ) ); + // Metadata in asset-only filtered roots belongs to this same scan, too. + $extensions = 'dist/components' === $key ? array( 'css', 'js', 'json' ) : array( 'css', 'js' ); + $this->asset_file_records[ $key ] = FileDiscovery::file_records( $this->asset_roots( $directory ), $extensions ); } return $this->asset_file_records[ $key ]; @@ -290,8 +287,6 @@ private function normalize_extensions( array $extensions ): array { * @return array Asset root records. */ private function asset_roots( string $directory ): array { - $directories = FileDiscovery::theme_roots( $directory, true ); - /** * Filters built asset directories before files are discovered. * @@ -302,18 +297,7 @@ private function asset_roots( string $directory ): array { * @param array $directories Built asset directory records. * @param string $directory Theme-relative asset directory being scanned. */ - $filtered = apply_filters( 'emulsify_theme_asset_directories', $directories, $directory ); - - if ( is_array( $filtered ) ) { - $directories = $filtered; - } - - return FileDiscovery::normalize_roots( - $directories, - array( - 'require_uri' => true, - ) - ); + return FileDiscovery::filtered_theme_roots( $directory, 'emulsify_theme_asset_directories' ); } /** @@ -348,11 +332,11 @@ private function is_scoped_component_asset( string $directory, array $file ): bo return true; } - $component_dir = dirname( (string) $file['path'] ); - $relative = FileDiscovery::relative_path( $component_dir, (string) $file['path'] ); - $asset_paths = $this->component_asset_paths( $component_dir ); + $asset_paths = $this->component_asset_paths(); + $path = (string) $file['path']; + $real = realpath( $path ); - return isset( $asset_paths[ $relative ] ); + return isset( $asset_paths[ false === $real ? $path : $real ] ); } /** @@ -371,25 +355,30 @@ private function manifest_component_asset_paths(): array { } /** - * Gets declared component metadata asset paths for a component directory. + * Gets declared metadata asset paths from the shared component file index. + * + * Metadata-only components are included even when they cannot register a + * Twig block. Their declared editor files must never become global assets. * - * @param string $component_dir Absolute component directory path. - * @return array Declared asset paths keyed by relative path. + * @return array Declared asset paths keyed by absolute path. */ - private function component_asset_paths( string $component_dir ): array { - if ( isset( $this->component_asset_paths[ $component_dir ] ) ) { - return $this->component_asset_paths[ $component_dir ]; + private function component_asset_paths(): array { + if ( is_array( $this->component_asset_paths ) ) { + return $this->component_asset_paths; } $paths = array(); - $metadata_files = glob( rtrim( $component_dir, '/\\' ) . '/*.component.json' ); + $metadata_files = $this->components->component_metadata_files(); - if ( ! is_array( $metadata_files ) ) { - $this->component_asset_paths[ $component_dir ] = $paths; - return $paths; + // Preserve metadata scoping for roots added only to the asset directory + // filter, without walking those roots a second time. + foreach ( $this->raw_asset_file_records( 'dist/components' ) as $file ) { + if ( preg_match( '/\.component\.json$/', basename( $file['path'] ) ) ) { + $metadata_files[] = $file['path']; + } } - foreach ( $metadata_files as $metadata_file ) { + foreach ( array_unique( $metadata_files ) as $metadata_file ) { $contents = is_readable( $metadata_file ) ? file_get_contents( $metadata_file ) : false; if ( ! is_string( $contents ) ) { @@ -403,11 +392,13 @@ private function component_asset_paths( string $component_dir ): array { } foreach ( $this->metadata_asset_paths( $metadata['assets'] ) as $path ) { - $paths[ $path ] = true; + $absolute = dirname( $metadata_file ) . '/' . $path; + $real = realpath( $absolute ); + $paths[ false === $real ? $absolute : $real ] = true; } } - $this->component_asset_paths[ $component_dir ] = $paths; + $this->component_asset_paths = $paths; return $paths; } @@ -455,16 +446,4 @@ private function metadata_asset_path( $entry ): string { return AssetRecord::entry_path( $entry ); } - - /** - * Gets a filemtime-based asset version. - * - * @param string $path Absolute file path. - * @return string|null Asset version. - */ - private function version( string $path ): ?string { - $modified = filemtime( $path ); - - return false === $modified ? null : (string) $modified; - } } diff --git a/includes/Runtime/Context.php b/includes/Runtime/Context.php index e90d59a..458a219 100644 --- a/includes/Runtime/Context.php +++ b/includes/Runtime/Context.php @@ -7,18 +7,36 @@ namespace Emulsify\Theme\Runtime; +use Emulsify\Theme\Support\LogoutUrl; + /** * Timber context integration. */ final class Context { /** - * Registers context filters. + * Registers context and protected-content filters. * * @return void */ public function register(): void { add_filter( 'timber/context', array( $this, 'add' ) ); + // Timber otherwise returns protected content instead of WordPress's form. + add_filter( 'timber/post/content/show_password_form_for_protected', '__return_true' ); + add_filter( 'timber/post/content/password_form', array( $this, 'protect_password_form' ), PHP_INT_MAX ); + } + + /** + * Keeps hidden password forms from exposing content through Timber. + * + * Timber treats an empty form as permission to continue to post content. + * A non-empty space preserves a plugin's hidden form without that fallback. + * + * @param mixed $form Filtered WordPress password form. + * @return string Form markup or an invisible, non-empty placeholder. + */ + public function protect_password_form( $form ): string { + return is_string( $form ) && $form ? $form : ' '; } /** @@ -34,11 +52,13 @@ public function add( array $context ): array { $context['site'] = new \Timber\Site(); } + $body_class = implode( ' ', get_body_class() ); + $context['theme'] = $this->theme(); $context['menu'] = $this->menu(); $context['post'] = $context['post'] ?? $this->post(); - $context['wp'] = $this->wordpress_helpers(); - $context['body_class'] = $context['body_class'] ?? implode( ' ', get_body_class() ); + $context['wp'] = $this->wordpress_helpers( $body_class ); + $context['body_class'] = $context['body_class'] ?? $body_class; /** * Filters global Timber context values added by the parent theme. @@ -118,12 +138,13 @@ private function post() { /** * Provides common WordPress values to Twig templates. * + * @param string $body_class Native WordPress body classes. * @return array WordPress helper values. */ - private function wordpress_helpers(): array { + private function wordpress_helpers( string $body_class ): array { return array( 'ajax_url' => admin_url( 'admin-ajax.php' ), - 'body_class' => implode( ' ', get_body_class() ), + 'body_class' => $body_class, 'home_url' => home_url( '/' ), 'is_404' => is_404(), 'is_archive' => is_archive(), @@ -135,8 +156,8 @@ private function wordpress_helpers(): array { 'is_singular' => is_singular(), 'is_user_logged_in' => is_user_logged_in(), 'login_url' => wp_login_url(), - 'logout_url' => wp_logout_url(), - 'rest_url' => function_exists( 'rest_url' ) ? rest_url() : '', + 'logout_url' => new LogoutUrl(), + 'rest_url' => rest_url(), 'search_query' => get_search_query(), 'site_url' => site_url( '/' ), 'stylesheet_directory_uri' => get_stylesheet_directory_uri(), diff --git a/includes/Runtime/MissingTimber.php b/includes/Runtime/MissingTimber.php index cac818f..a84b7a6 100644 --- a/includes/Runtime/MissingTimber.php +++ b/includes/Runtime/MissingTimber.php @@ -44,7 +44,11 @@ public function admin_notice(): void { * @return void */ public function runtime_error(): void { - if ( is_admin() || $this->is_ajax_request() || $this->is_json_request() ) { + if ( is_admin() || wp_doing_ajax() || wp_is_json_request() ) { + return; + } + + if ( is_robots() || is_favicon() || is_feed() || is_trackback() || get_query_var( 'sitemap' ) || get_query_var( 'sitemap-stylesheet' ) ) { return; } @@ -69,28 +73,4 @@ public function runtime_error(): void { private function message(): string { return __( 'Emulsify requires Timber to render WordPress templates. Install Timber with Composer or activate the Timber plugin.', 'emulsify' ); } - - /** - * Checks whether the current request is AJAX. - * - * @return bool TRUE for AJAX requests. - */ - private function is_ajax_request(): bool { - if ( function_exists( 'wp_doing_ajax' ) ) { - return wp_doing_ajax(); - } - - $doing_ajax = defined( 'DOING_AJAX' ) ? constant( 'DOING_AJAX' ) : false; - - return true === $doing_ajax; - } - - /** - * Checks whether the current request is JSON. - * - * @return bool TRUE for JSON requests. - */ - private function is_json_request(): bool { - return function_exists( 'wp_is_json_request' ) && wp_is_json_request(); - } } diff --git a/includes/Runtime/Twig.php b/includes/Runtime/Twig.php index fb9d9a7..3676ae5 100644 --- a/includes/Runtime/Twig.php +++ b/includes/Runtime/Twig.php @@ -30,6 +30,20 @@ public function register(): void { add_filter( 'timber/twig', array( $this, 'extensions' ) ); } + /** + * Clears resolver snapshots before a persistent worker's next job. + * + * Rebuild the Twig loader/environment too when its own compiled-template or + * namespace caches need refreshing. No persistent discovery cache is changed. + * + * @return void + */ + public static function clear_request_cache(): void { + ProjectComponentLoader::clear_request_cache(); + ProjectConfig::clear_request_cache(); + clearstatcache( true ); + } + /** * Enables HTML autoescaping for every Timber render path. * @@ -57,6 +71,8 @@ public function loader_paths( $loader ) { return $loader; } + $structures = $this->project_structure_namespaces(); + $components = $this->component_root_records( $structures ); $namespaces = array_merge( array( array( @@ -72,27 +88,13 @@ public function loader_paths( $loader ) { 'path' => get_template_directory() . '/templates', ), ), - $this->project_structure_namespaces(), - array( - // @components remains a compatibility namespace for component - // systems and existing projects that have not moved to - // project_machine_name:component references. - array( - 'namespace' => 'components', - 'path' => get_stylesheet_directory() . '/src/components', - ), - array( - 'namespace' => 'components', - 'path' => get_stylesheet_directory() . '/components', - ), - array( + array_filter( $structures, static fn( array $record ): bool => 'components' !== $record['namespace'] ), + array_map( + static fn( array $record ): array => array( 'namespace' => 'components', - 'path' => get_template_directory() . '/src/components', - ), - array( - 'namespace' => 'components', - 'path' => get_template_directory() . '/components', + 'path' => $record['path'], ), + $components ) ); @@ -129,16 +131,32 @@ public function loader_paths( $loader ) { * @return array Updated Timber functions. */ public function functions( array $functions ): array { + // Timber injects context even when Twig supplies no arguments. Pad that + // case so it cannot be mistaken for the direct PHP single-argument form. $functions['bem'] = array( - 'callable' => array( $this, 'bem' ), - 'needs_context' => true, - 'is_safe' => array( 'html' ), + 'callable' => function ( array $context, ...$arguments ): AttributeBag { + if ( empty( $arguments ) ) { + $arguments[] = ''; + } + return $this->bem( $context, ...$arguments ); + }, + 'options' => array( + 'needs_context' => true, + 'is_safe' => array( 'html' ), + ), ); $functions['add_attributes'] = array( - 'callable' => array( $this, 'add_attributes' ), - 'needs_context' => true, - 'is_safe' => array( 'html' ), + 'callable' => function ( array $context, ...$arguments ): AttributeBag { + if ( empty( $arguments ) ) { + $arguments[] = array(); + } + return $this->add_attributes( $context, ...$arguments ); + }, + 'options' => array( + 'needs_context' => true, + 'is_safe' => array( 'html' ), + ), ); return $functions; @@ -246,14 +264,15 @@ private function project_structure_namespaces(): array { $records = array(); $theme_dir = rtrim( get_stylesheet_directory(), '/\\' ); - foreach ( ProjectConfig::structure_implementations() as $implementation ) { - if ( ! is_array( $implementation ) || empty( $implementation['name'] ) || empty( $implementation['directory'] ) ) { + foreach ( array_values( ProjectConfig::structure_implementations() ) as $index => $implementation ) { + if ( ! is_array( $implementation ) || empty( $implementation['directory'] ) || ! is_string( $implementation['directory'] ) ) { continue; } - $namespace = ltrim( (string) $implementation['name'], '@' ); + $namespace = isset( $implementation['name'] ) && is_string( $implementation['name'] ) ? strtolower( trim( $implementation['name'] ) ) : ''; + $namespace = '' !== $namespace ? $namespace : 'structure-' . ( $index + 1 ); - if ( 1 !== preg_match( '/^[A-Za-z0-9_-]+$/', $namespace ) ) { + if ( 1 !== preg_match( '/^[A-Za-z0-9_-]+$/', $namespace ) || in_array( $namespace, array_column( $records, 'namespace' ), true ) ) { continue; } @@ -285,10 +304,6 @@ private function with_project_component_loader( $loader ) { $machine_name = ProjectConfig::machine_name(); - if ( '' === $machine_name ) { - return $loader; - } - $roots = $this->project_component_roots( $machine_name, $loader ); if ( empty( $roots ) ) { @@ -308,17 +323,18 @@ private function can_wrap_twig_loader( $loader ): bool { return interface_exists( '\Twig\Loader\LoaderInterface' ) && class_exists( '\Twig\Source' ) && class_exists( '\Twig\Error\LoaderError' ) - && is_a( $loader, '\Twig\Loader\LoaderInterface' ); + && is_a( $loader, '\Twig\Loader\LoaderInterface' ) + && method_exists( $loader, 'getNamespaces' ) + && method_exists( $loader, 'getPaths' ); } /** - * Gets project component root paths in child-first order. + * Selects Core's configured child root while retaining WordPress inheritance. * - * @param string $machine_name Active project machine name. - * @param mixed $loader Timber loader. - * @return array Component root paths. + * @param array $structures Safe structure namespace records. + * @return array Child-first root records. */ - private function project_component_roots( string $machine_name, $loader ): array { + private function component_root_records( array $structures ): array { $roots = array( array( 'path' => get_stylesheet_directory() . '/src/components', @@ -337,12 +353,46 @@ private function project_component_roots( string $machine_name, $loader ): array 'source' => 'parent', ), ); + if ( ! empty( $structures ) ) { + $components = array_values( array_filter( $structures, static fn( array $record ): bool => 'components' === $record['namespace'] ) ); + $selected = $components[0] ?? $structures[0]; + $roots = array_merge( + array( + array( + 'path' => $selected['path'], + 'source' => 'child', + ), + ), + array_slice( $roots, 2 ) + ); + } + return $roots; + } + + /** + * Gets project component root paths in child-first order. + * + * @param string $machine_name Active project machine name. + * @param mixed $loader Timber loader. + * @return array Component root paths. + */ + private function project_component_roots( string $machine_name, $loader ): array { + $roots = array(); + $child = rtrim( get_stylesheet_directory(), '/\\' ) . '/'; + $parent = rtrim( get_template_directory(), '/\\' ) . '/'; + foreach ( $loader->getPaths( 'components' ) as $path ) { + $source = str_starts_with( $path, $child ) ? 'child' : ( str_starts_with( $path, $parent ) ? 'parent' : 'filtered' ); + $roots[] = array( + 'path' => $path, + 'source' => $source, + ); + } /** - * Filters roots used for machineName:component Twig references. + * Filters roots used for explicit component Twig references. * * Roots can be path strings or arrays with a path key. The default order - * mirrors @components: active child paths first, then parent paths. + * uses the filtered @components paths: active child first, then parent. * * @param array $roots Project component root records. * @param string $machine_name Active project machine name. diff --git a/includes/Support/AssetEnqueuer.php b/includes/Support/AssetEnqueuer.php index 6cd4466..3e51b0b 100644 --- a/includes/Support/AssetEnqueuer.php +++ b/includes/Support/AssetEnqueuer.php @@ -72,7 +72,7 @@ public static function enqueue_script( string $prefix, array $record ): void { $handle = self::handle( $prefix, $record ); - if ( self::is_module_script( $record ) && function_exists( 'wp_enqueue_script_module' ) ) { + if ( self::is_module_script( $record ) ) { wp_enqueue_script_module( $handle, (string) $record['uri'], diff --git a/includes/Support/AssetManifest.php b/includes/Support/AssetManifest.php index fa50f17..a7c7b9e 100644 --- a/includes/Support/AssetManifest.php +++ b/includes/Support/AssetManifest.php @@ -495,23 +495,7 @@ private function debug_log( string $message ): void { * @return array Manifest file candidates. */ private function manifest_candidates(): array { - $relative_path = self::DEFAULT_PATH; - - /** - * Filters the theme-relative asset manifest path. - * - * Return an empty value to disable manifest loading and always use the - * recursive scanner fallback. - * - * @param string $relative_path Theme-relative manifest path. - */ - $filtered = apply_filters( 'emulsify_theme_asset_manifest_path', $relative_path ); - - if ( ! is_scalar( $filtered ) ) { - return array(); - } - - $relative_path = AssetRecord::normalize_relative_path( (string) $filtered ); + $relative_path = self::relative_path(); if ( '' === $relative_path ) { return array(); @@ -542,6 +526,25 @@ private function manifest_candidates(): array { return $candidates; } + /** + * Gets the filtered theme-relative manifest path for assets and cache keys. + * + * @return string Manifest path, or empty string when disabled. + */ + public static function relative_path(): string { + /** + * Filters the theme-relative asset manifest path. + * + * Return an empty value to disable manifest loading and always use the + * recursive scanner fallback. + * + * @param string $relative_path Theme-relative manifest path. + */ + $filtered = apply_filters( 'emulsify_theme_asset_manifest_path', self::DEFAULT_PATH ); + + return is_scalar( $filtered ) ? AssetRecord::normalize_relative_path( (string) $filtered ) : ''; + } + /** * Builds a manifest candidate record. * diff --git a/includes/Support/AssetRecord.php b/includes/Support/AssetRecord.php index d53efc9..616284f 100644 --- a/includes/Support/AssetRecord.php +++ b/includes/Support/AssetRecord.php @@ -12,6 +12,36 @@ */ final class AssetRecord { + /** + * Converts discovered files to child-first, ordered asset records. + * + * @param array $files Discovered files, with service exclusions already applied. + * @return array Built asset records. + */ + public static function from_discovered_files( array $files ): array { + $assets = array(); + $seen = array(); + + foreach ( $files as $file ) { + $relative = $file['relative']; + + if ( isset( $seen[ $relative ] ) ) { + continue; + } + + $seen[ $relative ] = true; + $assets[] = array( + 'path' => $file['path'], + 'priority' => $file['priority'], + 'relative' => $relative, + 'uri' => $file['root_uri'] . '/' . $relative, + 'version' => self::entry_version( array(), $file['path'] ), + ); + } + + return FileDiscovery::sort_by_priority_and_relative( $assets ); + } + /** * Gets an asset entry path. * diff --git a/includes/Support/AttributeBag.php b/includes/Support/AttributeBag.php index 68b0ead..0699454 100644 --- a/includes/Support/AttributeBag.php +++ b/includes/Support/AttributeBag.php @@ -89,7 +89,7 @@ public function set( string $name, $value ): self { return $this; } - if ( 'class' === $attribute_name ) { + if ( 'class' === strtolower( $attribute_name ) ) { $class_string = is_string( $value ) ? self::parseClassAttributeString( $value ) : null; // Support legacy helper calls that pass class="foo bar" while storing // classes internally as tokens for safe merging and deduplication. @@ -103,6 +103,12 @@ public function set( string $name, $value ): self { return $this; } + // Use WordPress's URI attribute policy, also covering SVG links. + if ( true !== $normalized_value && in_array( strtolower( $attribute_name ), array_merge( wp_kses_uri_attributes(), array( 'xlink:href' ) ), true ) ) { + $url = is_array( $normalized_value ) ? implode( ' ', $normalized_value ) : $normalized_value; + $normalized_value = wp_kses_bad_protocol( $url, wp_allowed_protocols() ); + } + $this->attributes[ $attribute_name ] = $normalized_value; return $this; @@ -127,10 +133,6 @@ public function merge( $value ): self { $value = iterator_to_array( $value ); } - if ( is_object( $value ) ) { - $value = get_object_vars( $value ); - } - if ( ! is_array( $value ) ) { return $this; } @@ -355,7 +357,7 @@ private static function cleanClassToken( $value ): string { * @return string|null Class value when the string is class-only. */ private static function parseClassAttributeString( string $value ): ?string { - if ( preg_match( '/^class=(["\'])(.*?)\1$/', $value, $matches ) ) { + if ( preg_match( '/^class=(["\'])(.*?)\1$/i', $value, $matches ) ) { return $matches[2]; } @@ -369,7 +371,14 @@ private static function parseClassAttributeString( string $value ): ?string { * @return bool TRUE when safe. */ private static function isSafeAttributeName( string $name ): bool { - return 1 === preg_match( '/^[A-Za-z_:][A-Za-z0-9:_.-]*$/', $name ); + $name = strtolower( $name ); + + // Framework directives can evaluate expressions just like native handlers. + // Keep static htmx attributes, but reject its evaluation-bearing families. + return 'srcdoc' !== $name + && 0 !== strpos( $name, 'on' ) + && 1 !== preg_match( '/^(?:x-|v-|:|(?:data-)?hx-(?:on|vals$|vars$|headers$|request$|trigger$))/', $name ) + && 1 === preg_match( '/^[A-Za-z_][A-Za-z0-9:_.-]*$/', $name ); } /** diff --git a/includes/Support/FileDiscovery.php b/includes/Support/FileDiscovery.php index da2b4ef..6b4423c 100644 --- a/includes/Support/FileDiscovery.php +++ b/includes/Support/FileDiscovery.php @@ -12,6 +12,13 @@ */ final class FileDiscovery { + /** + * Roots whose discovery failures have already been reported this request. + * + * @var array<string, bool> + */ + private static array $reported_roots = array(); + /** * Builds child-first theme root candidates for a theme-relative directory. * @@ -54,6 +61,23 @@ public static function theme_roots( string $directory, bool $include_uri = false return $roots; } + /** + * Gets filtered child-first roots for publicly served theme assets. + * + * @param string $directory Theme-relative directory. + * @param string $hook Service-specific roots filter. + * @return array Normalized asset roots. + */ + public static function filtered_theme_roots( string $directory, string $hook ): array { + $roots = self::theme_roots( $directory, true ); + $filtered = apply_filters( $hook, $roots, $directory ); + + return self::normalize_roots( + is_array( $filtered ) ? $filtered : $roots, + array( 'require_uri' => true ) + ); + } + /** * Normalizes root records to readable, unique directories. * @@ -82,11 +106,15 @@ public static function normalize_roots( array $roots, array $options = array() ) false === $real || isset( $seen[ $real ] ) || ! is_dir( $candidate['path'] ) - || ! is_readable( $candidate['path'] ) ) { continue; } + if ( ! is_readable( $candidate['path'] ) ) { + self::report_unreadable_directory( $candidate['path'], $candidate['path'] ); + continue; + } + $seen[ $real ] = true; $normalized[] = $candidate; } @@ -100,18 +128,24 @@ public static function normalize_roots( array $roots, array $options = array() ) * @param array $roots Normalized root records. * @param array $extensions Allowed extensions. Empty allows all files. * @param bool $recursive Whether child directories should be scanned. + * @param bool $complete Receives whether every directory could be scanned. * @return array File records. */ - public static function file_records( array $roots, array $extensions = array(), bool $recursive = true ): array { - $records = array(); + public static function file_records( array $roots, array $extensions = array(), bool $recursive = true, bool &$complete = true ): array { + $records = array(); + $complete = true; foreach ( $roots as $root ) { if ( empty( $root['path'] ) || ! is_scalar( $root['path'] ) ) { continue; } - $path = rtrim( (string) $root['path'], '/\\' ); - $files = $recursive ? self::recursive_files( $path, $extensions ) : self::directory_files( $path, $extensions ); + $path = rtrim( (string) $root['path'], '/\\' ); + $root_complete = true; + $files = $recursive + ? self::recursive_files( $path, $extensions, $root_complete ) + : self::directory_files( $path, $extensions, $root_complete ); + $complete = $complete && $root_complete; foreach ( $files as $file ) { $record = array( @@ -138,18 +172,38 @@ public static function file_records( array $roots, array $extensions = array(), * * @param string $directory Directory to scan. * @param array $extensions Allowed extensions. Empty allows all files. + * @param bool $complete Receives whether every directory could be scanned. * @return array Absolute file paths. */ - public static function recursive_files( string $directory, array $extensions = array() ): array { + public static function recursive_files( string $directory, array $extensions = array(), bool &$complete = true ): array { $files = array(); $extensions = self::normalize_extensions( $extensions ); - $iterator = new \RecursiveIteratorIterator( - new \RecursiveDirectoryIterator( $directory, \RecursiveDirectoryIterator::SKIP_DOTS ) - ); + $pending = array( $directory ); + $complete = true; + + // Open each directory separately so a failed branch cannot hide its siblings. + while ( $pending ) { + $path = array_pop( $pending ); + + if ( ! is_dir( $path ) || ! is_readable( $path ) ) { + $complete = false; + self::report_unreadable_directory( $directory, $path ); + continue; + } + + try { + $iterator = new \FilesystemIterator( $path, \FilesystemIterator::SKIP_DOTS ); - foreach ( $iterator as $file ) { - if ( $file->isFile() && self::extension_allowed( $file, $extensions ) ) { - $files[] = $file->getPathname(); + foreach ( $iterator as $file ) { + if ( $file->isDir() && ! $file->isLink() ) { + $pending[] = $file->getPathname(); + } elseif ( $file->isFile() && self::extension_allowed( $file, $extensions ) ) { + $files[] = $file->getPathname(); + } + } + } catch ( \UnexpectedValueException $error ) { + $complete = false; + self::report_unreadable_directory( $directory, $path ); } } @@ -163,17 +217,31 @@ public static function recursive_files( string $directory, array $extensions = a * * @param string $directory Directory to scan. * @param array $extensions Allowed extensions. Empty allows all files. + * @param bool $complete Receives whether the directory could be scanned. * @return array Absolute file paths. */ - public static function directory_files( string $directory, array $extensions = array() ): array { + public static function directory_files( string $directory, array $extensions = array(), bool &$complete = true ): array { $files = array(); $extensions = self::normalize_extensions( $extensions ); - $iterator = new \FilesystemIterator( $directory, \FilesystemIterator::SKIP_DOTS ); + $complete = true; - foreach ( $iterator as $file ) { - if ( $file->isFile() && self::extension_allowed( $file, $extensions ) ) { - $files[] = $file->getPathname(); + if ( ! is_dir( $directory ) || ! is_readable( $directory ) ) { + $complete = false; + self::report_unreadable_directory( $directory, $directory ); + return $files; + } + + try { + $iterator = new \FilesystemIterator( $directory, \FilesystemIterator::SKIP_DOTS ); + + foreach ( $iterator as $file ) { + if ( $file->isFile() && self::extension_allowed( $file, $extensions ) ) { + $files[] = $file->getPathname(); + } } + } catch ( \UnexpectedValueException $error ) { + $complete = false; + self::report_unreadable_directory( $directory, $directory ); } sort( $files ); @@ -181,6 +249,28 @@ public static function directory_files( string $directory, array $extensions = a return $files; } + /** + * Reports a failed scan once per root in debug environments only. + * + * @param string $root Discovery root. + * @param string $directory Unreadable or vanished directory. + * @return void + */ + private static function report_unreadable_directory( string $root, string $directory ): void { + if ( ! defined( 'WP_DEBUG' ) || ! WP_DEBUG || isset( self::$reported_roots[ $root ] ) ) { + return; + } + + self::$reported_roots[ $root ] = true; + $message = sprintf( 'Skipping unreadable or missing discovery directory: %s (root: %s).', $directory, $root ); + + if ( function_exists( 'wp_trigger_error' ) ) { + wp_trigger_error( __METHOD__, $message, E_USER_WARNING ); + } else { + error_log( $message ); + } + } + /** * Builds a POSIX relative path. * diff --git a/includes/Support/LogoutUrl.php b/includes/Support/LogoutUrl.php new file mode 100644 index 0000000..0d10f16 --- /dev/null +++ b/includes/Support/LogoutUrl.php @@ -0,0 +1,39 @@ +<?php +/** + * Provides an on-demand WordPress logout URL. + * + * @package Emulsify + */ + +namespace Emulsify\Theme\Support; + +/** + * Keeps nonce creation out of context that never uses the URL. + */ +final class LogoutUrl implements \Stringable, \JsonSerializable { + + /** + * Computed URL, including its nonce. + * + * @var string|null + */ + private ?string $url = null; + + /** + * Gets the logout URL when requested by a template. + * + * @return string Logout URL. + */ + public function __toString(): string { + return $this->url ??= wp_logout_url(); + } + + /** + * Preserves nonce-sensitive values in Timber's output cache keys. + * + * @return string Logout URL. + */ + public function jsonSerialize(): string { + return (string) $this; + } +} diff --git a/includes/Support/ProjectConfig.php b/includes/Support/ProjectConfig.php index 83b8c8c..f374a16 100644 --- a/includes/Support/ProjectConfig.php +++ b/includes/Support/ProjectConfig.php @@ -12,27 +12,62 @@ */ final class ProjectConfig { + /** + * Decoded config keyed by canonical child theme path for this request. + * + * @var array + */ + private static $cache = array(); + + /** + * Enables immutable-request memoization, bypassing mutable CLI workers. + * + * @return bool TRUE when request-local caches can be shared. + */ + public static function request_cache_enabled(): bool { + /** + * Filters request-local component and project-config memoization. + * + * CLI batches opting in must clear caches after filesystem changes or + * between jobs. Ordinary web requests share caches without persistent IO. + * + * @param bool $enabled Whether request memoization is enabled. + */ + return (bool) apply_filters( 'emulsify_theme_twig_request_cache_enabled', 'cli' !== PHP_SAPI ); + } + + /** + * Clears decoded metadata at a logical request or worker-job boundary. + * + * @return void + */ + public static function clear_request_cache(): void { + self::$cache = array(); + } + /** * Reads active child theme Emulsify project metadata. * * @return array Project config, or an empty array when unavailable. */ public static function read(): array { - $path = get_stylesheet_directory() . '/project.emulsify.json'; - - if ( ! is_readable( $path ) ) { - return array(); + $real = realpath( get_stylesheet_directory() ); + $theme_dir = false !== $real ? $real : get_stylesheet_directory(); + $path = $theme_dir . '/project.emulsify.json'; + $cacheable = self::request_cache_enabled(); + if ( $cacheable && array_key_exists( $path, self::$cache ) ) { + return self::$cache[ $path ]; } - - $contents = file_get_contents( $path ); - - if ( false === $contents ) { - return array(); + $data = array(); + if ( is_readable( $path ) ) { + $contents = file_get_contents( $path ); + $decoded = false !== $contents ? json_decode( $contents, true ) : null; + $data = is_array( $decoded ) ? $decoded : array(); } - - $data = json_decode( $contents, true ); - - return is_array( $data ) ? $data : array(); + if ( $cacheable ) { + self::$cache[ $path ] = $data; + } + return $data; } /** diff --git a/includes/Twig/ProjectComponentLoader.php b/includes/Twig/ProjectComponentLoader.php index 8b89d40..e884027 100644 --- a/includes/Twig/ProjectComponentLoader.php +++ b/includes/Twig/ProjectComponentLoader.php @@ -1,23 +1,25 @@ <?php /** - * Resolves project machine-name component references. + * Resolves explicit component references with Emulsify Core candidate order. * * @package Emulsify */ namespace Emulsify\Theme\Twig; +use Emulsify\Theme\Support\ProjectConfig; + /** - * Wraps a Twig loader with project machine-name component support. + * Wraps a Twig loader with component aliases and grouped lookup. */ final class ProjectComponentLoader implements \Twig\Loader\LoaderInterface { /** - * Project template prefix. + * Project identity for request-local resolution caches. * * @var string */ - private $prefix; + private $machine_name; /** * Component root paths. @@ -33,12 +35,33 @@ final class ProjectComponentLoader implements \Twig\Loader\LoaderInterface { */ private $loader; + /** + * Canonical ordered roots and machine-name cache identity. + * + * @var string + */ + private $cache_key; + /** * Resolved project template cache. * * @var array */ - private $cache = array(); + private static $cache = array(); + + /** + * Breadth-first grouping directories shared by loaders for this request. + * + * @var array + */ + private static $group_directories = array(); + + /** + * Directory names excluded by Emulsify Core source discovery. + * + * @var array + */ + private const SKIP_DIRECTORIES = array( 'node_modules', '.git', '.cache', '.vite', '.out', '.coverage', 'dist' ); /** * Constructs the project component loader wrapper. @@ -48,9 +71,39 @@ final class ProjectComponentLoader implements \Twig\Loader\LoaderInterface { * @param \Twig\Loader\LoaderInterface $loader Wrapped Twig loader. */ public function __construct( string $machine_name, array $roots, \Twig\Loader\LoaderInterface $loader ) { - $this->prefix = $machine_name . ':'; - $this->roots = $roots; - $this->loader = $loader; + $this->machine_name = $machine_name; + $this->loader = $loader; + $this->set_roots( $roots ); + } + + /** + * Clears component hits, misses and groups for a new logical request. + * + * @return void + */ + public static function clear_request_cache(): void { + self::$cache = array(); + self::$group_directories = array(); + } + + /** + * Refreshes canonical roots when a later Twig filter changes components. + * + * @param array $roots Component paths in namespace order. + * @return void + */ + private function set_roots( array $roots ): void { + $this->roots = array(); + foreach ( $roots as $root ) { + $real = realpath( $root ); + if ( false !== $real && is_dir( $real ) && is_readable( $real ) ) { + $path = str_replace( '\\', '/', $real ); + if ( ! in_array( $path, $this->roots, true ) ) { + $this->roots[] = $path; + } + } + } + $this->cache_key = serialize( array( $this->machine_name, $this->roots ) ); } /** @@ -63,6 +116,9 @@ public function __construct( string $machine_name, array $roots, \Twig\Loader\Lo public function addPath( string $path, string $namespace = '__main__' ): void { if ( method_exists( $this->loader, 'addPath' ) ) { $this->loader->addPath( $path, $namespace ); + if ( 'components' === $namespace ) { + $this->set_roots( $this->getPaths( 'components' ) ); + } } } @@ -76,6 +132,9 @@ public function addPath( string $path, string $namespace = '__main__' ): void { public function prependPath( string $path, string $namespace = '__main__' ): void { if ( method_exists( $this->loader, 'prependPath' ) ) { $this->loader->prependPath( $path, $namespace ); + if ( 'components' === $namespace ) { + $this->set_roots( $this->getPaths( 'components' ) ); + } } } @@ -132,7 +191,7 @@ public function getSourceContext( string $name ): \Twig\Source { throw new \Twig\Error\LoaderError( $this->project_loader_error( $name ) ); } - return $this->loader->getSourceContext( $name ); + return $this->loader->getSourceContext( $this->delegate_name( $name ) ); } /** @@ -154,7 +213,7 @@ public function getCacheKey( string $name ): string { throw new \Twig\Error\LoaderError( $this->project_loader_error( $name ) ); } - return $this->loader->getCacheKey( $name ); + return $this->loader->getCacheKey( $this->delegate_name( $name ) ); } /** @@ -171,7 +230,7 @@ public function isFresh( string $name, int $time ): bool { if ( null !== $path ) { $modified = filemtime( $path ); - return false !== $modified && $modified <= $time; + return false !== $modified && $modified < $time; } if ( $this->is_project_reference( $name ) ) { @@ -179,7 +238,7 @@ public function isFresh( string $name, int $time ): bool { throw new \Twig\Error\LoaderError( $this->project_loader_error( $name ) ); } - return $this->loader->isFresh( $name, $time ); + return $this->loader->isFresh( $this->delegate_name( $name ), $time ); } /** @@ -193,7 +252,7 @@ public function exists( string $name ) { return null !== $this->find_project_template( $name ); } - return $this->loader->exists( $name ); + return $this->loader->exists( $this->delegate_name( $name ) ); } /** @@ -203,38 +262,189 @@ public function exists( string $name ) { * @return string|null Resolved template path. */ private function find_project_template( string $name ): ?string { - if ( array_key_exists( $name, $this->cache ) ) { - return $this->cache[ $name ]; - } - + // Namespace ownership is checked before any shared hit or miss is reused. $component = $this->project_component_name( $name ); - if ( null === $component ) { return null; } - - $parts = explode( '/', $component ); - $filename = end( $parts ) . '.twig'; + $cacheable = ProjectConfig::request_cache_enabled(); + $key = $this->cache_key . "\0" . $name; + if ( $cacheable && array_key_exists( $key, self::$cache ) ) { + return self::$cache[ $key ]; + } foreach ( $this->roots as $root ) { - // Support the single-directory component convention first, then the - // older flat component.twig form. Roots are already child-first. - foreach ( array( $component . '/' . $filename, $component . '.twig' ) as $relative ) { - $path = $root . '/' . $relative; + // Core tries a literal unregistered reference before stripping its prefix. + $path = null === $this->registered_reference( $name ) + ? $this->find_in_directory( $root, str_replace( '\\', '/', $name ), $root ) + : null; + if ( null === $path ) { + $path = $this->find_in_directory( $root, $component, $root ); + } - if ( is_file( $path ) && is_readable( $path ) ) { - $realpath = realpath( $path ); + if ( null === $path ) { + foreach ( $this->group_directories( $root ) as $directory ) { + $path = $this->find_in_directory( $directory, $component, $root ); - $this->cache[ $name ] = false !== $realpath ? $realpath : $path; + if ( null !== $path ) { + break; + } + } + } - return $this->cache[ $name ]; + if ( null !== $path ) { + if ( $cacheable ) { + self::$cache[ $key ] = $path; } + + return $path; + } + } + + if ( $cacheable ) { + self::$cache[ $key ] = null; + } + + return null; + } + + /** + * Checks Core's ordered file candidates below one base directory. + * + * @param string $directory Base directory. + * @param string $component Component-relative template name. + * @param string $root Owning component root. + * @return string|null Canonical template path. + */ + private function find_in_directory( string $directory, string $component, string $root ): ?string { + $without_twig = (string) preg_replace( '/\.twig$/i', '', $component ); + $stem = basename( $without_twig ); + $candidates = array_unique( + array( + $component, + $component . '.twig', + $component . '.html.twig', + $without_twig . '/' . $stem . '.twig', + $without_twig . '/' . $stem . '.html.twig', + ) + ); + + foreach ( $candidates as $candidate ) { + $path = $this->normalize_path( rtrim( $directory, '/' ) . '/' . $candidate ); + + if ( ! $this->is_within_root( $root, $path ) || ! is_file( $path ) || ! is_readable( $path ) ) { + continue; + } + + $real = realpath( $path ); + + if ( false !== $real && $this->is_within_root( $root, str_replace( '\\', '/', $real ) ) ) { + return $real; } } return null; } + /** + * Discovers groups in Core's breadth-first, UTF-16 sibling order. + * + * Directory symlinks are not traversed, matching Node's Dirent.isDirectory(). + * + * @param string $root Canonical component root. + * @return array Group directory paths. + */ + private function group_directories( string $root ): array { + $key = serialize( array( $this->machine_name, $root ) ); + $cacheable = ProjectConfig::request_cache_enabled(); + if ( $cacheable && array_key_exists( $key, self::$group_directories ) ) { + return self::$group_directories[ $key ]; + } + + $groups = array(); + $pending = array( $root ); + + for ( $index = 0; isset( $pending[ $index ] ); ++$index ) { + $directory = $pending[ $index ]; + + try { + $entries = new \FilesystemIterator( $directory, \FilesystemIterator::SKIP_DOTS ); + } catch ( \UnexpectedValueException $exception ) { + continue; + } + + $children = array(); + + foreach ( $entries as $entry ) { + $name = $entry->getFilename(); + + if ( $entry->isLink() || ! $entry->isDir() || in_array( $name, self::SKIP_DIRECTORIES, true ) ) { + continue; + } + + $path = str_replace( '\\', '/', $entry->getPathname() ); + $real = realpath( $path ); + + if ( false !== $real && $this->is_within_root( $root, $path ) && $this->is_within_root( $root, str_replace( '\\', '/', $real ) ) ) { + $children[ mb_convert_encoding( $name, 'UTF-16BE', 'UTF-8' ) ] = $path; + } + } + + ksort( $children, SORT_STRING ); + + foreach ( $children as $child ) { + $groups[] = $child; + $pending[] = $child; + } + } + + if ( $cacheable ) { + self::$group_directories[ $key ] = $groups; + } + + return $groups; + } + + /** + * Checks a normalized absolute path against a canonical root boundary. + * + * @param string $root Component root. + * @param string $path Candidate lexical or real path. + * @return bool TRUE when the path stays inside the root. + */ + private function is_within_root( string $root, string $path ): bool { + $prefix = rtrim( $root, '/' ) . '/'; + + return $path === $root || ( + str_starts_with( $path, $prefix ) + && ! str_starts_with( substr( $path, strlen( $prefix ) ), '..' ) + ); + } + + /** + * Resolves lexical dot segments after each candidate suffix is appended. + * + * @param string $path Absolute path with POSIX separators. + * @return string Normalized absolute path. + */ + private function normalize_path( string $path ): string { + $parts = array(); + + foreach ( explode( '/', $path ) as $part ) { + if ( '' === $part || '.' === $part ) { + continue; + } + + if ( '..' === $part ) { + array_pop( $parts ); + } else { + $parts[] = $part; + } + } + + return ( str_starts_with( $path, '/' ) ? '/' : '' ) . implode( '/', $parts ); + } + /** * Gets the safe project component name from a template reference. * @@ -246,12 +456,34 @@ private function project_component_name( string $name ): ?string { return null; } - $component = substr( $name, strlen( $this->prefix ) ); + $registered = $this->registered_reference( $name ); + if ( null !== $registered ) { + $component = $registered['path']; + } else { + preg_match( '#^(?:@[^/:]+/|@?[^/:]+:)(.+)$#D', $name, $matches ); + $component = $matches[1]; + } + $component = str_replace( '\\', '/', $component ); + + if ( '' === $component || str_contains( $name, "\0" ) || str_starts_with( $component, '/' ) || preg_match( '/^[A-Za-z]:/', $component ) ) { + return null; + } + + $depth = 0; - if ( 1 !== preg_match( '/^[A-Za-z0-9_-]+(?:\/[A-Za-z0-9_-]+)?$/', $component ) ) { - // Keep project component references intentionally shallow: - // component-name or group/component-name. Legacy deep paths are - // still available through explicit @namespace configuration. + foreach ( explode( '/', $component ) as $part ) { + if ( '..' === $part ) { + if ( 0 === $depth ) { + return null; + } + + --$depth; + } elseif ( '' !== $part && '.' !== $part ) { + ++$depth; + } + } + + if ( 0 === $depth && 1 !== preg_match( '/[^.\/]/', $component ) ) { return null; } @@ -259,13 +491,53 @@ private function project_component_name( string $name ): ?string { } /** - * Checks whether a template name starts with the project prefix. + * Checks explicit component aliases without claiming registered namespaces. * * @param string $name Template logical name. - * @return bool TRUE when the name targets this project namespace. + * @return bool TRUE when component resolution owns this reference. */ private function is_project_reference( string $name ): bool { - return 0 === strncmp( $name, $this->prefix, strlen( $this->prefix ) ); + $registered = $this->registered_reference( $name ); + if ( null !== $registered ) { + return 'components' === $registered['namespace']; + } + return ! str_starts_with( $name, '.' ) && 1 === preg_match( '#^(?:@[^/:]+/|@?[^/:]+:)(.+)$#D', $name ); + } + + /** + * Parses Core's component aliases and the wrapped loader's namespaces. + * + * @param string $name Template logical name. + * @return array|null Registered namespace and relative path. + */ + private function registered_reference( string $name ): ?array { + $namespaces = array_merge( array( 'components' ), $this->getNamespaces() ); + foreach ( array( '#^@([^/]+)/(.+)$#D', '#^([^:]+)::(.+)$#D', '#^([^:/.]+):(.+)$#D' ) as $pattern ) { + if ( 1 === preg_match( $pattern, $name, $matches ) && in_array( $matches[1], $namespaces, true ) ) { + return array( + 'namespace' => $matches[1], + 'path' => $matches[2], + ); + } + } + if ( str_starts_with( $name, 'components/' ) ) { + return array( + 'namespace' => 'components', + 'path' => substr( $name, strlen( 'components/' ) ), + ); + } + return null; + } + + /** + * Converts registered namespace aliases for Twig's native loader. + * + * @param string $name Template logical name. + * @return string Native Twig template name. + */ + private function delegate_name( string $name ): string { + $registered = $this->registered_reference( $name ); + return null !== $registered ? '@' . $registered['namespace'] . '/' . $registered['path'] : $name; } /** @@ -275,9 +547,7 @@ private function is_project_reference( string $name ): bool { * @return string Error message. */ private function project_loader_error( string $name ): string { - $component = substr( $name, strlen( $this->prefix ) ); - - if ( '' === $component || false !== strpos( $component, "\0" ) || null === $this->project_component_name( $name ) ) { + if ( null === $this->project_component_name( $name ) ) { return sprintf( 'Project component template name "%s" is invalid.', $name ); } diff --git a/index.php b/index.php index 6391409..8ae93e2 100644 --- a/index.php +++ b/index.php @@ -21,9 +21,12 @@ $templates = array( '@templates/index.twig' ); if ( is_home() ) { - // Prefer WordPress' blog/front-page Twig names before the generic index - // fallback, matching the PHP template hierarchy without duplicate files. - array_unshift( $templates, '@templates/front-page.twig', '@templates/home.twig' ); + array_unshift( $templates, '@templates/home.twig' ); +} + +if ( is_front_page() ) { + // A separate posts page is home, but only the site's front page gets this. + array_unshift( $templates, '@templates/front-page.twig' ); } $context = Timber::context(); diff --git a/package-lock.json b/package-lock.json index b6dbe7e..14094c4 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,22 +1,23 @@ { "name": "emulsify-wordpress", - "version": "2.0.0", + "version": "2.1.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "emulsify-wordpress", - "version": "2.0.0", + "version": "2.1.0", "license": "GPL-2.0-only", "devDependencies": { - "@commitlint/cli": "^21.2.1", - "@commitlint/config-conventional": "^21.2.0", + "@commitlint/cli": "^21.2.4", + "@commitlint/config-conventional": "^21.2.4", "@semantic-release/commit-analyzer": "^13.0.1", - "@semantic-release/github": "^12.0.9", + "@semantic-release/github": "^12.0.10", "@semantic-release/release-notes-generator": "^14.1.1", "husky": "^9.1.7", - "lint-staged": "^17.3.0", - "semantic-release": "^25.0.8" + "js-yaml": "4.3.2", + "lint-staged": "^17.6.0", + "semantic-release": "^25.0.9" }, "engines": { "node": ">=24.10" @@ -55,9 +56,9 @@ } }, "node_modules/@actions/http-client/node_modules/undici": { - "version": "6.27.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-6.27.0.tgz", - "integrity": "sha512-YmfV3YnEDzXRC5lZ2jWtWWHKGUm1zIt8AhesR1tens+HTNv+YZlN/dp6G727LOvMJ8xjP9Be7Y2Sdr96LDm+pg==", + "version": "6.29.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-6.29.1.tgz", + "integrity": "sha512-EvRlUt/QqAEvXdQeRMYUfwOQsfzpDztykrG2owGEE/rBOBoYv9uF39ZzsNDh4lTFHhTr2XOZjKkYgueD12ZmGA==", "dev": true, "license": "MIT", "engines": { @@ -108,18 +109,18 @@ } }, "node_modules/@commitlint/cli": { - "version": "21.2.1", - "resolved": "https://registry.npmjs.org/@commitlint/cli/-/cli-21.2.1.tgz", - "integrity": "sha512-blsZGe29hJ72VGEFVl72IVYX+1vsfINpjA9yWQA6i7OKD/McGEOXg08sKIRKjFk4JvzhV/9n0l3i6NooPLTNfg==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/cli/-/cli-21.2.4.tgz", + "integrity": "sha512-g3M/wrQdElqGH5vROIeL2QiYIxrzqUkhCgsDyDlWfKEyQdCt10OyMB28W2cJtpZ+VNGMvmaN923infr1hOfyrg==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/config-conventional": "^21.2.0", - "@commitlint/format": "^21.2.0", - "@commitlint/lint": "^21.2.0", - "@commitlint/load": "^21.2.0", - "@commitlint/read": "^21.2.1", - "@commitlint/types": "^21.2.0", + "@commitlint/config-conventional": "^21.2.4", + "@commitlint/format": "^21.2.3", + "@commitlint/lint": "^21.2.4", + "@commitlint/load": "^21.2.4", + "@commitlint/read": "^21.2.3", + "@commitlint/types": "^21.2.3", "tinyexec": "^1.0.0", "yargs": "^18.0.0" }, @@ -131,13 +132,13 @@ } }, "node_modules/@commitlint/config-conventional": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/config-conventional/-/config-conventional-21.2.0.tgz", - "integrity": "sha512-Qf8WRDVcyVd14if6VTWenebxFbKnVnbzPUJjlzjkyJGeHK2xCGd63Dr1XZzj0plXKQb9P0BfOxoc1HVeCo2BWQ==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/config-conventional/-/config-conventional-21.2.4.tgz", + "integrity": "sha512-IRldtwgNmR0SySR7wizFbhRmq45lPt6H3XCNTMyVN7jrPLgi8JlTRR6Eg1HLWUQt9P1Lh3k6eY25ilDa47EE6w==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "conventional-changelog-conventionalcommits": "^10.0.0" }, "engines": { @@ -145,13 +146,13 @@ } }, "node_modules/@commitlint/config-validator": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/config-validator/-/config-validator-21.2.0.tgz", - "integrity": "sha512-t7AzNHAKeIdo/3NRGwzpufKHsKkPHmFs/56N2Fnsh0/r0rGtnQzTxk6vnFgjaGr4hdSQKNB50/KAhR9Yk4LJKA==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/config-validator/-/config-validator-21.2.3.tgz", + "integrity": "sha512-JQ13v0GafSM4fBYX8UowSy++07Was20auq0NcTdnzSEq6/05Cq5GBUMIfKkqjzyBwC9sJFmPpKWgLLhH7cygkw==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "ajv": "^8.11.0" }, "engines": { @@ -159,13 +160,13 @@ } }, "node_modules/@commitlint/ensure": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-21.2.0.tgz", - "integrity": "sha512-76IF9vDNS13lAzEEik9eKwzt8f9hYhWiwVXZ2AnyLCz5/f511FsEQ3pw1X3/zSQpdRLQU7i5qDMVKyXi1GWjSg==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/ensure/-/ensure-21.2.4.tgz", + "integrity": "sha512-woLOLV4pBMUBLyr5+MDM3WSG1r+eb2DObkysFSDxqyDUE4c6hZUOrpebJb2f8XcP3zKGJLb8H5w2suERVGI+Ag==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "es-toolkit": "^1.46.0" }, "engines": { @@ -183,13 +184,13 @@ } }, "node_modules/@commitlint/format": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/format/-/format-21.2.0.tgz", - "integrity": "sha512-c4q64xaav2U83t7k7RyzJerBZurPer7FxUOY0RL5L/6CZijZ7K+s6HIBGIghj0ey1P2+seRX0J9XQYtDued6tg==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/format/-/format-21.2.3.tgz", + "integrity": "sha512-KKwCjXYqA8r295uhLnulDXL9yekdXmj2yp2Q0XsBPhxQ2iPuvRE8F43j7g7yexo69wTdmUQmFz15jpderluzUQ==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "picocolors": "^1.1.1" }, "engines": { @@ -197,13 +198,13 @@ } }, "node_modules/@commitlint/is-ignored": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/is-ignored/-/is-ignored-21.2.0.tgz", - "integrity": "sha512-4/eB0vBN7L88O/oC4ajAEqi7j2ZfNgxl/+11RfAV9YosejZgDXhY2C9VcHnHJhOzPLoSy5P3Mg/46kqeyJfXKw==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/is-ignored/-/is-ignored-21.2.3.tgz", + "integrity": "sha512-Ng4nRj/LBAOvc+GQu7bsFW4/fL89LvZ14OOC/ERLbUpnG6QBwWRzY/1oXGwPs3C8YHWjJObin4kLYo2YeEn70w==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "semver": "^7.6.0" }, "engines": { @@ -211,36 +212,36 @@ } }, "node_modules/@commitlint/lint": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/lint/-/lint-21.2.0.tgz", - "integrity": "sha512-ceO5dp9pLjEZ6y6qbq/uXWXDPykqqlTsyzoQ0NzecpisSJhK3kTy9qzQoPeJuWG/IMNdV1lO0RgmzqoAlSi1uw==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/lint/-/lint-21.2.4.tgz", + "integrity": "sha512-HR8SGl1oEGfi/cqyBipanVY0a9CfEzIcJjPC37t7oQedaUUngw3d5E17g5Cfr2S3p6KsZM7UOHFq5fXHLRh7DQ==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/is-ignored": "^21.2.0", - "@commitlint/parse": "^21.2.0", - "@commitlint/rules": "^21.2.0", - "@commitlint/types": "^21.2.0" + "@commitlint/is-ignored": "^21.2.3", + "@commitlint/parse": "^21.2.3", + "@commitlint/rules": "^21.2.4", + "@commitlint/types": "^21.2.3" }, "engines": { "node": ">=22.12.0" } }, "node_modules/@commitlint/load": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/load/-/load-21.2.0.tgz", - "integrity": "sha512-RjlzWQqruRwIenJEfZtq7kG97co97nKoHpflE5YnF61tDLXxHPrdWImgzw6VL6MlFyaOcVlk74eBV8ZQmc3oIA==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/load/-/load-21.2.4.tgz", + "integrity": "sha512-Gi+aAW9nL8XPgvg8kIO0gZOw1/ePvpDLkv1bm8tj0RqenhNtCzk0frtctJhl41uIAP7OSx9bgQ6HCOa9En4g2Q==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/config-validator": "^21.2.0", + "@commitlint/config-validator": "^21.2.3", "@commitlint/execute-rule": "^21.0.1", - "@commitlint/resolve-extends": "^21.2.0", - "@commitlint/types": "^21.2.0", + "@commitlint/resolve-extends": "^21.2.3", + "@commitlint/types": "^21.2.3", "cosmiconfig": "^9.0.1", - "cosmiconfig-typescript-loader": "^6.1.0", "es-toolkit": "^1.46.0", "is-plain-obj": "^4.1.0", + "jiti": "^2.6.1", "picocolors": "^1.1.1" }, "engines": { @@ -258,13 +259,13 @@ } }, "node_modules/@commitlint/parse": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/parse/-/parse-21.2.0.tgz", - "integrity": "sha512-QHWxG4d0PLTF634/AdyZ0MQS+CLn5YOuJlCFhMMlSGKFxzYGUetkHBj18xgBD+6fVzUrA2lrCdi/vlS2f/oYXg==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/parse/-/parse-21.2.3.tgz", + "integrity": "sha512-Jt61QpF1xA88damCELe8I0FlDZPSpXNc8IhN7z5kZ0EcDYPjdZ+ZHPvsSXl69r2MIlLnNKeHhOn2cmVpziFE9w==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "conventional-changelog-angular": "^9.0.0", "conventional-commits-parser": "^7.0.0" }, @@ -273,14 +274,14 @@ } }, "node_modules/@commitlint/read": { - "version": "21.2.1", - "resolved": "https://registry.npmjs.org/@commitlint/read/-/read-21.2.1.tgz", - "integrity": "sha512-hUW7EJQnNTL0vPOmVMNK4CrnrNBN0nN+JJHReFkdHO5y4iyHeEmTBwuC15OCqUTjxWo7idnH1LftfpWVIaPWIA==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/read/-/read-21.2.3.tgz", + "integrity": "sha512-szAepuLA1vTTr7fuudEg7jYyVHudf+FH+vptU91bhxE1WnE8TKrfTAi44HVllz8XpI8Pvp4GjR/iP5Nshgh+og==", "dev": true, "license": "MIT", "dependencies": { "@commitlint/top-level": "^21.2.0", - "@commitlint/types": "^21.2.0", + "@commitlint/types": "^21.2.3", "@conventional-changelog/git-client": "^3.0.0", "tinyexec": "^1.0.0" }, @@ -289,22 +290,22 @@ } }, "node_modules/@commitlint/read/node_modules/@conventional-changelog/git-client": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/@conventional-changelog/git-client/-/git-client-3.1.0.tgz", - "integrity": "sha512-Tqa/gHco2WJWa740NRjOrfKVvzIqxkZpecb8bemaQ8sKM5PXb1UK4uTyTb/1wIqNuOVaDOFxyBdhTIQZn6gdjQ==", + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/@conventional-changelog/git-client/-/git-client-3.2.0.tgz", + "integrity": "sha512-sD/E0vzpkoDz/dqM1Hhv0ihC4KBw6RXjefeO8SG1XrX+wGkMxe1pKeedkKDPCtr2JjuhbuS9aJNgOvnT8hbeBw==", "dev": true, "license": "MIT", "dependencies": { "@simple-libs/child-process-utils": "^2.0.0", "@simple-libs/stream-utils": "^2.0.0", - "semver": "^7.5.2" + "verkit": "^0.5.0" }, "engines": { "node": ">=22" }, "peerDependencies": { "conventional-commits-filter": "^6.0.1", - "conventional-commits-parser": "^7.0.1" + "conventional-commits-parser": "^7.1.3" }, "peerDependenciesMeta": { "conventional-commits-filter": { @@ -328,27 +329,15 @@ "url": "https://ko-fi.com/dangreen" } }, - "node_modules/@commitlint/read/node_modules/conventional-commits-filter": { - "version": "6.0.1", - "resolved": "https://registry.npmjs.org/conventional-commits-filter/-/conventional-commits-filter-6.0.1.tgz", - "integrity": "sha512-cs+LadpH7Kpw0M3k8wurk+sOVVDAENA0iK4OBOrkL94j5lEVYRJ4j3zd2bhY9qgzyrPqthdcYT3axzRN7AliMg==", - "dev": true, - "license": "MIT", - "optional": true, - "peer": true, - "engines": { - "node": ">=22" - } - }, "node_modules/@commitlint/resolve-extends": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/resolve-extends/-/resolve-extends-21.2.0.tgz", - "integrity": "sha512-4O/1j51+79Wth9s/MGxt/5gs0XYLDgNlYpltQfhAvLE0itusLKs9zruxbiNg1oOkmkb9L9L4USYGjEj7n87NxA==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/resolve-extends/-/resolve-extends-21.2.3.tgz", + "integrity": "sha512-bqJdmAtXgAQel+l02uIsF7rHgKgx1AGZdGBjam7uK4XW54ZAQtB6XAIUXezYprQiCcRMpBh4fHs5JodXK4mVZA==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/config-validator": "^21.2.0", - "@commitlint/types": "^21.2.0", + "@commitlint/config-validator": "^21.2.3", + "@commitlint/types": "^21.2.3", "es-toolkit": "^1.46.0", "global-directory": "^5.0.0", "resolve-from": "^5.0.0" @@ -358,16 +347,16 @@ } }, "node_modules/@commitlint/rules": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/rules/-/rules-21.2.0.tgz", - "integrity": "sha512-C2yXMNpiB8ETZKfx5JD8+ExgF8vTU1VQMKPSUUYwqKpw9oJWQBrlXBpdU038mj2WPjof7o9UzFpmTyBeGMZwZg==", + "version": "21.2.4", + "resolved": "https://registry.npmjs.org/@commitlint/rules/-/rules-21.2.4.tgz", + "integrity": "sha512-wranK/aevXs/WiW4N3orQlXY4sU2pQWjRSjN7I3TsZmP146Rr4CpsG38lpyqVcbNfMgvUVGy7ffYm7nCziTUwg==", "dev": true, "license": "MIT", "dependencies": { - "@commitlint/ensure": "^21.2.0", + "@commitlint/ensure": "^21.2.4", "@commitlint/message": "^21.2.0", "@commitlint/to-lines": "^21.0.1", - "@commitlint/types": "^21.2.0" + "@commitlint/types": "^21.2.3" }, "engines": { "node": ">=22.12.0" @@ -397,9 +386,9 @@ } }, "node_modules/@commitlint/types": { - "version": "21.2.0", - "resolved": "https://registry.npmjs.org/@commitlint/types/-/types-21.2.0.tgz", - "integrity": "sha512-7zVFCDB2reMvJH5dmbKnOQPjZEvjdJTH8jc0U/PIPU1r3/+vf5pD1HlfitV2MWsWXrvu7u39iY1lyLUPOaN0Gw==", + "version": "21.2.3", + "resolved": "https://registry.npmjs.org/@commitlint/types/-/types-21.2.3.tgz", + "integrity": "sha512-sGEA473TlCvhCGNoTBY9OXZVWdscIXdGt0dm8EpB+2MRfmt8LNh/X56P/T3nCtEB+eH5qGEa3odphSAoUxSfSQ==", "dev": true, "license": "MIT", "dependencies": { @@ -411,9 +400,9 @@ } }, "node_modules/@conventional-changelog/template": { - "version": "1.2.1", - "resolved": "https://registry.npmjs.org/@conventional-changelog/template/-/template-1.2.1.tgz", - "integrity": "sha512-TzlTVpKPjaqW6qOYjQcYUDuGsLCNsvFHVBXkYGTAnf5V37jCWrE5haKNXzz0WZUtVHjrpV76L1buANjwXMfT8w==", + "version": "1.4.0", + "resolved": "https://registry.npmjs.org/@conventional-changelog/template/-/template-1.4.0.tgz", + "integrity": "sha512-aalGyl7dbB5PArRebDIX43ZvBlXrYm9uWzGJ26t+4SzJVPsOuvfILGGbw5X4yX7i50YEmJ8zvbiWnqH/AAnZqg==", "dev": true, "license": "MIT", "engines": { @@ -486,13 +475,13 @@ "license": "MIT" }, "node_modules/@octokit/plugin-paginate-rest": { - "version": "14.0.0", - "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-14.0.0.tgz", - "integrity": "sha512-fNVRE7ufJiAA3XUrha2omTA39M6IXIc6GIZLvlbsm8QOQCYvpq/LkMNGyFlB1d8hTDzsAXa3OKtybdMAYsV/fw==", + "version": "15.0.0", + "resolved": "https://registry.npmjs.org/@octokit/plugin-paginate-rest/-/plugin-paginate-rest-15.0.0.tgz", + "integrity": "sha512-lw9A9YL5s4VPj+VEx8uMxaxQm2YTgrPDkrLEuZuu18R8TK3oPcXF4K6t52nx6xn1RcogZC9i188sAr/4XYJaQQ==", "dev": true, "license": "MIT", "dependencies": { - "@octokit/types": "^16.0.0" + "@octokit/types": "^17.0.0" }, "engines": { "node": ">= 20" @@ -501,6 +490,23 @@ "@octokit/core": ">=6" } }, + "node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/openapi-types": { + "version": "28.0.0", + "resolved": "https://registry.npmjs.org/@octokit/openapi-types/-/openapi-types-28.0.0.tgz", + "integrity": "sha512-0rFyLuyHvIj6uuZWuDslxkowFYdPXoNIkeAv4b27dzm2Tf4vGWXnPsMcxs7d65kLdMERgP3wc1AEPlqMz8e1cQ==", + "dev": true, + "license": "MIT" + }, + "node_modules/@octokit/plugin-paginate-rest/node_modules/@octokit/types": { + "version": "17.0.0", + "resolved": "https://registry.npmjs.org/@octokit/types/-/types-17.0.0.tgz", + "integrity": "sha512-ByP1v7YL5SMveFPP7+sj0/ZuWCOOg/Chs4NafOMpq6WNIM/hdGY0S7C0TCGDBWu1aGmOxmUIhMx3cO+IdwYZ1Q==", + "dev": true, + "license": "MIT", + "dependencies": { + "@octokit/openapi-types": "^28.0.0" + } + }, "node_modules/@octokit/plugin-retry": { "version": "8.1.0", "resolved": "https://registry.npmjs.org/@octokit/plugin-retry/-/plugin-retry-8.1.0.tgz", @@ -683,14 +689,14 @@ } }, "node_modules/@semantic-release/github": { - "version": "12.0.9", - "resolved": "https://registry.npmjs.org/@semantic-release/github/-/github-12.0.9.tgz", - "integrity": "sha512-ODIqb0V3QqndipryEEiaBxUQCFjvv7Oese5Dt4omMGa60YRNEW0Sx3K+zri0uac2Y6S9nOlMehciWIzvvRCTGQ==", + "version": "12.0.10", + "resolved": "https://registry.npmjs.org/@semantic-release/github/-/github-12.0.10.tgz", + "integrity": "sha512-QskygvpX8hFx9UEbqJ+C46OIhaJjsysNQ8PYJPuRDc/ek5+dh8WYGD1ofUahCcGLAOmnnwZTcmCJCEXM8XxhRw==", "dev": true, "license": "MIT", "dependencies": { "@octokit/core": "^7.0.0", - "@octokit/plugin-paginate-rest": "^14.0.0", + "@octokit/plugin-paginate-rest": "^15.0.0", "@octokit/plugin-retry": "^8.0.0", "@octokit/plugin-throttling": "^11.0.0", "@semantic-release/error": "^4.0.0", @@ -3020,17 +3026,6 @@ "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/@types/node": { - "version": "26.1.2", - "resolved": "https://registry.npmjs.org/@types/node/-/node-26.1.2.tgz", - "integrity": "sha512-Vu4a5UFA9rIIFJ7rB/Vaafh9lrCQszopTCx6KjFboXTGQbPNasehVR5TEiithSDGyd1DEiUByggTZsg8jukeIg==", - "dev": true, - "license": "MIT", - "peer": true, - "dependencies": { - "undici-types": "~8.3.0" - } - }, "node_modules/@types/normalize-package-data": { "version": "2.4.4", "resolved": "https://registry.npmjs.org/@types/normalize-package-data/-/normalize-package-data-2.4.4.tgz", @@ -3122,9 +3117,9 @@ "license": "Python-2.0" }, "node_modules/argue-cli": { - "version": "3.1.0", - "resolved": "https://registry.npmjs.org/argue-cli/-/argue-cli-3.1.0.tgz", - "integrity": "sha512-DhBpBfXL4SS2uC0N922MMajKR3CdrTG0u2or1PNYgXMsrSzViJrbtvT0nCLlLGUI0plam/ZZCs7aAauHtW9thw==", + "version": "3.2.0", + "resolved": "https://registry.npmjs.org/argue-cli/-/argue-cli-3.2.0.tgz", + "integrity": "sha512-VipTB0gXgGIFO2Rg9yEVN5wLt2AurJcZqDbgmYSwPwsykhLrQhs240/bfceev4w68lI8JshoOJIk9uW7tFzROw==", "dev": true, "license": "MIT", "engines": { @@ -3545,26 +3540,26 @@ } }, "node_modules/conventional-changelog-angular": { - "version": "9.2.1", - "resolved": "https://registry.npmjs.org/conventional-changelog-angular/-/conventional-changelog-angular-9.2.1.tgz", - "integrity": "sha512-oWSL6ZhnXbYraOFTK3PgRAQJ8fADDAEv5K6AdeyQPLvjFmhG8+ejL0jZZp/R7vTmGJaBvZEE+sE7dB4bCv7sAw==", + "version": "9.4.0", + "resolved": "https://registry.npmjs.org/conventional-changelog-angular/-/conventional-changelog-angular-9.4.0.tgz", + "integrity": "sha512-HdxRxuS8bBXVIuo4V82gvSwAXT0vYQUizrjs/izmPg5JdDstr8v8I5hduGL3iQbG+o310dUDxC4+LetuS5hu9w==", "dev": true, "license": "ISC", "dependencies": { - "@conventional-changelog/template": "^1.2.1" + "@conventional-changelog/template": "^1.4.0" }, "engines": { "node": ">=22" } }, "node_modules/conventional-changelog-conventionalcommits": { - "version": "10.2.1", - "resolved": "https://registry.npmjs.org/conventional-changelog-conventionalcommits/-/conventional-changelog-conventionalcommits-10.2.1.tgz", - "integrity": "sha512-n4Kr1HFMTf3iMbES0TMxKIcYtUUv4rKqyQQp2JwfOEfFCOfGT3Tq4mCyJ8S9/YPyWhydjfKrrvnyl+gCjA+mJQ==", + "version": "10.4.1", + "resolved": "https://registry.npmjs.org/conventional-changelog-conventionalcommits/-/conventional-changelog-conventionalcommits-10.4.1.tgz", + "integrity": "sha512-jS1LRFSbRoAr6JbhhRy1JYfNNUj5LM3+v49hRE03CgccsiYqgdVj/RTmrw4J1rylrqijHwdOlJWiJa61JHOgHg==", "dev": true, "license": "ISC", "dependencies": { - "@conventional-changelog/template": "^1.2.1" + "@conventional-changelog/template": "^1.4.0" }, "engines": { "node": ">=22" @@ -3601,9 +3596,9 @@ } }, "node_modules/conventional-commits-parser": { - "version": "7.1.2", - "resolved": "https://registry.npmjs.org/conventional-commits-parser/-/conventional-commits-parser-7.1.2.tgz", - "integrity": "sha512-O+x4N2yH+ijvqWlIyTHsXTAP+algNWgGbjY2duCe8w2vUMvUB95cLRslCPfTMQyLAKlet3bhZTdu6ozn4M+QJQ==", + "version": "7.1.3", + "resolved": "https://registry.npmjs.org/conventional-commits-parser/-/conventional-commits-parser-7.1.3.tgz", + "integrity": "sha512-Q9oWm1o9uy/oEsZQIraoFMZ4RuPD+79KgwWj6mJVP356tazolCB0piRLZ5Kz9te9p027uSEcUW+Gu44Eh+X79g==", "dev": true, "license": "MIT", "dependencies": { @@ -3677,24 +3672,6 @@ } } }, - "node_modules/cosmiconfig-typescript-loader": { - "version": "6.3.0", - "resolved": "https://registry.npmjs.org/cosmiconfig-typescript-loader/-/cosmiconfig-typescript-loader-6.3.0.tgz", - "integrity": "sha512-Akr82WH1Wfqatyiqpj8HDkO2o2KmJRu1FhKfSNJP3K4IdXwHfEyL7MOb62i1AGQVLtIQM+iCE9CGOtrfhR+mmA==", - "dev": true, - "license": "MIT", - "dependencies": { - "jiti": "2.6.1" - }, - "engines": { - "node": ">=v18" - }, - "peerDependencies": { - "@types/node": "*", - "cosmiconfig": ">=9", - "typescript": ">=5" - } - }, "node_modules/cross-spawn": { "version": "7.0.6", "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz", @@ -4009,15 +3986,16 @@ } }, "node_modules/es-toolkit": { - "version": "1.50.0", - "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.50.0.tgz", - "integrity": "sha512-OyZKhUVvEep9ITEiwHn8GKnMRQIVqoSIX7WnRbkWgJkllCujilqP2rD0u979tkl8wqyc8ICwlc1UBVv/Sl1G6w==", + "version": "1.53.0", + "resolved": "https://registry.npmjs.org/es-toolkit/-/es-toolkit-1.53.0.tgz", + "integrity": "sha512-3+AYXp9fmJ/UhHBMYj2/U+RaUouMD90SzoItyDOB2Za7W6dB7fQApFGnZPl2MF6K8/Tv1koh1JyirSx/kju6Pw==", "dev": true, "license": "MIT", "workspaces": [ "docs", "benchmarks", - "tests/types" + "tests/types", + "tests/browser-compat" ] }, "node_modules/escalade": { @@ -4051,9 +4029,9 @@ "license": "MIT" }, "node_modules/fast-uri": { - "version": "3.1.5", - "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.5.tgz", - "integrity": "sha512-gHwA1O9LDIcKunMKhObS/HimwtehO1nPUECKAu5TpKgaO19fcWEl4bliWe1jWxVFvIXztJjjQ4L8XQ1EU9f7Jw==", + "version": "3.1.9", + "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.9.tgz", + "integrity": "sha512-hS/0Wt3Ya043oKXs0sIxrMpKQITXhMLIrVAKKXi4gozGC9v7YRWVnXIZzjNPTO02M9BdxLCWqK1yRXgNziVyJQ==", "dev": true, "funding": [ { @@ -4239,13 +4217,13 @@ "license": "ISC" }, "node_modules/handlebars": { - "version": "4.7.9", - "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.9.tgz", - "integrity": "sha512-4E71E0rpOaQuJR2A3xDZ+GM1HyWYv1clR58tC8emQNeQe3RH7MAzSbat+V0wG78LQBo6m6bzSG/L4pBuCsgnUQ==", + "version": "4.7.10", + "resolved": "https://registry.npmjs.org/handlebars/-/handlebars-4.7.10.tgz", + "integrity": "sha512-P5VJMVM7qgBn6vjXMw8WG9uVI+ncf2pi72j4de4yz5ZULLj2RGqLYaKOYGsgyrViQ0tePOVlN1tDCCXXtFqXKg==", "dev": true, "license": "MIT", "dependencies": { - "minimist": "^1.2.5", + "minimist": "^1.2.8", "neo-async": "^2.6.2", "source-map": "^0.6.1", "wordwrap": "^1.0.0" @@ -4529,9 +4507,9 @@ } }, "node_modules/jiti": { - "version": "2.6.1", - "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.6.1.tgz", - "integrity": "sha512-ekilCSN1jwRvIbgeg/57YFh8qQDNbwDb9xT/qu2DAHbFFZUicIl4ygVaAvzveMhMVr3LnpSKTNnwt8PoOfmKhQ==", + "version": "2.7.0", + "resolved": "https://registry.npmjs.org/jiti/-/jiti-2.7.0.tgz", + "integrity": "sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==", "dev": true, "license": "MIT", "bin": { @@ -4546,9 +4524,9 @@ "license": "MIT" }, "node_modules/js-yaml": { - "version": "4.3.0", - "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.0.tgz", - "integrity": "sha512-1td788aAnnZ5qs7V2QIRl1owjtYpbKt749Y3xauqQgwIIGF/xXWz1wMTEBx5O3LK3lXLVuqXPdPxj2BoFHaW9Q==", + "version": "4.3.2", + "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.3.2.tgz", + "integrity": "sha512-SFNOvSJ+Dgf/9An904Yx+CgSlIPCkIpao4qo51lpee25TIRejdH3rhR4EZMGoNx3/TP3O+wzWuiTFl4sqbltzA==", "dev": true, "funding": [ { @@ -4617,15 +4595,15 @@ "license": "MIT" }, "node_modules/lint-staged": { - "version": "17.3.0", - "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-17.3.0.tgz", - "integrity": "sha512-woZS3vNe3UKqBaLPvbLOtKRY4tLANpWQhom12MGWqC8Mh1lCOO+WgSwmX2amjJAqTY9BkXYW87fCUH5H9Ph6xw==", + "version": "17.6.0", + "resolved": "https://registry.npmjs.org/lint-staged/-/lint-staged-17.6.0.tgz", + "integrity": "sha512-nOhBfYkZEwkFtNzD5pK9s9LkcWoxJ+whLzEnhqi9nl7zTB5n7tg8+9iYgMGx2Wm3VlLu8cbNj0RACzY+nWi5iQ==", "dev": true, "license": "MIT", "dependencies": { - "picomatch": "^4.0.5", + "picomatch": "^4.0.7", "string-argv": "^0.3.2", - "tinyexec": "^1.2.4" + "tinyexec": "^1.3.1" }, "bin": { "lint-staged": "bin/lint-staged.js" @@ -4637,13 +4615,13 @@ "url": "https://opencollective.com/lint-staged" }, "optionalDependencies": { - "yaml": "^2.9.0" + "yaml": "^2.9.1" } }, "node_modules/lint-staged/node_modules/picomatch": { - "version": "4.0.5", - "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.5.tgz", - "integrity": "sha512-RvwwcruNjI1ncT5xRakeyS9Lf8lcItv34KD+aif+VH9kduAyfYBipGh12274xtenIPZ119/R9BdTBa8gAwSh0A==", + "version": "4.0.7", + "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.7.tgz", + "integrity": "sha512-qcJu88Q2IWqJsDD529JKMdwGm/dvInW4HvQnRwiH9JtihJvzGOscDtHE3x1pBKeUOTysQ8kVmLnJ2kJu7yhcGA==", "dev": true, "license": "MIT", "engines": { @@ -5521,9 +5499,9 @@ "license": "MIT" }, "node_modules/semantic-release": { - "version": "25.0.8", - "resolved": "https://registry.npmjs.org/semantic-release/-/semantic-release-25.0.8.tgz", - "integrity": "sha512-w/iZ0bur36rKffXZYmIUmy068eoBY3Ij1DCCddx2JwWEM5Tg+eU9ld/E9qSInVvPASyyR2Ln/XGfQ9OZrMlhtw==", + "version": "25.0.9", + "resolved": "https://registry.npmjs.org/semantic-release/-/semantic-release-25.0.9.tgz", + "integrity": "sha512-bxve7csK0/Txr++CkfrmV+X1r4jqiSOw2WsSad9E2S68R+ZfLBwDn8IceM8WfiOmKQIHgsQc1cNA8Dzg7U75pg==", "dev": true, "license": "MIT", "dependencies": { @@ -6274,9 +6252,9 @@ } }, "node_modules/tinyexec": { - "version": "1.3.0", - "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.0.tgz", - "integrity": "sha512-QKAl9m8gWWGHV8jZcPeym6j+XULi6tOf1mT83WYJ4Lk2ytW/uwAWkrP0uFsdoYMdueVJ0qs26wZ+23xeB4ibNQ==", + "version": "1.3.1", + "resolved": "https://registry.npmjs.org/tinyexec/-/tinyexec-1.3.1.tgz", + "integrity": "sha512-GCvB3aoys96IuDFBMcTB46JOR6mdMtAToqwiW8JlWhsoh1mhHi/xn9ss/Dg7N555GiJyEt2qzoG/NHCwM6h1EA==", "dev": true, "license": "MIT", "engines": { @@ -6380,21 +6358,6 @@ "url": "https://github.com/sponsors/sindresorhus" } }, - "node_modules/typescript": { - "version": "6.0.3", - "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz", - "integrity": "sha512-y2TvuxSZPDyQakkFRPZHKFm+KKVqIisdg9/CZwm9ftvKXLP8NRWj38/ODjNbr43SsoXqNuAisEf1GdCxqWcdBw==", - "dev": true, - "license": "Apache-2.0", - "peer": true, - "bin": { - "tsc": "bin/tsc", - "tsserver": "bin/tsserver" - }, - "engines": { - "node": ">=14.17" - } - }, "node_modules/uglify-js": { "version": "3.19.3", "resolved": "https://registry.npmjs.org/uglify-js/-/uglify-js-3.19.3.tgz", @@ -6410,23 +6373,15 @@ } }, "node_modules/undici": { - "version": "7.28.0", - "resolved": "https://registry.npmjs.org/undici/-/undici-7.28.0.tgz", - "integrity": "sha512-cRZYrTDwWznlnRiPjggAGxZXanty6M8RV1ff8Wm4LWXBp7/IG8v5DnOm74DtUBp9OONpK75YlPnIjQqX0dBDtA==", + "version": "7.30.1", + "resolved": "https://registry.npmjs.org/undici/-/undici-7.30.1.tgz", + "integrity": "sha512-03KrMbjIFDWQR5RNPrSw3bd1r12JpyFQl9/yxjUbJtqkjmllqC5lFjZh6ujeuJCKr8EOQvRW872Oy/az+nLYxg==", "dev": true, "license": "MIT", "engines": { "node": ">=20.18.1" } }, - "node_modules/undici-types": { - "version": "8.3.0", - "resolved": "https://registry.npmjs.org/undici-types/-/undici-types-8.3.0.tgz", - "integrity": "sha512-j375ScV60dom+YkPFIfTLcOiPxkN/buHz5GobjLhixFuANaNs3C9l4GmrWqejgXWJ7BbJcFYpTEUkS1Ge8bpZQ==", - "dev": true, - "license": "MIT", - "peer": true - }, "node_modules/unicode-emoji-modifier-base": { "version": "1.0.0", "resolved": "https://registry.npmjs.org/unicode-emoji-modifier-base/-/unicode-emoji-modifier-base-1.0.0.tgz", @@ -6511,6 +6466,19 @@ "spdx-expression-parse": "^3.0.0" } }, + "node_modules/verkit": { + "version": "0.5.0", + "resolved": "https://registry.npmjs.org/verkit/-/verkit-0.5.0.tgz", + "integrity": "sha512-u4J1hr6Y+C/hit34GwL3eIcUf3wngT8TlYUjK7tk0jxydKLAq3sYvifjdTDA6U3KCKRcQCQDGf/srjxfZF3l7g==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18.12.0" + }, + "funding": { + "url": "https://github.com/sponsors/sxzz" + } + }, "node_modules/web-worker": { "version": "1.5.0", "resolved": "https://registry.npmjs.org/web-worker/-/web-worker-1.5.0.tgz", @@ -6598,9 +6566,9 @@ } }, "node_modules/yaml": { - "version": "2.9.0", - "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz", - "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==", + "version": "2.9.1", + "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz", + "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==", "dev": true, "license": "ISC", "optional": true, diff --git a/package.json b/package.json index 2bbf13f..811f618 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,7 @@ { "name": "emulsify-wordpress", - "version": "2.0.0", + "version": "2.1.0", + "private": true, "description": "Timber-first WordPress parent theme that generates child themes with Emulsify Core 4, Vite, Storybook, and Twig", "engines": { "node": ">=24.10" @@ -31,23 +32,34 @@ "lint:php": "vendor/bin/phpcs -q && vendor/bin/phpstan analyse --no-progress --memory-limit=1G", "lint:php:fix": "vendor/bin/phpcbf", "lint-staged": "lint-staged", - "prepare": "[ -d '.git' ] && (husky install) || true", + "prepare": "husky", "pr:check": "node .github/scripts/pr-validation.cjs", "release:check": "node .github/scripts/release-check.cjs", "test:generated-theme": "node --test .github/scripts/generated-theme-contract.test.cjs", + "test:audit-wrappers": "node --test .github/scripts/generated-audit-wrappers.test.cjs", + "test:a11y-runner": "node --test .github/scripts/a11y-runner.test.cjs", + "test:lint-wrappers": "node --test .github/scripts/lint-wrappers.test.cjs", + "test:twig-helpers": "node .github/scripts/twig-helper-contract.cjs", + "test:component-resolution": "node .github/scripts/component-resolution-contract.cjs", "smoke:acf-json": "php .github/scripts/acf-local-json-smoke.php", "smoke:asset-manifest": "php .github/scripts/asset-manifest-smoke.php", "smoke:attributes": "php .github/scripts/attribute-helper-smoke.php", "smoke:block-assets": "php .github/scripts/block-scoped-assets-smoke.php", "smoke:bootstrap-loader": "php .github/scripts/bootstrap-loader-smoke.php", + "smoke:missing-timber": "php .github/scripts/missing-timber-smoke.php", "smoke:child-theme-generator": "php .github/scripts/child-theme-generator-smoke.php", "smoke:generation-parity": "node .github/scripts/generation-parity-smoke.cjs", "smoke:component-locator": "php .github/scripts/component-locator-smoke.php", + "smoke:file-discovery": "php .github/scripts/file-discovery-smoke.php", + "smoke:component-request-cache": "php .github/scripts/component-request-cache-smoke.php", "smoke:core-block-twig": "php .github/scripts/core-block-twig-renderer-smoke.php", "smoke:editor-enhancements": "php .github/scripts/editor-enhancements-smoke.php", "smoke:editor-policy": "php .github/scripts/editor-policy-smoke.php", + "smoke:navigation": "php .github/scripts/fallback-navigation-smoke.php", + "smoke:jest-project": "node .github/scripts/jest-project-smoke.cjs", "smoke:patterns": "php .github/scripts/pattern-registry-smoke.php", "smoke:starter-init": "node .github/scripts/wordpress-starter-init-smoke.cjs", + "smoke:template-extension": "php .github/scripts/template-extension-smoke.php", "smoke:theme-filters": "php .github/scripts/theme-filters-smoke.php", "smoke:twig-autoescape": "php .github/scripts/twig-autoescape-smoke.php", "smoke:twig-switch": "php .github/scripts/twig-switch-smoke.php", @@ -56,17 +68,17 @@ "whisk:install": "npm --prefix whisk install --package-lock=false --ignore-scripts", "build:dist": "bash scripts/build-dist.sh", "publish": "node .github/scripts/semantic-release.cjs --tag-format '${version}'", - "publish-test": "node .github/scripts/semantic-release.cjs --tag-format '${version}' --dry-run --debug", - "semantic-release": "semantic-release" + "publish-test": "node .github/scripts/semantic-release.cjs --tag-format '${version}' --dry-run --debug" }, "devDependencies": { - "@commitlint/cli": "^21.2.1", - "@commitlint/config-conventional": "^21.2.0", + "@commitlint/cli": "^21.2.4", + "@commitlint/config-conventional": "^21.2.4", "@semantic-release/commit-analyzer": "^13.0.1", - "@semantic-release/github": "^12.0.9", + "@semantic-release/github": "^12.0.10", "@semantic-release/release-notes-generator": "^14.1.1", "husky": "^9.1.7", - "lint-staged": "^17.3.0", - "semantic-release": "^25.0.8" + "js-yaml": "4.3.2", + "lint-staged": "^17.6.0", + "semantic-release": "^25.0.9" } } diff --git a/page.php b/page.php index 8304c9b..e6b0a86 100644 --- a/page.php +++ b/page.php @@ -13,6 +13,14 @@ // Page rendering is intentionally thin: route data comes from Timber context, // while markup and extension points live in Twig. -$context = Timber::context(); +$context = Timber::context(); +$wp_post = $context['post'] ?? null; +$templates = array( '@templates/page.twig' ); -Timber::render( '@templates/page.twig', $context ); +if ( $wp_post && post_password_required( $wp_post->ID ) ) { + $templates = array( '@templates/single-password.twig' ); +} elseif ( is_front_page() ) { + array_unshift( $templates, '@templates/front-page.twig' ); +} + +Timber::render( $templates, $context ); diff --git a/release.config.js b/release.config.js index fee464d..024b329 100644 --- a/release.config.js +++ b/release.config.js @@ -1,4 +1,5 @@ -const { execFileSync } = require('node:child_process'); +const fs = require('node:fs'); +const path = require('node:path'); const parserOpts = { // semantic-release's default parser does not treat "feat!:" consistently @@ -10,132 +11,29 @@ const parserOpts = { noteKeywords: ['BREAKING CHANGE', 'BREAKING CHANGES', 'BREAKING-CHANGE'], }; -const expectedStableRelease = '2.0.0'; -const initialStableBaseline = '1.0.0'; -const syntheticBaselineEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE'; -const syntheticBaselineShaEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SHA'; -const syntheticBaselineSourceEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SOURCE'; - -function parseVersionParts(version) { - return String(version || '') - .split('-')[0] - .split('.') - .map((part) => Number.parseInt(part, 10)); -} - -function isAtLeastVersion(version, minimumVersion) { - const current = parseVersionParts(version); - const minimum = parseVersionParts(minimumVersion); - - if ( - current.length !== 3 || - minimum.length !== 3 || - current.some(Number.isNaN) || - minimum.some(Number.isNaN) - ) { - return false; - } - - for (let index = 0; index < current.length; index += 1) { - if (current[index] > minimum[index]) { - return true; - } - - if (current[index] < minimum[index]) { - return false; - } - } - - return true; -} - -function removeSyntheticBaseline(cwd) { - const baselineTag = process.env[syntheticBaselineEnvironment]; - const expectedSha = process.env[syntheticBaselineShaEnvironment]; - - if (baselineTag !== initialStableBaseline || !expectedSha) { - return; - } - - try { - const actualSha = execFileSync('git', ['rev-parse', '--verify', `${baselineTag}^{commit}`], { - cwd: cwd || process.cwd(), - encoding: 'utf8', - }).trim(); - - if (actualSha !== expectedSha) { - throw new Error(`${baselineTag} points to ${actualSha}, not the temporary baseline commit ${expectedSha}.`); - } - - execFileSync('git', ['tag', '--delete', baselineTag], { - cwd: cwd || process.cwd(), - stdio: 'ignore', - }); - delete process.env[syntheticBaselineEnvironment]; - delete process.env[syntheticBaselineShaEnvironment]; - } - catch (error) { - throw new Error(`Unable to remove the temporary ${baselineTag} release baseline tag before publishing.`, { - cause: error, - }); - } -} - -const expectedStableReleaseGuard = { - verifyRelease(pluginConfig, { branch, cwd, lastRelease = {}, nextRelease }) { - try { - // The 2.x release branch prepares the stable 2.0.0 baseline. After that - // baseline exists, normal semantic-release versioning can continue. - if (branch.name !== 'main' || isAtLeastVersion(lastRelease.version, expectedStableRelease)) { - return; - } - - if (nextRelease.version !== expectedStableRelease) { - const message = `Expected semantic-release to prepare ${expectedStableRelease} on main, but computed ${nextRelease.version}. Confirm stable baseline tags and breaking-change commits before publishing.`; - throw new Error(message); - } - } - finally { - // semantic-release pushes every local tag. Remove the temporary baseline - // after version calculation, regardless of whether the guard accepts it. - removeSyntheticBaseline(cwd); +const preparedReleaseGuard = { + verifyConditions(pluginConfig, { cwd = __dirname }) { + const archive = fs.statSync(path.join(cwd, 'dist-artifact/emulsify.zip'), { throwIfNoEntry: false }); + if (!archive?.isFile() || archive.size === 0) { + throw new Error('Required release asset dist-artifact/emulsify.zip is missing or empty. Run npm run build:dist and test that exact ZIP before publishing.'); } }, -}; + verifyRelease(pluginConfig, { cwd = __dirname, nextRelease }) { + const preparedVersion = JSON.parse(fs.readFileSync(path.join(cwd, 'package.json'), 'utf8')).version; -const expectedStableReleaseAnalyzer = { - analyzeCommits(pluginConfig, { branch, lastRelease = {} }) { - // The release-2.x branch is the first stable release line for the rebuilt - // parent theme. The runner temporarily exposes the latest 1.0.0 alpha as a - // local 1.0.0 baseline so semantic-release can calculate 2.0.0. - return branch.name === 'main' && !isAtLeastVersion(lastRelease.version, expectedStableRelease) - ? 'major' - : null; + if (nextRelease.version !== preparedVersion) { + throw new Error( + `Prepared package.json version ${preparedVersion}, but semantic-release computed ${nextRelease.version}. Update the release PR's package.json and all derived version files to match Conventional Commits, then rerun npm run release:check.`, + ); + } }, }; -function finalizeReleaseNotesContext(context) { - if ( - context.version === expectedStableRelease - && context.previousTag === initialStableBaseline - && process.env[syntheticBaselineSourceEnvironment]?.startsWith(`${initialStableBaseline}-`) - ) { - // The temporary baseline is never published, so do not emit a compare URL - // whose left-hand tag would not exist on GitHub. - context.linkCompare = false; - } - - return context; -} - module.exports = { - expectedStableRelease, - initialStableBaseline, tagFormat: '${version}', branches: ['main'], repositoryUrl: 'git@github.com:emulsify-ds/emulsify-wordpress.git', plugins: [ - expectedStableReleaseAnalyzer, ['@semantic-release/commit-analyzer', { preset: 'angular', parserOpts }], [ '@semantic-release/release-notes-generator', @@ -144,11 +42,10 @@ module.exports = { parserOpts, writerOpts: { commitsSort: ['subject', 'scope'], - finalizeContext: finalizeReleaseNotesContext, }, }, ], - expectedStableReleaseGuard, + preparedReleaseGuard, [ '@semantic-release/github', { diff --git a/scripts/build-dist.sh b/scripts/build-dist.sh index f0705f1..d2aede8 100755 --- a/scripts/build-dist.sh +++ b/scripts/build-dist.sh @@ -13,11 +13,33 @@ for command_name in composer git node zip; do fi done -copy_tracked_directory() { +# Resolve one immutable commit before reading any payload. Working-tree and index +# edits never become release inputs, even if HEAD moves while the build runs. +build_commit="$(git -C "${repo_root}" rev-parse --verify 'HEAD^{commit}')" + +while IFS= read -r -d '' tree_entry; do + case "${tree_entry}" in + '120000 '*) + echo "Refusing to package committed symlink: ${tree_entry#*$'\t'}" >&2 + exit 1 + ;; + esac +done < <(git -C "${repo_root}" ls-tree -r -z "${build_commit}") + +copy_committed_file() { + local relative_path="$1" + local target_path="${staging_root}/${relative_path}" + + mkdir -p "$(dirname "${target_path}")" + if ! git -C "${repo_root}" cat-file blob "${build_commit}:${relative_path}" > "${target_path}"; then + echo "Required committed file not found: ${relative_path}" >&2 + exit 1 + fi +} + +copy_committed_directory() { local relative_directory="$1" local relative_path - local source_path - local target_path local copied_files=0 while IFS= read -r -d '' relative_path; do @@ -27,15 +49,12 @@ copy_tracked_directory() { ;; esac - source_path="${repo_root}/${relative_path}" - target_path="${staging_root}/${relative_path}" - mkdir -p "$(dirname "${target_path}")" - cp "${source_path}" "${target_path}" + copy_committed_file "${relative_path}" copied_files=$((copied_files + 1)) - done < <(git -C "${repo_root}" ls-files -z -- "${relative_directory}") + done < <(git -C "${repo_root}" ls-tree -r -z --name-only "${build_commit}" -- "${relative_directory}") if (( copied_files == 0 )); then - echo "No tracked files found for required directory: ${relative_directory}" >&2 + echo "No committed files found for required directory: ${relative_directory}" >&2 exit 1 fi } @@ -54,6 +73,7 @@ mkdir -p "${staging_root}" runtime_files=( "404.php" + "AGENTS.md" "LICENSE" "README.md" "UPGRADE.md" @@ -77,36 +97,21 @@ runtime_directories=( ) for relative_path in "${runtime_files[@]}"; do - source_path="${repo_root}/${relative_path}" - if [[ ! -f "${source_path}" ]]; then - echo "Required runtime path not found: ${relative_path}" >&2 - exit 1 - fi - - cp "${source_path}" "${staging_root}/" + copy_committed_file "${relative_path}" done for relative_directory in "${runtime_directories[@]}"; do - if [[ ! -d "${repo_root}/${relative_directory}" ]]; then - echo "Required runtime directory not found: ${relative_directory}" >&2 - exit 1 - fi - - copy_tracked_directory "${relative_directory}" + copy_committed_directory "${relative_directory}" done -# Whisk is product payload for `wp emulsify`, but only its tracked generator -# source belongs in the release. This prevents ignored local dependencies, -# caches, and build output from leaking into the archive. -copy_tracked_directory "whisk" +# Whisk is product payload for `wp emulsify`, but only its committed generator +# source belongs in the release. Development output stays outside the archive. +copy_committed_directory "whisk" +# Read Git objects explicitly rather than git archive: export-ignore omits the +# lockfile from Git distributions, but Composer needs it for reproducible builds. for composer_file in composer.json composer.lock; do - if [[ ! -f "${repo_root}/${composer_file}" ]]; then - echo "Required Composer metadata not found: ${composer_file}" >&2 - exit 1 - fi - - cp "${repo_root}/${composer_file}" "${staging_root}/" + copy_committed_file "${composer_file}" done echo "Installing production Composer dependencies..." @@ -127,11 +132,15 @@ if [[ ! -f "${staging_root}/vendor/autoload.php" ]]; then fi required_release_paths=( + "AGENTS.md" "UPGRADE.md" "docs/wp-cli-child-theme-generation.md" "functions.php" "vendor/autoload.php" "whisk/README.md" + "whisk/AGENTS.md" + "whisk/.agents/skills/emulsify-wordpress-integration/SKILL.md" + "whisk/docs/wordpress-integration.md" "whisk/package.json" "whisk/project.emulsify.json" "whisk/style.css" @@ -164,11 +173,7 @@ for forbidden_path in \ done if [[ -z "${SOURCE_DATE_EPOCH:-}" ]]; then - if git -C "${repo_root}" rev-parse --is-inside-work-tree >/dev/null 2>&1; then - SOURCE_DATE_EPOCH="$(git -C "${repo_root}" log -1 --format=%ct)" - else - SOURCE_DATE_EPOCH=315532800 - fi + SOURCE_DATE_EPOCH="$(git -C "${repo_root}" show --no-show-signature -s --format=%ct "${build_commit}")" fi if [[ ! "${SOURCE_DATE_EPOCH}" =~ ^[0-9]+$ ]] || (( SOURCE_DATE_EPOCH < 315532800 )); then @@ -210,5 +215,13 @@ echo "Creating ${artifact_path}..." find emulsify -type f -print | LC_ALL=C sort | zip -X -q "${temporary_archive}" -@ ) +archive_listing="$(zip -sf "${temporary_archive}")" +for relative_path in "${required_release_paths[@]}"; do + if ! grep -Fqx " emulsify/${relative_path}" <<< "${archive_listing}"; then + echo "Required release path not found in ZIP: ${relative_path}" >&2 + exit 1 + fi +done + mv "${temporary_archive}" "${artifact_path}" echo "Built ${artifact_path}" diff --git a/style.css b/style.css index ca4b220..d3e45bb 100644 --- a/style.css +++ b/style.css @@ -3,10 +3,10 @@ * Author: Callin Mullaney & Mike Goulding * Description: Timber-first WordPress parent theme for generated child themes with Emulsify Core 4, Vite, Storybook, and Twig. * Text Domain: emulsify - * Requires at least: 6.7 - * Tested up to: 6.7 + * Requires at least: 6.8 + * Tested up to: 7.1 * Requires PHP: 8.3 - * Version: 2.0.0 + * Version: 2.1.0 * License: GPL-2.0-only * License URI: https://www.gnu.org/licenses/old-licenses/gpl-2.0.html */ diff --git a/templates/layouts/base.twig b/templates/layouts/base.twig index 6851b1b..6f17d73 100644 --- a/templates/layouts/base.twig +++ b/templates/layouts/base.twig @@ -1,5 +1,6 @@ {# Shared document shell. Keep structural WordPress hooks here so child page - templates can focus on content blocks and component composition. #} + templates can focus on content blocks and component composition. + Timber supplies language_attributes as the trusted WordPress core attribute fragment. #} {% set body_attributes = { class: body_class|default('') } %} @@ -36,7 +37,7 @@ } %} {% set menu_items = menu|default(null) ? menu.get_items : [] %} <!doctype html> -<html {{ site.language_attributes|default('') }}> +<html {{ site.language_attributes|default('')|raw }}> {% block head %} {% include '@templates/partials/head.twig' %} {% endblock %} @@ -45,11 +46,12 @@ {{ function('wp_body_open') }} <a {{ add_attributes(skip_link_attributes) }}>{{ function('__', 'Skip to content', 'emulsify') }}</a> +{% block site_header %} <header {{ add_attributes(site_header_attributes) }}> <div {{ add_attributes(site_header_inner_attributes) }}> {% block header %} <a {{ add_attributes(site_header_brand_attributes) }}> - {{ site.name|default('') }} + {{ site.name|default('')|esc_html }} </a> {% if menu_items is not empty %} @@ -63,22 +65,28 @@ {% endblock %} </div> </header> +{% endblock %} +{% block main %} <main {{ add_attributes(site_main_attributes) }}> +{% block page_title %} {% if title|default(null) %} <header {{ add_attributes(page_header_attributes) }}> - <h1 {{ add_attributes(page_header_title_attributes) }}>{{ title }}</h1> + <h1 {{ add_attributes(page_header_title_attributes) }}>{{ title|esc_html }}</h1> </header> {% endif %} +{% endblock %} {% block content %}{% endblock %} </main> +{% endblock %} + + {% do action('get_footer') %} {% block footer %} {% include '@templates/partials/footer.twig' %} {% endblock %} {{ function('wp_footer') }} - {% do action('get_footer') %} </body> </html> diff --git a/templates/page.twig b/templates/page.twig index ba11867..6e90f6a 100644 --- a/templates/page.twig +++ b/templates/page.twig @@ -20,7 +20,7 @@ {% if post|default(null) %} <article {{ add_attributes(entry_attributes) }}> <header {{ add_attributes(entry_header_attributes) }}> - <h1 {{ add_attributes(entry_title_attributes) }}>{{ post.title }}</h1> + <h1 {{ add_attributes(entry_title_attributes) }}>{{ post.title|wp_kses_post }}</h1> </header> <div {{ add_attributes(entry_content_attributes) }}> diff --git a/templates/partials/comment.twig b/templates/partials/comment.twig index c642bec..6f71193 100644 --- a/templates/partials/comment.twig +++ b/templates/partials/comment.twig @@ -21,7 +21,7 @@ <article {{ add_attributes(comment_attributes) }}> {% if comment.author.name|default(null) %} <header {{ add_attributes(comment_header_attributes) }}> - <h3 {{ add_attributes(comment_author_attributes) }}>{{ comment.author.name }}</h3> + <h3 {{ add_attributes(comment_author_attributes) }}>{{ comment.author.name|esc_html }}</h3> </header> {% endif %} diff --git a/templates/partials/footer.twig b/templates/partials/footer.twig index 4158fe2..81ecde1 100644 --- a/templates/partials/footer.twig +++ b/templates/partials/footer.twig @@ -10,6 +10,6 @@ <footer {{ add_attributes(site_footer_attributes) }}> <p {{ add_attributes(site_footer_copyright_attributes) }}> - © {{ 'now'|date('Y') }} {{ site.name|default('') }} + © {{ 'now'|date('Y') }} {{ site.name|default('')|esc_html }} </p> </footer> diff --git a/templates/partials/menu.twig b/templates/partials/menu.twig index baa0faa..f766bfa 100644 --- a/templates/partials/menu.twig +++ b/templates/partials/menu.twig @@ -17,11 +17,12 @@ class: bem('link', [], 'menu'), href: item.link|default('#'), target: item.target|default(null), - rel: item.target|default(null) ? 'noopener' : null + rel: item.target|default(null) ? 'noopener' : null, + 'aria-current': item.current|default(false) ? 'page' : null } %} <li {{ add_attributes(item_attributes) }}> <a {{ add_attributes(link_attributes) }}> - {{ item.title|default('') }} + {{ item.title|default('')|esc_html }} </a> {% if children is not empty %} diff --git a/templates/partials/oembed-poster.twig b/templates/partials/oembed-poster.twig new file mode 100644 index 0000000..cda2294 --- /dev/null +++ b/templates/partials/oembed-poster.twig @@ -0,0 +1,39 @@ +{# Standalone iframe srcdoc; see docs/media-embeds.md before overriding. #} +<!doctype html> +<html lang="{{ media_embed.language_code }}" dir="{{ media_embed.language_direction }}"> +<head> + <meta charset="utf-8"> + <meta http-equiv="Content-Security-Policy" content="script-src 'none'"> + <meta name="viewport" content="width=device-width, initial-scale=1"> + <title>{{ media_embed.title ?: media_embed.play_label }} + + + + + {% if media_embed.thumbnail_url %}{% endif %} + + {{ media_embed.play_label }}{% if media_embed.title %}: {{ media_embed.title }}{% endif %} + + +
- ', ''), + }; + const server = http.createServer((request, response) => { + response.writeHead(request.url === '/http-error' ? 500 : 200, { 'Content-Type': 'text/html; charset=utf-8' }); + response.end(pages[request.url] || clean); + }); + await new Promise((resolve, reject) => { + server.once('error', reject); + server.listen(0, '127.0.0.1', resolve); + }); + const baseUrl = `http://127.0.0.1:${server.address().port}`; + try { + const routes = Object.keys(pages).map((url) => ({ + name: url.slice(1), + url: baseUrl + url, + expectedText: ['Fixture ready', 'Expected content'], + paginationPage: 2, + currentMenuHref: `${baseUrl}/clean`, + })); + await assert.rejects(auditRenderedPages({ themeDir, routes, outputDir }), (error) => { + assert(error instanceof AggregateError); + assert.equal(error.errors.length, 6, 'Every failing route must be reported, including routes after the first failure.'); + return true; + }); + const reports = Object.fromEntries(routes.map(({ name }) => { + assert(fs.readFileSync(path.join(outputDir, `${name}.html`), 'utf8').includes('Fixture ready')); + return [name, JSON.parse(fs.readFileSync(path.join(outputDir, `${name}.axe.json`), 'utf8'))]; + })); + assert.equal(reports.clean.error, undefined); + assert.equal(reports.clean.axe.violations.length, 0); + assert.deepEqual(reports.clean.wcagTags, wcagTags); + assert.deepEqual(disabledRules, ['target-size']); + assert.deepEqual(reports.clean.disabledRules, ['target-size']); + assert.equal(reports.clean.rendered.screenReaderText[0].position, 'static', 'Evidence must reflect actual computed styles without injecting screen-reader CSS.'); + assert.match(reports['http-error'].error, /HTTP 500/); + assert.match(reports['missing-content'].error, /missing expected rendered content/); + assert(reports['axe-violation'].axe.violations.some(({ id }) => id === 'image-alt')); + assert(reports['bad-media'].axe.violations.some(({ id }) => id === 'image-alt'), 'Axe must audit the document inside srcdoc too.'); + assert.match(reports['axe-violation'].error, /accessibility violations: image-alt/); + assert.match(reports['bad-pagination'].error, /exactly one current pagination item/); + assert.match(reports['bad-menu'].error, /exactly one current primary-menu item/); + } finally { + await new Promise((resolve) => server.close(resolve)); + fs.rmSync(outputDir, { recursive: true, force: true }); + } +}); diff --git a/.github/scripts/semantic-release.cjs b/.github/scripts/semantic-release.cjs index ac3926d..e46eeab 100644 --- a/.github/scripts/semantic-release.cjs +++ b/.github/scripts/semantic-release.cjs @@ -1,162 +1,169 @@ #!/usr/bin/env node -const { execFileSync, spawnSync } = require('node:child_process'); +const { execFileSync } = require('node:child_process'); const path = require('node:path'); +const { parseArgs } = require('node:util'); +const { validateReleaseVersionContract } = require('./release-version-contract.cjs'); -const repoRoot = path.resolve(__dirname, '..', '..'); -const { - expectedStableRelease, - initialStableBaseline, -} = require(path.join(repoRoot, 'release.config.js')); -const syntheticBaselineEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE'; -const syntheticBaselineShaEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SHA'; -const syntheticBaselineSourceEnvironment = 'EMULSIFY_SYNTHETIC_STABLE_BASELINE_SOURCE'; - -function git(args, options = {}) { - const output = execFileSync('git', args, { - cwd: repoRoot, - encoding: 'utf8', - ...options, - }); - - return typeof output === 'string' ? output.trim() : ''; -} - -function mergedTags() { - const output = git(['tag', '--merged', 'HEAD', '--sort=-version:refname']); - - return output === '' ? [] : output.split(/\r?\n/); +function git(repoRoot, args) { + return execFileSync('git', args, { cwd: repoRoot, encoding: 'utf8' }).trim(); } -function publishedTags() { - const output = git(['ls-remote', '--tags', 'origin']); - const tags = new Set(); +function assertPublishedStableTags(repoRoot) { + const stableTags = git(repoRoot, ['tag', '--list']) + .split(/\r?\n/).filter((tag) => /^\d+\.\d+\.\d+$/.test(tag)); + const remoteTags = new Set(git(repoRoot, ['ls-remote', '--tags', 'origin']) + .split(/\r?\n/).map((line) => (line.split(/\s+/)[1] || '') + .replace(/^refs\/tags\//, '').replace(/\^\{\}$/, ''))); + const localOnlyTags = stableTags.filter((tag) => !remoteTags.has(tag)); - for (const line of output.split(/\r?\n/)) { - const ref = line.trim().split(/\s+/)[1] || ''; - if (ref.startsWith('refs/tags/')) { - tags.add(ref.slice('refs/tags/'.length).replace(/\^\{\}$/, '')); - } + if (localOnlyTags.length > 0) { + throw new Error( + `Refusing to publish local-only stable tag(s): ${localOnlyTags.join(', ')}. Remove them or publish them intentionally first.`, + ); } - - return tags; } -function tagCommit(tag) { +function assertCurrentMain(repoRoot) { + const head = git(repoRoot, ['rev-parse', 'HEAD']); + let remoteMain; try { - return git(['rev-parse', '--verify', `${tag}^{commit}`]); + remoteMain = git(repoRoot, ['ls-remote', 'origin', 'refs/heads/main']).split(/\s+/)[0]; + } catch (error) { + throw new Error(`Unable to verify origin/main before releasing; check origin connectivity and retry. ${error.message}`); } - catch { - return null; + if (!remoteMain) { + throw new Error('Unable to verify origin/main before releasing: origin has no refs/heads/main.'); + } + if (head !== remoteMain) { + throw new Error( + `Main moved during the release: HEAD ${head} differs from origin/main ${remoteMain}. The Semantic release job is stale. Start a new workflow_dispatch run of WordPress Release (semantic-release.yml) on main instead of re-running the old job.`, + ); } } -function prepareStableBaseline() { - const branch = process.env.GITHUB_REF_NAME || git(['branch', '--show-current']); - - if (branch !== 'main') { - return null; +async function assertPublishedRelease(tag, env, fetchRelease) { + const token = env.GITHUB_TOKEN || env.GH_TOKEN; + const repository = env.GITHUB_REPOSITORY; + if (!token) throw new Error('GITHUB_TOKEN is required in CI to verify the tagged GitHub release and emulsify.zip.'); + if (!/^[\w.-]+\/[\w.-]+$/.test(repository || '')) { + throw new Error('GITHUB_REPOSITORY must identify owner/repo to verify the tagged GitHub release in CI.'); } - - const tags = mergedTags(); - const stableTags = tags.filter((tag) => /^\d+\.\d+\.\d+$/.test(tag)); - - if (stableTags.length > 0) { - const remoteTags = publishedTags(); - const localOnlyTags = stableTags.filter((tag) => !remoteTags.has(tag)); - - if (localOnlyTags.length > 0) { - throw new Error( - `Refusing to publish local-only stable tag(s): ${localOnlyTags.join(', ')}. Remove them or publish them intentionally first.` - ); - } - - return null; + const api = (env.GITHUB_API_URL || 'https://api.github.com').replace(/\/$/, ''); + const upload = `gh release upload ${tag} dist-artifact/emulsify.zip --repo ${repository} --clobber`; + const publish = `gh release edit ${tag} --repo ${repository} --draft=false --prerelease=false`; + let response; + let release; + try { + response = await fetchRelease(`${api}/repos/${repository}/releases/tags/${encodeURIComponent(tag)}`, { + headers: { Authorization: `Bearer ${token}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28' }, + redirect: 'error', + signal: AbortSignal.timeout(15000), + }); + if (response.ok) release = await response.json(); + } catch (error) { + throw new Error(`Unable to verify GitHub release ${tag}: ${error.message}. Restore API connectivity and rerun the release workflow.`); } - - const prereleaseTag = tags.find((tag) => tag.startsWith(`${initialStableBaseline}-`)); - - if (!prereleaseTag) { + if (response.status === 404) { + // The tag endpoint exposes published releases; read-only callers may not + // see a remaining draft. Keep recovery conditional instead of adding writes. throw new Error( - `Cannot prepare ${expectedStableRelease}: no stable tag or merged ${initialStableBaseline} prerelease tag was found.` + `Published GitHub release ${tag} is missing or still a draft. With a maintainer token, inspect: gh release view ${tag} --repo ${repository}. If no release exists, create a draft from the tag's tested ZIP: gh release create ${tag} dist-artifact/emulsify.zip --repo ${repository} --verify-tag --draft --title ${tag} --generate-notes. If a draft already exists, restore its ZIP instead: ${upload}. Review the release notes, then publish: ${publish}`, ); } - - const sourceSha = tagCommit(prereleaseTag); - if (!sourceSha) { - throw new Error(`Cannot resolve ${prereleaseTag} to a commit for the temporary stable baseline.`); + if (!response.ok) throw new Error(`Unable to verify GitHub release ${tag}: HTTP ${response.status}. Check GITHUB_TOKEN repository permissions and GitHub API availability, then rerun the release workflow.`); + if (!release || typeof release !== 'object' || Array.isArray(release) || !Array.isArray(release.assets)) { + throw new Error(`Unable to verify GitHub release ${tag}: invalid GitHub API response. Rerun after checking API availability.`); } + const zip = release.assets.find((asset) => asset?.name === 'emulsify.zip' && asset.state === 'uploaded' && typeof asset.size === 'number' && asset.size > 0); + const unpublished = release.draft !== false || release.prerelease !== false || !release.published_at; + if (!zip || unpublished) { + const commands = [!zip && upload, unpublished && publish].filter(Boolean).join('; '); + throw new Error(`Tagged release ${tag} is incomplete: ${!zip ? 'emulsify.zip is missing, empty, or not uploaded' : 'the GitHub release is not published as stable'}. Recover using the tag's tested ZIP and review the release notes before publishing: ${commands}`); + } + console.log(`Verified published GitHub release ${tag} with emulsify.zip.`); +} - git(['tag', initialStableBaseline, sourceSha]); +function releaseOptions(args) { + const { values } = parseArgs({ + args, + allowNegative: true, + options: { + 'tag-format': { type: 'string', short: 't' }, + 'dry-run': { type: 'boolean', short: 'd' }, + debug: { type: 'boolean' }, + ci: { type: 'boolean' }, + 'check-publication': { type: 'boolean' }, + }, + }); return { - sha: sourceSha, - source: prereleaseTag, - tag: initialStableBaseline, + ...(values['tag-format'] !== undefined && { tagFormat: values['tag-format'] }), + ...(values['dry-run'] !== undefined && { dryRun: values['dry-run'] }), + ...(values.ci !== undefined && { ci: values.ci }), + ...(values.debug !== undefined && { debug: values.debug }), + ...(values['check-publication'] !== undefined && { checkPublication: values['check-publication'] }), }; } -function removeStableBaseline(baseline) { - if (!baseline) { - return; +async function runSemanticRelease(options, context) { + if (options.debug) { + (await import('debug')).default.enable('semantic-release:*'); } + return (await import('semantic-release')).default(options, context); +} - const existingSha = tagCommit(baseline.tag); - if (!existingSha) { - return; +async function main({ + repoRoot = path.resolve(__dirname, '../..'), + args = process.argv.slice(2), + runRelease = runSemanticRelease, + env = process.env, + fetchRelease = globalThis.fetch, +} = {}) { + const { checkPublication = false, ...options } = releaseOptions(args); + const isCI = Boolean(env.CI) && env.CI !== 'false'; + const contract = validateReleaseVersionContract({ repoRoot }); + if (!contract.latestStableTag || !Object.hasOwn(contract, 'packageVersion')) { + throw new Error(contract.errors.join('\n')); } - if (existingSha !== baseline.sha) { - throw new Error( - `Refusing to delete ${baseline.tag}: it no longer points to the temporary baseline commit ${baseline.sha}.` - ); + // Check before skipping too: semantic-release must never push an unpublished + // stable tag from a developer's checkout. + assertPublishedStableTags(repoRoot); + // Diagnose a partial tag-first release before stale draft metadata masks it. + if (isCI && contract.packageVersion === contract.latestStableTag) { + await assertPublishedRelease(contract.latestStableTag, env, fetchRelease); + } + // The early workflow preflight is read-only. Full readiness and the normal + // runner still enforce all document and version rules before publishing. + if (checkPublication) return 0; + if (contract.errors.length > 0) throw new Error(contract.errors.join('\n')); + if (!contract.releasePrepared) { + console.log(`No release prepared: package.json matches latest stable tag ${contract.latestStableTag}. Skipping publishing.`); + return 0; } - git(['tag', '--delete', baseline.tag], { stdio: 'ignore' }); -} - -function main() { - let temporaryBaseline = null; - - try { - temporaryBaseline = prepareStableBaseline(); - - const cli = require.resolve('semantic-release/bin/semantic-release.js'); - const result = spawnSync(process.execPath, [cli, ...process.argv.slice(2)], { - cwd: repoRoot, - env: { - ...process.env, - [syntheticBaselineEnvironment]: temporaryBaseline?.tag || '', - [syntheticBaselineShaEnvironment]: temporaryBaseline?.sha || '', - [syntheticBaselineSourceEnvironment]: temporaryBaseline?.source || '', - }, - stdio: 'inherit', - }); - - if (result.error) { - throw result.error; - } - - if ( - result.status === 0 - && temporaryBaseline - && tagCommit(temporaryBaseline.tag) - ) { - throw new Error( - `Semantic-release completed without removing the temporary ${temporaryBaseline.tag} baseline tag.` - ); - } + if (isCI) assertCurrentMain(repoRoot); - return Number.isInteger(result.status) ? result.status : 1; + // A release PR can verify its version before merging to main. This override + // is only for an explicit local dry run, which cannot tag or publish. + if (!isCI && options.dryRun && options.ci === false) { + options.branches = [git(repoRoot, ['branch', '--show-current'])]; } - finally { - removeStableBaseline(temporaryBaseline); + + const result = await runRelease(options, { cwd: repoRoot }); + if (result?.nextRelease?.version !== contract.packageVersion) { + throw new Error( + `Prepared package.json version ${contract.packageVersion}, but semantic-release ${result?.nextRelease ? `computed ${result.nextRelease.version}` : 'did not compute a release'}. Run on main with releasable Conventional Commits matching the prepared version, then rerun npm run release:check.`, + ); } + return 0; } -try { - process.exitCode = main(); -} -catch (error) { - console.error(`Semantic release runner failed: ${error.message}`); - process.exitCode = 1; +if (require.main === module) { + main().then((status) => { process.exitCode = status; }).catch((error) => { + console.error(`Semantic release runner failed: ${error.message}`); + process.exitCode = 1; + }); } + +module.exports = { assertPublishedStableTags, main, releaseOptions }; diff --git a/.github/scripts/semantic-release.test.cjs b/.github/scripts/semantic-release.test.cjs new file mode 100644 index 0000000..dd7fd8e --- /dev/null +++ b/.github/scripts/semantic-release.test.cjs @@ -0,0 +1,292 @@ +const assert = require('node:assert/strict'); +const { execFileSync } = require('node:child_process'); +const fs = require('node:fs'); +const os = require('node:os'); +const path = require('node:path'); +const { test } = require('node:test'); +const { assertPublishedStableTags, main, releaseOptions } = require('./semantic-release.cjs'); +const releaseConfig = require('../../release.config.js'); +const guard = releaseConfig.plugins.find((plugin) => typeof plugin.verifyRelease === 'function'); + +const githubEnv = { + CI: 'true', + GITHUB_TOKEN: 'fixture-token', + GITHUB_REPOSITORY: 'emulsify-ds/emulsify-wordpress', +}; + +function publishedRelease(overrides = {}) { + return { + draft: false, + prerelease: false, + published_at: '2026-10-28T12:00:00Z', + assets: [{ name: 'emulsify.zip', state: 'uploaded', size: 42 }], + ...overrides, + }; +} + +function releaseResponse(status = 200, release = publishedRelease()) { + return { ok: status >= 200 && status < 300, status, json: async () => release }; +} + +function fixture(t, version = '2.1.0') { + const workRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'emulsify-publish-contract-')); + t.after(() => fs.rmSync(workRoot, { recursive: true, force: true })); + const repoRoot = path.join(workRoot, 'checkout'); + const remote = path.join(workRoot, 'origin.git'); + fs.mkdirSync(repoRoot); + const git = (...args) => execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', ...args], { cwd: repoRoot, encoding: 'utf8', stdio: 'pipe' }).trim(); + // Keep remote HEAD valid even when the runner defaults to another branch. + git('-c', 'init.defaultBranch=legacy', 'init', '--bare', '-b', 'main', remote); + git('init', '-b', 'main'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'chore: initial release'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'tag', '-a', '2.0.0', '-m', '2.0.0'); + git('remote', 'add', 'origin', remote); + git('push', 'origin', 'main', '--tags'); + fs.mkdirSync(path.join(repoRoot, 'docs')); + for (const file of ['README.md', 'docs/release-process.md', 'docs/release-notes-next.md']) { + fs.writeFileSync(path.join(repoRoot, file), ''); + } + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ name: 'release-contract', version })); + fs.mkdirSync(path.join(repoRoot, 'dist-artifact')); + fs.writeFileSync(path.join(repoRoot, 'dist-artifact/emulsify.zip'), 'fixture release archive'); + return { repoRoot, remote, git }; +} + +test('publish guard accepts the exact prepared version on every subsequent release', (t) => { + const { repoRoot } = fixture(t); + guard.verifyRelease({}, { cwd: repoRoot, nextRelease: { version: '2.1.0' } }); + assert.throws(() => guard.verifyRelease({}, { cwd: repoRoot, nextRelease: { version: '2.0.1' } }), /Prepared package.json version 2\.1\.0.*computed 2\.0\.1.*release PR/); + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ version: '3.0.0' })); + assert.throws(() => guard.verifyRelease({}, { cwd: repoRoot, lastRelease: { version: '2.1.0' }, nextRelease: { version: '2.2.0' } }), /Prepared package.json version 3\.0\.0.*computed 2\.2\.0/); +}); + +test('skips publishing successfully when package.json equals the latest tag', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + const status = await main({ repoRoot, env: {}, args: ['--dry-run', '--debug', '--no-ci'], runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.') }); + assert.equal(status, 0); +}); + +test('prepared release accepts a matching semantic-release result and forwards documented flags', async (t) => { + const { repoRoot } = fixture(t); + const status = await main({ repoRoot, env: {}, args: ['--tag-format', '${version}', '--dry-run', '--debug', '--no-ci'], runRelease: async (options, context) => { + assert.equal(context.cwd, repoRoot); + assert.equal(options.tagFormat, '${version}'); + assert.equal(options.dryRun, true); + assert.equal(options.debug, true); + assert.equal(options.ci, false); + guard.verifyRelease({}, { ...context, nextRelease: { version: '2.1.0' } }); + return { nextRelease: { version: '2.1.0' } }; + } }); + assert.equal(status, 0); +}); + +test('prepared release rejects mismatched or absent semantic-release results', async (t) => { + const { repoRoot } = fixture(t); + for (const result of [false, { nextRelease: { version: '2.0.1' } }]) { + await assert.rejects(main({ repoRoot, env: {}, args: [], runRelease: async () => result }), /Prepared package.json version 2\.1\.0.*(?:computed 2\.0\.1|did not compute a release).*Conventional Commits/); + } +}); + +test('refuses local-only stable tags before any publishing or skip', async (t) => { + const { repoRoot, git } = fixture(t, '2.0.1'); + assert.doesNotThrow(() => assertPublishedStableTags(repoRoot)); + git('tag', '2.0.1'); + assert.throws(() => assertPublishedStableTags(repoRoot), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); + await assert.rejects(main({ repoRoot, env: {}, args: [], runRelease: () => assert.fail('Local-only stable tags must block semantic-release.') }), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); +}); + +test('also refuses local-only stable tags on unmerged branches', (t) => { + const { repoRoot, git } = fixture(t); + git('switch', '-c', 'unmerged'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'chore: unmerged work'); + git('tag', '2.0.1'); + git('switch', 'main'); + assert.equal(git('tag', '--merged', 'HEAD'), '2.0.0'); + assert.throws(() => assertPublishedStableTags(repoRoot), /Refusing to publish local-only stable tag\(s\): 2\.0\.1/); +}); + +function advanceRemoteMain({ repoRoot, remote }) { + const otherCheckout = path.join(path.dirname(repoRoot), 'main-mover'); + execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', 'clone', '--quiet', remote, otherCheckout], { stdio: 'pipe' }); + const git = (...args) => execFileSync('git', ['-c', 'commit.gpgsign=false', '-c', 'tag.gpgSign=false', ...args], { cwd: otherCheckout, encoding: 'utf8', stdio: 'pipe' }).trim(); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'docs: update contributors'); + git('push', 'origin', 'main'); + return git('rev-parse', 'HEAD'); +} + +test('CI refuses a moved remote main before semantic-release, even with --no-ci and a stale tracking ref', async (t) => { + const repository = fixture(t); + const { repoRoot, git } = repository; + const checkedOut = git('rev-parse', 'HEAD'); + const remoteHead = advanceRemoteMain(repository); + assert.notEqual(remoteHead, checkedOut); + assert.equal(git('rev-parse', 'origin/main'), checkedOut, 'The regression must not refresh the stale tracking ref.'); + let released = false; + await assert.rejects(main({ + repoRoot, env: { CI: 'true' }, args: ['--dry-run', '--no-ci'], + runRelease: async () => { released = true; return { nextRelease: { version: '2.1.0' } }; }, + }), /main moved.*Semantic release.*workflow_dispatch.*main/i); + assert.equal(released, false, 'The preflight must stop before semantic-release can run.'); +}); + +test('CI accepts current main and a fresh detached workflow_dispatch after main moved', async (t) => { + const repository = fixture(t); + const { repoRoot, git } = repository; + const runRelease = async (options) => { + assert.equal(options.branches, undefined, 'CI must keep the configured main branch even with --no-ci.'); + return { nextRelease: { version: '2.1.0' } }; + }; + assert.equal(await main({ repoRoot, env: { CI: 'true' }, args: [], runRelease }), 0); + const currentMain = advanceRemoteMain(repository); + git('fetch', 'origin', 'main'); + git('switch', '--detach', 'origin/main'); + assert.equal(git('rev-parse', 'HEAD'), currentMain); + assert.equal(await main({ + repoRoot, env: { CI: 'true', GITHUB_EVENT_NAME: 'workflow_dispatch', GITHUB_REF: 'refs/heads/main' }, + args: ['--dry-run', '--no-ci'], runRelease, + }), 0); +}); + +test('local dry runs on a release branch do not require HEAD to equal remote main', async (t) => { + const { repoRoot, git } = fixture(t); + git('switch', '-c', 'release-2.1.x'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'feat: prepare the next release'); + for (const env of [{}, { CI: 'false' }]) { + assert.equal(await main({ + repoRoot, env, args: ['--dry-run', '--no-ci'], + runRelease: async (options) => { + assert.deepEqual(options.branches, ['release-2.1.x']); + return { nextRelease: { version: '2.1.0' } }; + }, + }), 0); + } +}); + +test('CI still skips a valid unprepared release without invoking semantic-release', async (t) => { + const repository = fixture(t, '2.0.0'); + advanceRemoteMain(repository); + let checked = 0; + assert.equal(await main({ + repoRoot: repository.repoRoot, env: githubEnv, args: [], + fetchRelease: async (url, options) => { + checked += 1; + assert.equal(url, 'https://api.github.com/repos/emulsify-ds/emulsify-wordpress/releases/tags/2.0.0'); + assert.equal(options.headers.Authorization, 'Bearer fixture-token'); + assert.equal(options.redirect, 'error', 'Release credentials must not follow redirects.'); + return releaseResponse(); + }, + runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.'), + }), 0); + assert.equal(checked, 1, 'CI must verify publication health before treating the tagged version as a successful skip.'); +}); + +test('CI refuses a missing GitHub release for a tag and reports safe recovery commands', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + await assert.rejects(main({ + repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(404), + runRelease: () => assert.fail('A partial release must never invoke semantic-release.'), + }), /release 2\.0\.0.*missing or still a draft.*gh release view 2\.0\.0.*gh release create 2\.0\.0.*--verify-tag.*--draft[\s\S]*gh release upload 2\.0\.0[\s\S]*gh release edit 2\.0\.0.*--draft=false/i); +}); + +test('CI refuses unpublished releases and missing or incomplete release ZIP assets', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + for (const release of [ + publishedRelease({ draft: true, published_at: null }), + publishedRelease({ prerelease: true }), + publishedRelease({ published_at: null }), + publishedRelease({ assets: [] }), + publishedRelease({ assets: [{ name: 'source.zip', state: 'uploaded', size: 42 }] }), + publishedRelease({ assets: [{ name: 'emulsify.zip', state: 'starter', size: 42 }] }), + publishedRelease({ assets: [{ name: 'emulsify.zip', state: 'uploaded', size: 0 }] }), + ]) { + await assert.rejects(main({ + repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(200, release), + runRelease: () => assert.fail('A partial release must never invoke semantic-release.'), + }), /gh release (?:upload|edit) 2\.0\.0/); + } +}); + +test('CI recovery check fails closed on absent credentials, API failures, and invalid release responses', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + for (const env of [{ CI: 'true' }, { CI: 'true', GITHUB_TOKEN: 'fixture-token' }]) { + await assert.rejects(main({ + repoRoot, env, args: [], fetchRelease: () => assert.fail('Missing CI configuration must fail before requesting GitHub.'), + }), /GITHUB_TOKEN|GITHUB_REPOSITORY/); + } + for (const status of [401, 403, 500]) { + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(status) }), new RegExp(`HTTP ${status}`)); + } + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => { throw new Error('network unavailable'); } }), /Unable to verify GitHub release.*network unavailable/); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(200, null) }), /Unable to verify GitHub release/); +}); + +test('CI diagnoses partial tagged releases before stale-draft errors but keeps the draft contract strict', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + fs.writeFileSync(path.join(repoRoot, 'docs/release-notes-next.md'), '# 2.0.0 Release Notes Draft'); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse(404) }), /gh release create 2\.0\.0/); + await assert.rejects(main({ repoRoot, env: githubEnv, args: [], fetchRelease: async () => releaseResponse() }), /already-tagged release 2\.0\.0/); +}); + +test('local unprepared runs remain tokenless and do not query GitHub', async (t) => { + const { repoRoot } = fixture(t, '2.0.0'); + assert.equal(await main({ + repoRoot, env: {}, args: ['--dry-run', '--no-ci'], + fetchRelease: () => assert.fail('Local skips do not require GitHub API access.'), + runRelease: () => assert.fail('An unprepared release must not invoke semantic-release.'), + }), 0); +}); + +test('publication preflight never invokes semantic-release and leaves draft validation to readiness', async (t) => { + const { repoRoot } = fixture(t); + fs.writeFileSync(path.join(repoRoot, 'README.md'), 'Latest release: 1.9.9'); + assert.equal(await main({ + repoRoot, env: githubEnv, args: ['--check-publication'], + fetchRelease: () => assert.fail('An upcoming untagged release has no GitHub release to check.'), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), 0); + fs.writeFileSync(path.join(repoRoot, 'package.json'), JSON.stringify({ version: '2.0.0' })); + await assert.rejects(main({ + repoRoot, env: githubEnv, args: ['--check-publication'], fetchRelease: async () => releaseResponse(404), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), /gh release create 2\.0\.0/); + assert.equal(await main({ + repoRoot, env: githubEnv, args: ['--check-publication'], fetchRelease: async () => releaseResponse(), + runRelease: () => assert.fail('Publication preflight must never publish.'), + }), 0); +}); + +test('parses the existing publish and publish-test command options', () => { + assert.deepEqual(releaseOptions(['--tag-format', '${version}', '--dry-run', '--debug', '--no-ci']), { tagFormat: '${version}', dryRun: true, debug: true, ci: false }); + assert.deepEqual(releaseOptions(['-t', '${version}', '-d']), { tagFormat: '${version}', dryRun: true }); + assert.deepEqual(releaseOptions(['--check-publication']), { checkPublication: true }); +}); + +test('real semantic-release dry run analyzes a pushed release PR branch and blocks mismatches before tagging', (t) => { + const { repoRoot, remote, git } = fixture(t); + fs.symlinkSync(path.resolve(__dirname, '../../node_modules'), path.join(repoRoot, 'node_modules'), 'dir'); + git('switch', '-c', 'release-2.1.x'); + git('-c', 'user.name=Contract Test', '-c', 'user.email=contract@example.invalid', 'commit', '--allow-empty', '-m', 'feat: add a project capability'); + git('push', 'origin', 'release-2.1.x'); + // semantic-release hooks stdout, so run it outside node:test's event stream. + const script = ` + const assert = require('node:assert/strict'); + const fs = require('node:fs'); + const { main } = require(${JSON.stringify(path.join(__dirname, 'semantic-release.cjs'))}); + const config = require(${JSON.stringify(path.resolve(__dirname, '../../release.config.js'))}); + (async () => { + const { default: semanticRelease } = await import(${JSON.stringify(require.resolve('semantic-release'))}); + const guard = config.plugins.find((plugin) => typeof plugin.verifyRelease === 'function'); + const runRelease = (options, context) => semanticRelease({ + ...config, ...options, repositoryUrl: ${JSON.stringify(remote)}, plugins: [config.plugins[0], guard], + }, context); + const options = { repoRoot: process.cwd(), env: {}, args: ['--dry-run', '--no-ci'], runRelease }; + assert.equal(await main(options), 0); + fs.writeFileSync('package.json', JSON.stringify({ version: '2.0.1' })); + await assert.rejects(main(options), /Prepared package.json version 2\\.0\\.1.*computed 2\\.1\\.0/); + })().catch((error) => { console.error(error); process.exitCode = 1; }); + `; + // CI provider branch variables and node:test IPC belong to the outer repo. + const env = { PATH: process.env.PATH, HOME: process.env.HOME }; + execFileSync(process.execPath, ['-e', script], { cwd: repoRoot, env, stdio: 'pipe' }); + assert.equal(git('tag', '--list'), '2.0.0'); +}); diff --git a/.github/scripts/template-extension-smoke.php b/.github/scripts/template-extension-smoke.php new file mode 100644 index 0000000..299cd55 --- /dev/null +++ b/.github/scripts/template-extension-smoke.php @@ -0,0 +1,412 @@ +'; +} + +function get_the_title( $post = 0 ): string { + $GLOBALS['emulsify_extension_title_posts'][] = $post; + return 'Protected: Secret