@valbuild/server 0.146.4 → 0.148.0

package/dist/declarations/src/remoteFileCheck.d.ts

@@ -0,0 +1,116 @@
+import { MediaSource, SerializedSchema, SourcePath, ValidationError } from "@valbuild/core";
+import { type AskHostProject } from "./remoteHostCheck.js";
+/**
+ * Does the host a remote ref names still serve it?
+ *
+ * `found` and `missing` are the host's answer. `unreachable` is no answer at
+ * all — a timeout, a refused connection, a 5xx — and says nothing about the
+ * file, only about the host.
+ */
+export type RemoteFileAnswer = {
+    status: "found";
+} | {
+    status: "missing";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+};
+export type HeadRemoteFile = (url: string) => Promise<RemoteFileAnswer>;
+/**
+ * How the remote check reaches the network: what it asks a host about a file,
+ * and which project a platform host serves. Both default to the real thing;
+ * tests replace them.
+ */
+export type RemoteNetwork = {
+    head?: HeadRemoteFile;
+    askHostProject?: AskHostProject;
+};
+/**
+ * A HEAD, falling back to the first byte of a GET for a host that does not
+ * answer HEAD (405, 501): either way no file is downloaded to learn that it is
+ * there.
+ */
+export declare const headRemoteFile: HeadRemoteFile;
+/** For tests: forget every answer. */
+export declare function clearRemoteFileAnswers(): void;
+/** A host that did not serve the refs of a module it was asked about. */
+export type RemoteHostProblem = {
+    /** `https://remote.val.build`, as the ref names it. */
+    host: string;
+    status: "missing" | "unreachable";
+    /** What the host answered, for "Details": never the row's sentence. */
+    details: string;
+    /** Every ref on that host in the module, checked or vouched for. */
+    sourcePaths: SourcePath[];
+};
+export type RemoteFilesCheck = {
+    /** Wrong refs, one by one: each has its own row. */
+    errors: Record<SourcePath, ValidationError[]>;
+    /** Hosts that failed: one row each, however many refs they cover. */
+    hosts: RemoteHostProblem[];
+};
+export type RemoteFilesCheckInput = {
+    /** What `validateSources` set aside as remote: every remote media value. */
+    remoteFiles: Record<SourcePath, MediaSource>;
+    /** The serialized schema at a path, or undefined when it does not resolve. */
+    schemaAt: (sourcePath: SourcePath) => SerializedSchema | undefined;
+    /**
+     * Does this ref have its bytes in a pending patch? They go to the remote
+     * host at publish, so until then asking the host for it is asking a
+     * question whose answer is "not yet".
+     */
+    pendingBytes: (ref: string) => Promise<"present" | "missing" | "not-pending">;
+    /**
+     * Is this value's ref the one already published at this path? Only those
+     * may be vouched for by another ref on the same host; see `sampleByHost`.
+     */
+    isPublished: (sourcePath: SourcePath, ref: string) => boolean;
+    /**
+     * Ask one published ref per host and take its answer for the rest.
+     *
+     * Right for a managed project, whose refs are only ever written by the
+     * Studio and whose host changes for every ref at once. Wrong for a connected
+     * one, where a developer can edit any single ref by hand. See
+     * `docs/plans/studio-validate.md`, "Remote refs in the full check".
+     */
+    sampleByHost: boolean;
+    /**
+     * Ask only whether the host serves each ref. For the keys of a media
+     * directory: what is recorded about the file is the entry, not a value at
+     * the path, and the ref's hash was made from a schema the directory
+     * synthesizes for it, so there is no schema here to judge it by.
+     */
+    existenceOnly?: boolean;
+    head?: HeadRemoteFile;
+    /** How a platform ref's host is asked which project it serves. */
+    askHostProject?: AskHostProject;
+};
+/**
+ * The remote half of the Studio's full check, for one module's remote values.
+ *
+ * Four questions, cheapest first, and a ref stops at the first one it fails:
+ *
+ * 1. **Is it a ref at all?** `splitRemoteRef` parses it.
+ * 2. **Does the ref agree with what is recorded about it?** A ref carries a
+ *    hash of the schema's options, the file's extension and its width, height
+ *    and mime type. When the value or the schema changed and the ref did not,
+ *    the ref is stale, and **Fix** (`image:check-remote`) re-reads the file and
+ *    writes the ref it should have. Computed with the ref's OWN core version:
+ *    the CLI also re-derives every ref after a Val upgrade, and listing every
+ *    remote image in the project after each upgrade would bury the rows that
+ *    matter. Nothing here downloads.
+ * 3. **Does its host still serve its project?** Only for a platform ref
+ *    (`…/_val/file/…`) that is not on the project's own `valstart.dev`
+ *    address: one `GET <host>/_val/project` per host. A host that dropped the
+ *    project gets a **Fix** (`remote:rewrite-host`) that points the ref at
+ *    `<public id>.valstart.dev`. See `remoteHostCheck.ts`.
+ * 4. **Does the host have it?** A HEAD.
+ *
+ * Neither host question is asked of a ref whose bytes are in a pending patch,
+ * which the host will not have until publish: there the question is whether
+ * the patch still has them.
+ */
+export declare function checkRemoteFiles(input: RemoteFilesCheckInput): Promise<RemoteFilesCheck>;
+/** `www.acme.no`, from `https://www.acme.no`: how a person names a host. */
+export declare function hostName(host: string): string;

package/dist/declarations/src/remoteHostCheck.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Does the host a platform ref names still serve the project the ref names?
+ *
+ * A ref served by the platform loader names the project's host at the time
+ * the file was added: `https://www.acme.no/_val/file/p/3f9a2c1/…`. When the
+ * project drops `www.acme.no`, the bytes are still there, at
+ * `3f9a2c1.valstart.dev`, but every ref that names the old domain points at a
+ * host that no longer serves them. This is the question that finds those refs,
+ * and `rewriteRefHost` is what the fix (`remote:rewrite-host`) does about it.
+ * See valbuild/home `docs/remote-files-on-platform.md`, "Rewriting refs after a
+ * domain is removed", and `docs/plans/studio-validate.md`, step 6.
+ *
+ * Asked of the host itself (`GET <host>/_val/project`), not of content: the
+ * host's answer covers DNS, the certificate and the loader's mapping in one,
+ * it needs no credential, and it works for a ref that names a project other
+ * than this one -- a project seeded from a template has refs naming the
+ * template's.
+ */
+/** The domain every platform project is always served at, by its public id. */
+export declare const PLATFORM_SITES_DOMAIN = "valstart.dev";
+/**
+ * The host every platform ref of `publicProjectId` can always be pointed at:
+ * `<public id>.valstart.dev` is permanent (decision 4 of the remote-files
+ * plan), and the loader serves a project's files there whatever else it has.
+ */
+export declare function fallbackRemoteHost(publicProjectId: string): string;
+/**
+ * Only a platform ref is asked about. `remote.val.build` is not a platform
+ * host and is not going away, and a ref already on the project's own
+ * `valstart.dev` address is on the fallback, which always serves it.
+ */
+export declare function needsHostCheck(remoteHost: string, projectId: string): boolean;
+/** `ref` with its host part replaced, and everything else as it was. */
+export declare function rewriteRefHost(ref: string, remoteHost: string): string | null;
+/**
+ * - `serves`: the host answered for the project the ref names.
+ * - `other-project`: it answered, for another one -- the domain was moved to
+ *   a different project, and decision 5 means it will not serve these files.
+ * - `no-site`: it answered, but serves no project at all (the loader's 404 for
+ *   a domain nobody has mapped any more).
+ * - `unreachable`: no answer. A domain whose DNS was removed looks like this,
+ *   and so does a host that is down for a minute, which is why the row says
+ *   which it saw.
+ */
+export type HostServes = {
+    status: "serves";
+} | {
+    status: "other-project";
+    publicProjectId: string;
+} | {
+    status: "no-site";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+};
+export type AskHostProject = (remoteHost: string) => Promise<{
+    status: "answered";
+    publicProjectId: string;
+} | {
+    status: "no-site";
+    httpStatus: number;
+} | {
+    status: "unreachable";
+    reason: string;
+}>;
+/** `GET <host>/_val/project`, answered by the platform loader. */
+export declare const askHostProject: AskHostProject;
+export declare function clearHostAnswers(): void;
+export declare function hostServes(remoteHost: string, projectId: string, ask?: AskHostProject): Promise<HostServes>;
+/**
+ * `ask`, asking each host once for as long as the returned function is kept:
+ * one check, not the life of the server. A check walks its refs in order, so
+ * without it every ref on a host that does not answer waits out its own
+ * timeout -- 150 images on a dead domain is 20 minutes. Kept per check rather
+ * than in {@link hostServes}'s cache because a host that did not answer has
+ * to be asked again by the next one.
+ */
+export declare function askOncePerHost(ask?: AskHostProject): AskHostProject;
+/** `www.acme.no`, from `https://www.acme.no/_val`: how a person names a host. */
+export declare function hostNameOfRemoteHost(remoteHost: string): string;
+/**
+ * Where a platform ref has to move to, when its host no longer serves the
+ * project it names; `undefined` when it does not have to (or is not a
+ * platform ref). `why` and `to` are for the caller's sentence: what can be
+ * done about it differs by caller (a Studio **Fix**, `val validate --fix`, or
+ * nothing yet).
+ */
+export declare function movedRemoteHost(ref: string, ask?: AskHostProject): Promise<{
+    ref: string;
+    why: string;
+    to: string;
+} | undefined>;
+/**
+ * Where else a ref's file can be downloaded from: the same file on the
+ * project's own `valstart.dev` address, for a platform ref on any other host.
+ * `null` when there is nowhere else -- a `remote.val.build` ref, or one already
+ * on the fallback. See valbuild/home `docs/remote-files-on-platform.md`,
+ * "Tooling: the fallback".
+ */
+export declare function fallbackRefOf(ref: string): string | null;

package/dist/declarations/src/studioValidation.d.ts

@@ -0,0 +1,84 @@
+import { ModuleFilePath, SourcePath, ValidationError, ValidationFix } from "@valbuild/core";
+import type { Patch } from "@valbuild/core/patch";
+import { FixPatchRemainingError } from "./createFixPatch.js";
+import type { FixFiles } from "./fixFiles.js";
+import { type RemoteHostProblem, type RemoteNetwork } from "./remoteFileCheck.js";
+import { type PatchAnalysis, type Schemas, type Sources, type ValOps } from "./ValOps.js";
+/**
+ * The Studio's full check, one module at a time: what `/validate` and
+ * `/validate/fix` answer with. See `docs/plans/studio-validate.md`.
+ *
+ * Both take the sources the caller is looking at — base plus the patches it
+ * names — so an error is about the content on the editor's screen, and a fix
+ * is a patch on top of it.
+ */
+export type StudioCheckInput = {
+    moduleFilePath: ModuleFilePath;
+    schemas: Schemas;
+    sources: Sources;
+    fileLastUpdatedByPatchId: PatchAnalysis["fileLastUpdatedByPatchId"];
+    /** How remote hosts are asked about refs. Tests replace it. */
+    network?: RemoteNetwork;
+};
+export type StudioModuleCheck = {
+    status: "ok";
+    errors: Record<SourcePath, ValidationError[]>;
+    /** Hosts that did not serve this module's remote files. */
+    remoteHosts: RemoteHostProblem[];
+} | {
+    status: "unknown-module";
+} | {
+    status: "invalid-source";
+    message: string;
+};
+/**
+ * Every error in one module: its sources against its schema, and its local
+ * files against their bytes.
+ *
+ * Not filtered the way the publish gate filters (`partitionValidationErrors`):
+ * the errors the gate hides because "the server repairs them on save" are the
+ * ones this check exists to show, since nothing repairs them in http mode.
+ *
+ * Remote files are checked too: a stale ref is an error with a fix, and a
+ * host that does not serve them is reported once, as a host, rather than as
+ * an error on every image it holds (`checkRemoteFiles`).
+ *
+ * Not yet here: the media directories' own entries, step 5 of the plan.
+ */
+export declare function checkModuleForStudio(ops: ValOps, input: StudioCheckInput): Promise<StudioModuleCheck>;
+export type StudioFixResult = {
+    status: "ok";
+    patch: Patch;
+    remainingErrors: FixPatchRemainingError[];
+} | {
+    status: "unknown-module";
+} | {
+    status: "not-in-studio";
+} | {
+    status: "not-found";
+};
+/**
+ * The patch that fixes one error, built from the server's own reading of the
+ * module rather than from the error the caller saw.
+ *
+ * The caller names the error by where it is and which fix it wants; the error
+ * itself is found again here. That is what keeps a stale or hand-written
+ * request from steering `createFixPatch` (CLAUDE.md, "Adding a ValidationFix
+ * code"), and it is what lets an error reported at a FIELD be fixed at the
+ * media value it belongs to: `validateFiles` reports a wrong width at
+ * `…"hero"."width"`, while the fix rewrites `…"hero"`.
+ *
+ * Only {@link isStudioFix} codes are built. The others need a disk or a
+ * remote host this server may not have, and are the CLI's for now.
+ */
+export declare function fixForStudio(ops: ValOps, input: StudioCheckInput & {
+    sourcePath: SourcePath;
+    fix: ValidationFix;
+}): Promise<StudioFixResult>;
+/**
+ * {@link FixFiles} over whatever store this server has: the disk in fs mode,
+ * the content service in http mode. A file a pending patch wrote is read from
+ * that patch, as `validateFiles` reads it, so a fix is made from the bytes
+ * the check was made from.
+ */
+export declare function opsFixFiles(ops: ValOps, fileLastUpdatedByPatchId: PatchAnalysis["fileLastUpdatedByPatchId"]): FixFiles;

package/dist/declarations/src/uploadRemoteFile.d.ts

@@ -1,4 +1,4 @@
-export declare function uploadRemoteFile(contentHost: string, project: string, bucket: string, fileHash: string, fileExt: string, fileBuffer: Buffer, auth: {
+export declare function uploadRemoteFile(contentHost: string, project: string, bucket: string, fileHash: string, fileExt: string, fileBuffer: Uint8Array, auth: {
     pat: string;
 } | {
     apiKey: string;

package/dist/declarations/src/videosetFixes.d.ts

@@ -1,6 +1,7 @@
 import { type ModuleFilePath, type SerializedRecordSchema, type SerializedSchema, type SerializedVideoSchema, type Source, type SourcePath, type ValidationError } from "@valbuild/core";
 import { type Patch } from "@valbuild/core/patch";
 import type { FixPatchRemainingError } from "./createFixPatch.js";
+import type { FixFiles } from "./fixFiles.js";
 import type { FixHandlerContext, FixHandlerResult, ModulePatch } from "./fixHandlers.js";
 import { type GalleryEntryKey } from "./galleryEntryKey.js";
 import type { Service } from "./Service.js";
@@ -129,8 +130,8 @@ export declare function videosetCheckAllFilesPatch({ projectRoot, apply, sourceP
  * from the file at the entry's KEY, and write only that, one op per field —
  * `alt` and anything already there are someone's, and stay.
  */
-export declare function videosetAddMetadataPatch({ projectRoot, sourcePath, validationError, moduleSource, moduleSchema, }: {
-    projectRoot: string;
+export declare function videosetAddMetadataPatch({ files, sourcePath, validationError, moduleSource, moduleSchema, }: {
+    files: FixFiles;
     sourcePath: SourcePath;
     validationError: ValidationError;
     moduleSource: Source | undefined;

package/dist/getJsonEntryAtCommit-2e36e805.cjs.prod.js

@@ -0,0 +1,142 @@
+'use strict';
+
+var ts = require('typescript');
+var ValRouterCore = require('./ValRouterCore-42772c21.cjs.prod.js');
+var fp = require('@valbuild/core/fp');
+var jsonValuesModule = require('./jsonValuesModule-d1bb8d8f.cjs.prod.js');
+require('@valbuild/core');
+require('@valbuild/shared/internal');
+require('zod');
+require('zod-validation-error');
+require('@valbuild/core/patch');
+require('image-size');
+
+function _interopDefault (e) { return e && e.__esModule ? e : { 'default': e }; }
+
+var ts__default = /*#__PURE__*/_interopDefault(ts);
+
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (fp.result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (fp.result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, ValRouterCore.bytesToUtf8(moduleRes.value), key);
+  if (fp.result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (fp.result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (fp.result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return fp.result.ok(JSON.parse(ValRouterCore.bytesToUtf8(entryRes.value)));
+  } catch (err) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts__default["default"].createSourceFile(moduleFilePath, valTsSource, ts__default["default"].ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = jsonValuesModule.analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (fp.result.isErr(analysis)) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = jsonValuesModule.analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = ValRouterCore.posixPath.dirname(moduleFilePath);
+  return fp.result.ok(ValRouterCore.posixPath.join(moduleDir, entry.importPath));
+}
+
+exports.findEntryImportPath = findEntryImportPath;
+exports.getJsonEntryAtCommit = getJsonEntryAtCommit;

package/dist/getJsonEntryAtCommit-40b6d9c1.esm.js

@@ -0,0 +1,135 @@
+import ts from 'typescript';
+import { F as bytesToUtf8, G as posixPath } from './ValRouterCore-7ca3dc68.esm.js';
+import { result } from '@valbuild/core/fp';
+import { a as analyzeValModule, c as analyzeJsonValuesEntries } from './jsonValuesModule-427d68c8.esm.js';
+import '@valbuild/core';
+import '@valbuild/shared/internal';
+import 'zod';
+import 'zod-validation-error';
+import '@valbuild/core/patch';
+import 'image-size';
+
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, bytesToUtf8(moduleRes.value), key);
+  if (result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return result.ok(JSON.parse(bytesToUtf8(entryRes.value)));
+  } catch (err) {
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts.createSourceFile(moduleFilePath, valTsSource, ts.ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (result.isErr(analysis)) {
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = posixPath.dirname(moduleFilePath);
+  return result.ok(posixPath.join(moduleDir, entry.importPath));
+}
+
+export { findEntryImportPath, getJsonEntryAtCommit };