Read and resolve entrypoints.json in RepriseBundle

docs/adr/0001-packages-driven-asset-urls.md

@@ -0,0 +1,67 @@
+# 1. Packages-driven asset URL resolution
+
+- Status: Accepted
+- Date: 2026-07-11
+
+## Context
+
+The `@symfony/reprise` plugin currently writes `entrypoints.json` with **final** URLs
+(content-hashed filenames, prefixed with `publicPath`), and `RepriseBundle` would render the
+`<script>`/`<link>` tags from those URLs as-is.
+
+Emitting final URLs and skipping Symfony's asset component loses, at render time:
+
+- **`base_path`** — a build cannot be served under an arbitrary sub-directory
+  (`https://host/myapp/`); baked `/build/...` URLs 404 under `/myapp`.
+- **`base_urls`** — no runtime CDN selection or domain sharding.
+- **named packages** — `asset(path, 'package')`-style routing.
+- **consistency** — entry tags do not share the URL treatment `asset()` gives the app's other
+  assets (images, etc.).
+- **version not in the filename** — Webpack Encore lets the hash live in a query string
+  (`app.js?v=hash`, see symfony/webpack-encore#1266 and #1340), where only the manifest carries
+  the version. The general lesson: a URL is opaque, not a filesystem path, and the PHP side must
+  not assume where the version lives.
+
+## Decision
+
+Adopt Webpack Encore's model: **`Packages` (symfony/asset) drives final URL generation at render
+time.** The bundler is responsible only for producing the files (already content-hashed) and the
+manifest; `RepriseBundle` turns a reference into a URL via `Packages::getUrl()`
+(`base_path` + `base_urls` [+ named package]).
+
+Concretely — the "relative hashed paths" variant, chosen over the pure-Encore "logical keys +
+`JsonManifestVersionStrategy`" one because Vite/Rollup shared & dynamic chunks are anonymous
+(hashed names only, no natural logical key):
+
+- **`entrypoints.json` (build)** carries **relative, hashed** paths — `build/app-<hash>.js`, no
+  leading slash and no origin — instead of final URLs.
+- **`RepriseBundle`** resolves each reference through a Reprise asset package configured with the
+  app's `base_path`/`base_urls` but an **empty version strategy** (the filename is already
+  hashed).
+- **Dev / serve mode** keeps **absolute** dev-server-origin URLs
+  (`http://127.0.0.1:5173/build/app.js`); `Packages` returns absolute URLs unchanged, so
+  `base_path`/CDN correctly do not apply (the browser hits the dev server directly).
+- **SRI**: the `integrity` map must be keyed so the tag renderer can find each hash for the
+  reference it renders. SRI computation (hashing files on disk) is unaffected; only the map's key
+  changes.
+
+## Consequences
+
+This is cross-cutting, not a PHP-only addition:
+
+- **JS plugin** (`assets/src/core/format.ts`, collectors, the `cdn`/`build` integration tests):
+  build `entrypoints.json` changes from final URLs to relative hashed paths; SRI integrity keying
+  updates; the shipped tests that assert final URLs change.
+- **RepriseBundle**: the tag renderer (slice 2) resolves via `Packages`; config points at the
+  package(s); the integrity lookup is keyed to match. `EntrypointsLookup` (slice 1) is unaffected —
+  it returns whatever references the file holds.
+- **Docs**: the "Using a CDN" section reframes around `framework.assets`
+  (`base_path`/`base_urls`) instead of an absolute build-time `publicPath`.
+
+## Considered and rejected
+
+- **Keep self-describing final URLs.** Simplest, but loses everything under _Context_.
+- **Pure Encore (logical keys + `JsonManifestVersionStrategy`).** Most faithful and would support
+  query-string versioning, but requires inventing stable manifest keys for Vite's anonymous
+  shared/dynamic chunks, and query-string versioning is not expressible in Rollup output names
+  anyway.

src/Asset/DevServer.php

@@ -0,0 +1,46 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Reprise\Asset;
+
+use Symfony\Reprise\Exception\InvalidEntrypointsException;
+
+/**
+ * The dev-server section of a serve-mode entrypoints.json.
+ *
+ * @author Hugo Alliaume <hugo@alliau.me>
+ */
+final class DevServer
+{
+    public function __construct(
+        public readonly string $origin,
+        public readonly ?string $client,
+    ) {
+    }
+
+    /**
+     * @param array<mixed, mixed> $data the raw, untrusted decoded "devServer" section
+     */
+    public static function fromArray(array $data): self
+    {
+        $origin = $data['origin'] ?? null;
+        if (!\is_string($origin)) {
+            throw new InvalidEntrypointsException('The dev-server "origin" must be a string.');
+        }
+
+        $client = $data['client'] ?? null;
+        if (null !== $client && !\is_string($client)) {
+            throw new InvalidEntrypointsException('The dev-server "client" must be a string or null.');
+        }
+
+        return new self($origin, $client);
+    }
+}

src/Asset/Entry.php

@@ -0,0 +1,71 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Reprise\Asset;
+
+use Symfony\Reprise\Exception\InvalidEntrypointsException;
+
+/**
+ * One entry's asset URLs, grouped by type, in load order.
+ *
+ * @author Hugo Alliaume <hugo@alliau.me>
+ *
+ * @internal
+ */
+final class Entry
+{
+    /**
+     * @param list<string> $js
+     * @param list<string> $css
+     * @param list<string> $preload
+     * @param list<string> $dynamic
+     */
+    public function __construct(
+        public readonly array $js,
+        public readonly array $css,
+        public readonly array $preload,
+        public readonly array $dynamic,
+    ) {
+    }
+
+    /**
+     * @param array<mixed, mixed> $data the raw, untrusted decoded entry section
+     */
+    public static function fromArray(array $data, string $entryName): self
+    {
+        return new self(
+            self::stringList($data['js'] ?? [], $entryName, 'js'),
+            self::stringList($data['css'] ?? [], $entryName, 'css'),
+            self::stringList($data['preload'] ?? [], $entryName, 'preload'),
+            self::stringList($data['dynamic'] ?? [], $entryName, 'dynamic'),
+        );
+    }
+
+    /**
+     * @return list<string>
+     */
+    private static function stringList(mixed $value, string $entryName, string $key): array
+    {
+        if (!\is_array($value) || !array_is_list($value)) {
+            throw new InvalidEntrypointsException(\sprintf('The "%s" key of entry "%s" must be a list of strings.', $key, $entryName));
+        }
+
+        $strings = [];
+        foreach ($value as $item) {
+            if (!\is_string($item)) {
+                throw new InvalidEntrypointsException(\sprintf('The "%s" key of entry "%s" must contain only strings.', $key, $entryName));
+            }
+            $strings[] = $item;
+        }
+
+        return $strings;
+    }
+}

src/Asset/Entrypoints.php

@@ -0,0 +1,101 @@
+<?php
+
+/*
+ * This file is part of the Symfony package.
+ *
+ * (c) Fabien Potencier <fabien@symfony.com>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Symfony\Reprise\Asset;
+
+use Symfony\Reprise\Exception\InvalidEntrypointsException;
+
+/**
+ * The parsed contents of an entrypoints.json file emitted by the @symfony/reprise plugin.
+ *
+ * Unlike Webpack Encore's format, the file is self-describing: it carries the build mode
+ * (`isProd`/`devServer`), the `publicPath`, per-entry `preload`/`dynamic` chunks and, when
+ * SRI is enabled, an `integrity` map keyed by asset URL.
+ *
+ * @author Hugo Alliaume <hugo@alliau.me>
+ *
+ * @internal
+ */
+final class Entrypoints
+{
+    /**
+     * @param array<string, Entry>  $entryPoints
+     * @param array<string, string> $integrity
+     */
+    public function __construct(
+        public readonly bool $isProd,
+        public readonly ?DevServer $devServer,
+        public readonly string $publicPath,
+        public readonly array $entryPoints,
+        public readonly array $integrity,
+    ) {
+    }
+
+    /**
+     * Validate and hydrate the raw decoded contents of an entrypoints.json file.
+     *
+     * The input is untrusted (whatever `json_decode()` produced), so it is deliberately typed
+     * loosely -- checking its shape is this method's job. Precision instead lives on the value
+     * object's properties and on the file-format documented on the class.
+     *
+     * @param array<mixed, mixed> $data
+     */
+    public static function fromArray(array $data): self
+    {
+        $isProd = $data['isProd'] ?? null;
+        if (!\is_bool($isProd)) {
+            throw new InvalidEntrypointsException('The "isProd" key must be a boolean.');
+        }
+
+        $publicPath = $data['publicPath'] ?? null;
+        if (!\is_string($publicPath)) {
+            throw new InvalidEntrypointsException('The "publicPath" key must be a string.');
+        }
+
+        $rawEntries = $data['entryPoints'] ?? null;
+        if (!\is_array($rawEntries)) {
+            throw new InvalidEntrypointsException('The "entryPoints" key must be an object.');
+        }
+
+        $entryPoints = [];
+        foreach ($rawEntries as $name => $files) {
+            if (!\is_array($files)) {
+                throw new InvalidEntrypointsException(\sprintf('Entry "%s" must be an object.', (string) $name));
+            }
+            $entryPoints[(string) $name] = Entry::fromArray($files, (string) $name);
+        }
+
+        $devServer = $data['devServer'] ?? null;
+        if (null !== $devServer && !\is_array($devServer)) {
+            throw new InvalidEntrypointsException('The "devServer" key must be an object or null.');
+        }
+
+        $rawIntegrity = $data['integrity'] ?? [];
+        if (!\is_array($rawIntegrity)) {
+            throw new InvalidEntrypointsException('The "integrity" key must be an object.');
+        }
+        $integrity = [];
+        foreach ($rawIntegrity as $url => $hash) {
+            if (!\is_string($url) || !\is_string($hash)) {
+                throw new InvalidEntrypointsException('The "integrity" map must map asset URLs to hash strings.');
+            }
+            $integrity[$url] = $hash;
+        }
+
+        return new self(
+            $isProd,
+            null !== $devServer ? DevServer::fromArray($devServer) : null,
+            $publicPath,
+            $entryPoints,
+            $integrity,
+        );
+    }
+}