@odori/cli 0.0.11 → 0.0.12

package/src/registry-source.ts

@@ -348,4 +348,143 @@ export const verifyIntegrity = (item: RegistryItemDocument, origin: RegistryOrig
   );
 };
 
+/**
+ * Blocks: whole videos, published the same way components are.
+ *
+ * A block is the larger unit — an entry and the files beside it, plus the
+ * components it installs — so it reuses every guarantee this module already
+ * makes rather than growing a second way in: the same index-then-document
+ * split, the same cache, the same integrity hash over the exact bytes a
+ * consumer writes, and the same refusal to write outside the project.
+ *
+ * There is no bundled floor for blocks. The snapshot exists so a locked-down
+ * machine can still install a component and so `odori test` never touches the
+ * network; taking a whole video is a deliberate act on a machine that has one.
+ * A block therefore resolves network → cache and says so when neither answers.
+ */
+export type BlockDocument = {
+  id: string;
+  title: string;
+  description: string;
+  tags: string[];
+  format: string;
+  /** The file to render, relative to the project root. */
+  entry: string;
+  /** Registry components this block imports, by namespaced name. */
+  components: string[];
+  files: Array<{path: string; content: string; target: string}>;
+  meta?: {integrity?: string};
+};
+
+/** The index: every block, without the file contents. */
+export type BlockSummary = Omit<BlockDocument, "files"> & {
+  files: Array<{path: string; target: string}>;
+};
+
+export type BlockIndex = {items: BlockSummary[]; origin: RegistryOrigin; detail: string};
+
+const blocksUnavailable = (url: string): Error =>
+  new Error(
+    `No blocks available: ${url}/blocks.json could not be fetched and nothing is cached on this machine. ` +
+      "Blocks are published rather than bundled, so this needs a network once. " +
+      "Components still install offline.",
+  );
+
+export const resolveBlocks = async (
+  config: ResolvedConfig,
+  options: {allowNetwork?: boolean} = {},
+): Promise<BlockIndex> => {
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), "blocks.json");
+
+  if (options.allowNetwork !== false) {
+    try {
+      const index = (await fetchJson(`${url}/blocks.json`)) as {items: BlockSummary[]};
+      if (!Array.isArray(index.items)) throw new Error("the index has no items array");
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(index), "utf8");
+      return {items: index.items, origin: "network", detail: url};
+    } catch {
+      // As with components: unreachable is not an error until the disk is
+      // empty too.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      const index = JSON.parse(await readFile(cache, "utf8")) as {items: BlockSummary[]};
+      return {items: index.items, origin: "cache", detail: cache};
+    } catch {
+      // A corrupt cache is a cache miss.
+    }
+  }
+
+  throw blocksUnavailable(url);
+};
+
+/** One block, with the source of every file it ships. */
+export const resolveBlock = async (
+  config: ResolvedConfig,
+  id: string,
+  options: {allowNetwork?: boolean} = {},
+): Promise<{block: BlockDocument; origin: RegistryOrigin}> => {
+  assertSafeName(id);
+  const url = registryUrl(config);
+  const cache = resolve(cacheDir(url), `block-${id}.json`);
+
+  if (options.allowNetwork !== false) {
+    try {
+      const block = (await fetchJson(`${url}/blocks/${id}.json`)) as BlockDocument;
+      if (block?.id !== id) throw new Error(`the document at ${url}/blocks/${id}.json is for "${block?.id}"`);
+      await mkdir(dirname(cache), {recursive: true});
+      await writeFile(cache, JSON.stringify(block), "utf8");
+      return {block, origin: "network"};
+    } catch {
+      // Try the disk before giving up.
+    }
+  }
+
+  if (existsSync(cache)) {
+    try {
+      return {block: JSON.parse(await readFile(cache, "utf8")) as BlockDocument, origin: "cache"};
+    } catch {
+      // Corrupt: fall through to the error, which names the whole situation.
+    }
+  }
+
+  throw blocksUnavailable(url);
+};
+
+/**
+ * The same hash components use, over a block's files.
+ *
+ * Integrity proves the bytes and not the intent, which is why every target is
+ * still resolved against the project root before anything is written.
+ */
+export const verifyBlockIntegrity = (block: BlockDocument): void => {
+  const expected = block.meta?.integrity;
+  if (!expected) {
+    throw new Error(
+      `The document for block "${block.id}" carries no integrity hash. ` +
+        "A fetched block must be verifiable; refusing to write it. Nothing was written.",
+    );
+  }
+
+  const hash = createHash("sha256");
+  for (const file of [...block.files].sort((left, right) => left.path.localeCompare(right.path))) {
+    hash.update(file.path);
+    hash.update("\0");
+    hash.update(file.content);
+    hash.update("\0");
+  }
+  const actual = `sha256-${hash.digest("base64")}`;
+  if (actual === expected) return;
+
+  throw new Error(
+    `The files for block "${block.id}" do not match the hash the registry published.\n` +
+      `  expected ${expected}\n  received ${actual}\n` +
+      "Nothing was written. This is a truncated download, a stale proxy, or a tampered document.",
+  );
+};
+
 export type {RegistryItemDocument};

package/src/structure.ts

@@ -0,0 +1,177 @@
+import {readFile} from "node:fs/promises";
+import {existsSync} from "node:fs";
+import {relative, resolve, sep} from "node:path";
+import {resolveEntryLayout} from "odori";
+import type {ResolvedConfig} from "./config";
+import {walkSource, type ProjectGraph} from "./discovery";
+import type {LoadedVideo} from "./project";
+
+/**
+ * A fact about the project's shape that discovery itself cannot say.
+ *
+ * Discovery answers "what exists": it walks the tree and takes what matches.
+ * That is the right behaviour for a build — an unrecognized file must never
+ * take the project down — and exactly the wrong behaviour for an author,
+ * because everything discovery quietly steps over is a file someone wrote on
+ * purpose. The filesystem is Odori's contract: `video.tsx` is a video,
+ * `*.preview.tsx` is a fixture, a directory under components/ names a
+ * component. This module checks the places where that contract can be almost
+ * met, which is the one distance discovery cannot see.
+ *
+ * An `error` is a promise the project makes and breaks at render or play
+ * time: a sound that will be silence, an override that will never be heard.
+ * A `warn` is a file that works today and will surprise someone later.
+ */
+export type StructureFinding = {
+  level: "error" | "warn";
+  /** The file an author would open to fix it, relative to the project root. */
+  file: string;
+  message: string;
+};
+
+/** Entry basenames one keystroke away from meaning something. */
+const NEAR_MISSES: Array<{test: (base: string) => boolean; message: string}> = [
+  {
+    test: (base) => base === "video.ts" || base === "video.jsx",
+    message: "Only video.tsx is a video entry. This file is invisible to discovery: rename it to video.tsx.",
+  },
+  {
+    test: (base) => base.toLowerCase() === "video.tsx" && base !== "video.tsx",
+    message: "Entry names are exact and lower case. This file is invisible to discovery: rename it to video.tsx.",
+  },
+  {
+    test: (base) => /\.preview\.(ts|jsx)$/.test(base),
+    message:
+      "Only *.preview.tsx is a component fixture. This file is invisible to discovery: rename it to end in .preview.tsx.",
+  },
+  {
+    test: (base) => base.toLowerCase().endsWith(".preview.tsx") && !base.endsWith(".preview.tsx"),
+    message:
+      "Fixture names are exact and lower case. This file is invisible to discovery: rename it to end in .preview.tsx.",
+  },
+];
+
+/** String literals that name a file under the served audio library. */
+const AUDIO_REFERENCE = /["'`](\/audio\/[^"'`\s]+\.[a-z0-9]{2,4})["'`]/gi;
+
+/**
+ * Check the filesystem contract and report every place it is almost met.
+ *
+ * Everything here is answerable in Node from the tree and the loaded
+ * metadata: no browser, no network, no render. That is what makes it cheap
+ * enough to run inside `odori doctor` and first inside `odori test`, before
+ * a browser ever starts.
+ */
+export const checkStructure = async (
+  config: ResolvedConfig,
+  graph: ProjectGraph,
+  videos: LoadedVideo[],
+): Promise<StructureFinding[]> => {
+  const findings: StructureFinding[] = [];
+  const videosRoot = resolve(config.root, config.videosDir);
+  const componentsRoot = resolve(config.root, config.componentsDir);
+  const files = existsSync(videosRoot) ? await walkSource(videosRoot) : [];
+
+  // Files one keystroke away from being entries. Discovery is filename
+  // driven, so `video.ts` is not a video with a small problem — it is not a
+  // video at all, and nothing else in the pipeline will ever say so.
+  for (const file of files) {
+    const base = file.split(sep).pop() ?? "";
+    const miss = NEAR_MISSES.find((candidate) => candidate.test(base));
+    if (miss) findings.push({level: "warn", file: relative(config.root, file), message: miss.message});
+  }
+
+  // A fixture named after something other than its directory. The catalog
+  // attributes usage by matching the fixture's name to the directory videos
+  // import from, so a mismatched name previews fine and is credited to
+  // nothing: its "used by" list stays empty forever.
+  for (const preview of graph.previews) {
+    if (!preview.file.startsWith(componentsRoot + sep)) continue;
+    const directory = resolve(preview.file, "..").split(sep).pop() ?? "";
+    if (directory && preview.name !== directory) {
+      findings.push({
+        level: "warn",
+        file: preview.relativeFile,
+        message:
+          `Fixture "${preview.name}" sits in components/${directory}/, so usage is never attributed to it. ` +
+          `Name the fixture after its directory: ${directory}.preview.tsx.`,
+      });
+    }
+  }
+
+  // A literal audio path with no file behind it. The dev server answers 404
+  // and plays on; the export hasher shrugs and warns late. The author finds
+  // out when the cut is silent where the sound was supposed to be.
+  const audioUrls = new Set(graph.audio.map((entry) => entry.url));
+  for (const file of files) {
+    if (!/\.(tsx|ts)$/.test(file)) continue;
+    const contents = await readFile(file, "utf8");
+    const reported = new Set<string>();
+    for (const match of contents.matchAll(AUDIO_REFERENCE)) {
+      const url = match[1];
+      // A template literal with an interpolation is a path decided at
+      // runtime. Only what is written in full can be answered for here.
+      if (url.includes("${") || audioUrls.has(url) || reported.has(url)) continue;
+      reported.add(url);
+      findings.push({
+        level: "error",
+        file: relative(config.root, file),
+        message: `References ${url}, and no file answers it under ${config.audioDir}/. It will play as silence.`,
+      });
+    }
+  }
+
+  // Variant overrides that answer to nothing. A variant replaces brand cues
+  // by name, so a name the brand never defines is an override nothing asks
+  // for, and a file path with no file is a sound that cannot load. Both are
+  // authored intent that the player will quietly ignore.
+  for (const video of videos) {
+    const layout = resolveEntryLayout(video.entry);
+    const brandCues = new Set(Object.keys(layout.brand.audio.cues));
+    for (const [variant, overrides] of Object.entries(video.entry.metadata.audio?.variants ?? {})) {
+      for (const [cue, value] of Object.entries(overrides)) {
+        if (!brandCues.has(cue)) {
+          findings.push({
+            level: "warn",
+            file: video.relativeFile,
+            message:
+              `Variant "${variant}" overrides a cue named "${cue}" that the brand "${layout.brand.name}" does not define. ` +
+              `Nothing plays that name, so the override is never heard.`,
+          });
+        }
+        if (typeof value === "string" && value.startsWith("/") && !audioUrls.has(value)) {
+          findings.push({
+            level: "error",
+            file: video.relativeFile,
+            message: `Variant "${variant}" points cue "${cue}" at ${value}, and no file answers it under ${config.audioDir}/.`,
+          });
+        }
+      }
+    }
+  }
+
+  // A compiled catalog that no longer describes the tree. Anything that
+  // reads the artifact instead of running discovery — an agent, a CI step,
+  // another tool — would be reading yesterday's project as if it were today's.
+  const catalogFile = resolve(config.root, config.outDir, "catalog.json");
+  if (existsSync(catalogFile)) {
+    try {
+      const catalog = JSON.parse(await readFile(catalogFile, "utf8")) as {sourceHash?: string};
+      if (catalog.sourceHash && catalog.sourceHash !== graph.sourceHash) {
+        findings.push({
+          level: "warn",
+          file: relative(config.root, catalogFile),
+          message: "The compiled catalog is older than the source tree. Run odori graph (or odori dev) to refresh it.",
+        });
+      }
+    } catch {
+      findings.push({
+        level: "warn",
+        file: relative(config.root, catalogFile),
+        message: "The compiled catalog is not valid JSON. Run odori graph (or odori dev) to rewrite it.",
+      });
+    }
+  }
+
+  return findings;
+};