@valbuild/shared 0.123.2 → 0.124.0

package/CHANGELOG.md

@@ -1,5 +1,113 @@
 # @valbuild/shared
 
+## 0.124.0
+
+### Minor Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Show `.jsonValues()` entries in the history pane
+
+  A `.jsonValues()` record keeps each entry's content in its own `*.val.json`
+  file; the module's own content is just markers pointing at them. The history
+  pane had no way to fetch those files for a past commit, so every entry rendered
+  as an **empty field** — which reads as "the author left this blank", about
+  content that was simply stored somewhere else.
+
+  Entries now load in the history pane the same way they load in the Studio: one
+  at a time, when you open one. A commit with a thousand support pages costs
+  nothing until you look at one of them.
+
+  An entry that cannot be read says so instead of rendering blank — including the
+  case where the key did not exist yet at that commit, which is a real answer
+  rather than an error.
+
+### Patch Changes
+
+- [#639](https://github.com/valbuild/val/pull/639) [`ad7fff4`](https://github.com/valbuild/val/commit/ad7fff4cc8cea98c506cf7ff9b4e8d6e5ffa4055) Thanks [@freekh](https://github.com/freekh)! - Require a session to read a file from history
+
+  `GET /api/val/history/files` served a file at a given commit to anyone who
+  asked. It followed the reasoning of `/api/val/files`, which is deliberately
+  open — and neither half of that reasoning applies to it:
+
+  - `/files` stands on `patch_id` being an unguessable UUID. A **commit sha is
+    published** — `git log`, the GitHub UI, every pull request — so it is no
+    substitute for a credential.
+  - `/files` also _cannot_ require auth: draft images are fetched by the app's own
+    backend during Next image optimisation, with no cookies to send. Nothing
+    fetches history files server-side; both callers are the Studio, in a browser
+    that already holds the session.
+
+  So history files now require a session. `/files` is unchanged, and the reason
+  the two differ is written down in `architecture/media.md` so it is not "fixed"
+  in either direction later.
+
+  No action needed: the Studio sends its session cookie automatically.
+
+- Updated dependencies [[`aa89fc2`](https://github.com/valbuild/val/commit/aa89fc26de7028b3c5a1666b99afc03b39e92769)]:
+  - @valbuild/core@0.124.0
+
+## 0.123.3
+
+### Patch Changes
+
+- [#633](https://github.com/valbuild/val/pull/633) [`accf4f8`](https://github.com/valbuild/val/commit/accf4f852fe3400d762cc14e80316da741a69a9a) Thanks [@freekh](https://github.com/freekh)! - Stop `@valbuild/shared` replacing a consumer's own flexsearch types
+
+  `@valbuild/shared` gained a flexsearch dependency in 0.123.0, for
+  `search_content`, and typed its exported `SearchIndex.index` as flexsearch's
+  own `Index`. That put `import { Index } from "flexsearch"` into the published
+  `searchIndex.d.ts` — and flexsearch's type entry opens with
+  `declare module "flexsearch"`, which is an AMBIENT module declaration and so
+  global to a whole TypeScript program.
+
+  The effect on a project that uses flexsearch itself, at a different version:
+  its own calls are checked against the copy Val dragged in. valbuild/web pins
+  flexsearch 0.7 and builds an index with
+  `new flexsearch.Document({ language: "en", … })`; on `@valbuild/shared@0.123.2`
+  that stopped compiling, because 0.8's `DocumentOptions` has no `language`. Its
+  resolved copy was still 0.7 — only the types had been swapped underneath it.
+
+  `SearchIndex.index` is now a structural type covering the three methods this
+  package calls, so nothing in the published declarations names flexsearch. The
+  library is still used to build the index; that is a value import, which never
+  reaches a `.d.ts`.
+
+  No API change: `SearchIndex` is still assignable from a real flexsearch
+  `Index`, and `noFlexsearchInPublishedTypes.test.ts` asserts both halves of that
+  — that no source file names flexsearch in a type position, and that a real
+  `Index` still satisfies the stand-in, so it cannot drift from the library
+  unnoticed.
+
+- [#628](https://github.com/valbuild/val/pull/628) [`aef45ce`](https://github.com/valbuild/val/commit/aef45ce3ef269f1b6221de44a56df0f6a0d9dbbd) Thanks [@freekh](https://github.com/freekh)! - Stop the serialized-schema parser dropping schema metadata
+
+  `SerializedSchema` in `@valbuild/shared` is a zod mirror of the serialized
+  schema type, and its `z.object`s strip keys they do not declare. Five fields
+  were declared on some schemas and forgotten on others:
+
+  - `customValidate` — missing on twelve of the eighteen schemas. This is the flag
+    that says a schema declares a `.validate()`; the function itself cannot
+    serialize, so the flag is the only thing that tells the Studio to run the
+    custom validators against the real instance.
+  - `description` — missing on thirteen, so a `.describe()` went unseen.
+  - `remote` and `referencedModule` — missing on `s.image()` and `s.file()`, so a
+    remote field read as local and a gallery-backed field lost the gallery it
+    reads its dimensions and mime type from.
+  - the `message` on a `.regexp(pattern, message)` — so a field with a custom
+    pattern message fell back to the generic "Expected string to match reg
+    exp: …".
+
+  Because it strips rather than rejects, nothing failed and nothing said so. The
+  live `/schema` route was unaffected — `ValClient` validates the response and
+  then returns the raw JSON — but the history path consumes the parsed output, so
+  in a commit or historical patch-set view (`getModuleAtCommit`,
+  `getHistoricalPatchSet`) a schema's custom validators, description, remoteness
+  and backing gallery all quietly disappeared.
+
+  The fields every serialized schema shares are now spread from one
+  `commonSchemaFields` object instead of being retyped eighteen times, which is
+  how they drifted apart in the first place. A round-trip test walks each schema's
+  serialized output against the parsed result and fails with the path of any key
+  that did not survive, so a field added to a serialized schema and forgotten in
+  the parser is caught without anyone having to remember to assert it.
+
 ## 0.123.2
 
 ### Patch Changes

package/dist/declarations/src/internal/ApiRoutes.d.ts

@@ -1329,6 +1329,80 @@ export declare const Api: {
      * actually mounts. A file at a fixed commit cannot change, so the response is
      * immutable and the browser's own cache handles flipping between commits.
      */
+    /**
+     * One `.jsonValues()` entry's content, as it was at a commit.
+     *
+     * The history pane's counterpart to `/json`. A `.jsonValues()` record's
+     * source is only `{_type:"json"}` markers - the content is per entry, fetched
+     * on demand - so without this the commit pane rendered every entry as an
+     * empty field, which is a claim that the author left it blank.
+     *
+     * One entry per request, deliberately: the store fetches an entry when
+     * something reads inside it, so a batch would mean guessing which entries the
+     * pane is about to show. Authenticated for the same reasons as
+     * `/history/files` below.
+     */
+    "/history/json": {
+        GET: {
+            req: {
+                query: {
+                    commit_sha: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                    key: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
+                };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
+            };
+            res: z.ZodUnion<readonly [z.ZodObject<{
+                status: z.ZodLiteral<401>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<404>;
+                json: z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<400>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<500>;
+                json: z.ZodIntersection<z.ZodObject<{
+                    message: z.ZodString;
+                }, z.core.$strip>, z.ZodObject<{
+                    kind: z.ZodOptional<z.ZodString>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>, z.ZodObject<{
+                status: z.ZodLiteral<200>;
+                json: z.ZodObject<{
+                    path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+                    key: z.ZodString;
+                    content: z.ZodUnknown;
+                }, z.core.$strip>;
+            }, z.core.$strip>]>;
+        };
+    };
+    /**
+     * A binary file as it was at a commit.
+     *
+     * AUTHENTICATED, unlike `/files` below - and the difference is not an
+     * oversight in either direction. See the comment on `/files`: what makes it
+     * safe to leave open is that a `patch_id` is an unguessable UUID, and what
+     * makes leaving it open NECESSARY is that a draft image is fetched by the
+     * app's own backend during Next image optimisation, with no cookies.
+     *
+     * Neither holds here. A commit sha is published - `git log`, the GitHub UI,
+     * every PR - so it is not a secret to stand in for a credential. And nothing
+     * fetches these server-side: they are read by the Studio, in a browser that
+     * has the session cookie, for the history pane and for staging a restore.
+     * So this one asks.
+     */
     "/history/files": {
         GET: {
             req: {
@@ -1337,6 +1411,9 @@ export declare const Api: {
                     path: z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>;
                     remote: z.ZodOptional<z.ZodPipe<z.ZodArray<z.ZodString>, z.ZodTransform<string, string[]>>>;
                 };
+                cookies: {
+                    val_session: z.ZodOptional<z.ZodString>;
+                };
             };
             res: z.ZodUnion<readonly [z.ZodObject<{
                 status: z.ZodLiteral<401>;

package/dist/declarations/src/internal/search/searchIndex.d.ts

@@ -1,5 +1,4 @@
 import { Json, ModuleFilePath, SerializedSchema, SourcePath } from "@valbuild/core";
-import { Index } from "flexsearch";
 /**
  * The search index and the labels to render for its hits.
  *
@@ -15,8 +14,37 @@ import { Index } from "flexsearch";
  * them — an agent and an editor searching the same project should find the same
  * things.
  */
+/**
+ * The parts of FlexSearch's `Index` this module uses.
+ *
+ * Structural, rather than importing flexsearch's own `Index`, because
+ * {@link SearchIndex} is EXPORTED — and a `.d.ts` that names `flexsearch` pulls
+ * that package's `declare module "flexsearch"` into every consumer's TypeScript
+ * program. Ambient module declarations are global to a program, so a consumer
+ * with its own flexsearch at another version then checks its OWN calls against
+ * the copy we dragged in, whichever of the two wins.
+ *
+ * That is not hypothetical: `@valbuild/shared` gained a flexsearch dependency
+ * in 0.123.0 for `search_content`, and valbuild/web — which pins flexsearch
+ * 0.7 and calls `new flexsearch.Document({ language: "en", … })` — stopped
+ * building on 0.123.2, because 0.8's `DocumentOptions` has no `language`. Its
+ * own resolved copy was still 0.7; only the types had been replaced.
+ *
+ * Three methods is all this module calls, and none of their signatures here is
+ * a guess: `add` and `remove` are used in `indexModule`/`removeModule`, and
+ * `search`'s result is only ever `.length`-ed, `.slice`-d and mapped over as
+ * ids. `FlexSearch.Index` is still constructed with the real library in
+ * {@link createSearchIndex} — a value import, which does not reach the `.d.ts`.
+ */
+type SearchableIndex = {
+    add(id: string, content: string): void;
+    remove(id: string): void;
+    search(query: string, options: {
+        limit: number;
+    }): (string | number)[];
+};
 export type SearchIndex = {
-    index: Index;
+    index: SearchableIndex;
     pathToLabel: Map<string, string>;
     /**
      * Which document ids belong to which module, so one module can be re-indexed
@@ -74,3 +102,4 @@ export type SearchResults = {
     totalIsLowerBound: boolean;
 };
 export declare function performSearch(searchIndex: SearchIndex | null, query: string, limit?: number, offset?: number): SearchResults;
+export {};