@valbuild/cli 0.150.0 → 0.150.1

package/src/validate.ts

@@ -12,13 +12,29 @@ import {
   type SourceFileCache,
 } from "./utils/sourcePathToFileLocation";
 
-type Diagnostic = {
-  // "fixable" => ⚠ (run --fix), "error" => ✘
-  severity: "fixable" | "error";
-  sourcePath: string;
-  message: string;
-  keyError?: boolean;
-};
+type Diagnostic =
+  | {
+      // Both are errors (✘) and count towards the exit code; "fixable" adds
+      // "run --fix".
+      severity: "fixable" | "error";
+      sourcePath: string;
+      message: string;
+      keyError?: boolean;
+    }
+  | {
+      // ⚠: printed, grouped by message, and counted only under --strict.
+      severity: "warning";
+      sourcePath: string;
+      message: string;
+      files: string[];
+      hint?: string;
+      keyError?: boolean;
+    };
+
+type WarningDiagnostic = Extract<Diagnostic, { severity: "warning" }>;
+
+/** How many of a warning group's files are listed before "… N more". */
+const WARNING_FILES_SHOWN = 5;
 
 type ModuleReport = {
   // Relative file path (no leading slash).
@@ -31,10 +47,13 @@ export async function validate({
   root,
   fix,
   watch,
+  strict,
 }: {
   root?: string;
   fix?: boolean;
   watch?: boolean;
+  /** Fail on warnings too. */
+  strict?: boolean;
 }) {
   const projectRoot = root ? path.resolve(root) : process.cwd();
 
@@ -45,7 +64,13 @@ export async function validate({
     console.log("Prettier not found, skipping formatting");
   }
 
-  const runOnce = () => validateOnce({ projectRoot, fix: !!fix, prettier });
+  const runOnce = () =>
+    validateOnce({
+      projectRoot,
+      fix: !!fix,
+      prettier,
+      ...(strict ? { strict: true } : {}),
+    });
 
   if (!watch) {
     const totalErrors = await runOnce();
@@ -60,7 +85,7 @@ export async function validate({
 
 /**
  * One validation pass over the project, printed as `val validate` prints it,
- * returning the number of errors found.
+ * returning the number of errors found -- and of warnings, under `strict`.
  *
  * Re-reads config and val files on each call so it always reflects the latest
  * state on disk: `val validate` calls it once or on every change (`--watch`),
@@ -71,6 +96,7 @@ export async function validateOnce({
   fix,
   prettier,
   blockingOnly = false,
+  strict = false,
 }: {
   projectRoot: string;
   fix: boolean;
@@ -82,6 +108,12 @@ export async function validateOnce({
    * what `val publish` refuses on. Every error is still printed.
    */
   blockingOnly?: boolean;
+  /**
+   * Count warnings as errors (`--strict`). A warning is a local file in a
+   * project that stores files remotely: see `WARNING_FIXES` in
+   * `@valbuild/shared`.
+   */
+  strict?: boolean;
 }): Promise<number> {
   const valConfigFile = await findAndEvalValConfigFile(projectRoot);
 
@@ -109,6 +141,7 @@ export async function validateOnce({
 
   const fixedFiles = new Set<string>();
   let totalErrors = 0;
+  let totalWarnings = 0;
   let repairedOnSave = 0;
 
   // Caches each val file's parsed source so files are read/parsed at most once
@@ -163,10 +196,15 @@ export async function validateOnce({
   })) {
     switch (event.type) {
       case "file-valid":
-        valid.push({
-          file: relFile(event.file),
-          durationMs: event.durationMs,
-        });
+        // No errors, but it may have warnings: then it is shown with them.
+        if (reports.has(relFile(event.file))) {
+          reportFor(event.file).durationMs = event.durationMs;
+        } else {
+          valid.push({
+            file: relFile(event.file),
+            durationMs: event.durationMs,
+          });
+        }
         break;
       case "file-error-count":
         reportFor(event.file).durationMs = event.durationMs;
@@ -190,6 +228,17 @@ export async function validateOnce({
           ...(event.keyError ? { keyError: true } : {}),
         });
         break;
+      case "validation-warning":
+        totalWarnings += 1;
+        reportFor(moduleOf(event.sourcePath)).diagnostics.push({
+          severity: "warning",
+          sourcePath: event.sourcePath,
+          message: event.message,
+          files: event.files,
+          ...(event.hint !== undefined ? { hint: event.hint } : {}),
+          ...(event.keyError ? { keyError: true } : {}),
+        });
+        break;
       case "unknown-fix":
         reportFor(moduleOf(event.sourcePath)).diagnostics.push({
           severity: "error",
@@ -249,42 +298,94 @@ export async function validateOnce({
 
   // Renders a module's diagnostics under a single left "│" gutter bar, with the
   // file name on top and blank gutter lines for air. Output flows least- to
-  // most-actionable top-to-bottom, so fixable diagnostics are shown last (at the
-  // bottom, nearest the prompt).
+  // most-actionable top-to-bottom: warnings first, then errors, and fixable
+  // errors last (at the bottom, nearest the prompt).
   const renderModule = (report: ModuleReport) => {
     const bar = picocolors.dim("│");
-    const diagnostics = [...report.diagnostics].sort((a, b) =>
-      a.severity === b.severity ? 0 : a.severity === "fixable" ? 1 : -1,
+    const rank: Record<Diagnostic["severity"], number> = {
+      warning: 0,
+      error: 1,
+      fixable: 2,
+    };
+    const diagnostics = [...report.diagnostics].sort(
+      (a, b) => rank[a.severity] - rank[b.severity],
     );
+    const warningCount = diagnostics.filter(
+      (d) => d.severity === "warning",
+    ).length;
     const fixableCount = diagnostics.filter(
       (d) => d.severity === "fixable",
     ).length;
-    const total = diagnostics.length;
-    const hasError = fixableCount < total;
-    const symbol = hasError ? picocolors.red("✘") : picocolors.yellow("⚠");
-    let label: string;
-    if (fixableCount === total) {
-      label = `${fixableCount} fixable`;
-    } else if (fixableCount > 0) {
-      label = `${total} error${total > 1 ? "s" : ""} (${fixableCount} fixable)`;
-    } else {
-      label = `${total} error${total > 1 ? "s" : ""}`;
+    const errorCount = diagnostics.length - warningCount;
+    const symbol =
+      errorCount > 0 ? picocolors.red("✘") : picocolors.yellow("⚠");
+    const labels: string[] = [];
+    if (errorCount > 0) {
+      labels.push(
+        `${errorCount} error${errorCount > 1 ? "s" : ""}${
+          fixableCount > 0 ? ` (${fixableCount} fixable)` : ""
+        }`,
+      );
+    }
+    if (warningCount > 0) {
+      labels.push(`${warningCount} warning${warningCount > 1 ? "s" : ""}`);
     }
     console.log(
-      `${picocolors.bold(report.file)}  ${symbol} ${label}  ${picocolors.dim(
+      `${picocolors.bold(report.file)}  ${symbol} ${labels.join(" · ")}  ${picocolors.dim(
         `(${report.durationMs}ms)`,
       )}`,
     );
-    for (const d of diagnostics) {
-      const target = d.keyError ? "key" : "value";
-      const dsym =
-        d.severity === "fixable" ? picocolors.yellow("⚠") : picocolors.red("✘");
-      const parts = sourcePathToLocationParts(
+    const locationOf = (d: Diagnostic) =>
+      sourcePathToLocationParts(
         d.sourcePath,
         projectRoot,
         sourceFileCache,
-        target,
+        d.keyError ? "key" : "value",
       );
+
+    // Warnings say the same thing about many values (every local image in a
+    // gallery), so each message is printed once, over the places it is about.
+    const warningGroups = new Map<string, WarningDiagnostic[]>();
+    for (const d of diagnostics) {
+      if (d.severity !== "warning") continue;
+      const group = warningGroups.get(d.message);
+      if (group) {
+        group.push(d);
+      } else {
+        warningGroups.set(d.message, [d]);
+      }
+    }
+    for (const [message, group] of warningGroups) {
+      console.log(bar);
+      console.log(`${bar}  ${picocolors.yellow("⚠")}  ${message}`);
+      console.log(bar);
+      for (const d of group.slice(0, WARNING_FILES_SHOWN)) {
+        const parts = locationOf(d);
+        const files = d.files.join(", ");
+        // `file:line:col` first, so VS Code's terminal links it.
+        const where = parts
+          ? `${parts.relativeFile}:${parts.line}:${parts.character}`
+          : d.sourcePath;
+        console.log(`${bar}     ${where}  ${picocolors.dim(files)}`);
+      }
+      if (group.length > WARNING_FILES_SHOWN) {
+        console.log(
+          `${bar}     ${picocolors.dim(
+            `… ${group.length - WARNING_FILES_SHOWN} more`,
+          )}`,
+        );
+      }
+      const hint = group.find((d) => d.hint !== undefined)?.hint;
+      if (hint !== undefined) {
+        console.log(bar);
+        console.log(`${bar}     ${picocolors.dim(`→ ${hint}`)}`);
+      }
+    }
+
+    for (const d of diagnostics) {
+      if (d.severity === "warning") continue;
+      const parts = locationOf(d);
+      const dsym = picocolors.red("✘");
       console.log(bar);
       if (parts) {
         // `file:line:col` (no key/value label) so VS Code's terminal links it.
@@ -299,7 +400,7 @@ export async function validateOnce({
         d.sourcePath,
         projectRoot,
         sourceFileCache,
-        target,
+        d.keyError ? "key" : "value",
       );
       if (frame !== undefined) {
         console.log(bar);
@@ -340,13 +441,17 @@ export async function validateOnce({
 
   // Render the grouped report least- to most-actionable, top-to-bottom, so the
   // most important things end up at the bottom nearest the prompt: valid files
-  // and skipped modules first, then error-only modules, then fixable modules.
+  // and skipped modules first, then warning-only modules, then error-only
+  // modules, then fixable modules.
   const allReports = [...reports.values()];
+  const hasErrors = (r: ModuleReport) =>
+    r.diagnostics.some((d) => d.severity !== "warning");
+  const warningModules = allReports.filter((r) => !hasErrors(r));
   const fixableModules = allReports.filter((r) =>
     r.diagnostics.some((d) => d.severity === "fixable"),
   );
   const errorModules = allReports.filter(
-    (r) => !r.diagnostics.some((d) => d.severity === "fixable"),
+    (r) => hasErrors(r) && !r.diagnostics.some((d) => d.severity === "fixable"),
   );
 
   for (const v of valid) {
@@ -365,7 +470,11 @@ export async function validateOnce({
   if (allReports.length > 0) {
     console.log("");
   }
-  for (const report of [...errorModules, ...fixableModules]) {
+  for (const report of [
+    ...warningModules,
+    ...errorModules,
+    ...fixableModules,
+  ]) {
     renderModule(report);
   }
 
@@ -373,32 +482,51 @@ export async function validateOnce({
     (n, r) => n + r.diagnostics.filter((d) => d.severity === "fixable").length,
     0,
   );
+  const errorFiles = allReports.filter(hasErrors).length;
+  const warningFiles = allReports.filter((r) =>
+    r.diagnostics.some((d) => d.severity === "warning"),
+  ).length;
+  const plural = (n: number, word: string) =>
+    `${n} ${word}${n === 1 ? "" : "s"}`;
+  const warnings = `${plural(totalWarnings, "warning")} in ${plural(warningFiles, "file")}`;
+  const warningPart =
+    totalWarnings > 0
+      ? `${warnings}${strict ? ", which --strict counts as errors" : ""}`
+      : undefined;
+  const tail = [
+    ...(valid.length > 0 ? [`${valid.length} valid`] : []),
+    ...(skipped.length > 0 ? [`${skipped.length} skipped`] : []),
+  ];
   if (totalErrors > 0) {
-    let summary = `${totalErrors} error${totalErrors > 1 ? "s" : ""}`;
+    let summary = plural(totalErrors, "error");
     if (fixableTotal > 0) {
       summary += ` (${fixableTotal} fixable)`;
     }
-    summary += ` across ${allReports.length} file${
-      allReports.length > 1 ? "s" : ""
-    }`;
-    if (valid.length > 0) {
-      summary += ` · ${valid.length} valid`;
-    }
-    if (skipped.length > 0) {
-      summary += ` · ${skipped.length} skipped`;
-    }
-    console.log(picocolors.red("✘"), summary);
+    summary += ` across ${plural(errorFiles, "file")}`;
+    console.log(
+      picocolors.red("✘"),
+      [summary, ...(warningPart ? [warningPart] : []), ...tail].join(" · "),
+    );
+  } else if (warningPart && strict) {
+    // Not "No validation errors" beside a ✘: under --strict this run failed,
+    // and the warnings are why.
+    console.log(
+      picocolors.red("✘"),
+      [`${warnings}, and --strict fails on warnings`, ...tail].join(" · "),
+    );
+  } else if (warningPart) {
+    console.log(
+      picocolors.green("✔"),
+      ["No validation errors", warningPart, ...tail].join(" · "),
+    );
   } else {
-    let summary = "No validation errors found";
-    if (valid.length > 0) {
-      summary += ` · ${valid.length} valid`;
-    }
-    if (skipped.length > 0) {
-      summary += ` · ${skipped.length} skipped`;
-    }
-    console.log(picocolors.green("✔"), summary);
+    console.log(
+      picocolors.green("✔"),
+      ["No validation errors found", ...tail].join(" · "),
+    );
   }
-  return blockingOnly ? totalErrors - repairedOnSave : totalErrors;
+  const errors = blockingOnly ? totalErrors - repairedOnSave : totalErrors;
+  return strict ? errors + totalWarnings : errors;
 }
 
 // Directory names anywhere in the path that should never be watched.

package/src/validate.warnings.test.ts

@@ -0,0 +1,170 @@
+import { describe, test, expect, beforeEach, afterEach } from "@jest/globals";
+import path from "path";
+import fs from "fs";
+import { validateOnce } from "./validate";
+
+/**
+ * A local file in a project with remote files is a WARNING: `val validate`
+ * prints it and passes, `--strict` makes it fail. Every project made from a
+ * template starts this way, hosted ones included, and the site serves those
+ * files from public/ until they are uploaded.
+ */
+
+const BASIC_FIXTURE = path.resolve(__dirname, "__fixtures__/basic");
+
+const PNG = Buffer.from(
+  "iVBORw0KGgoAAAANSUhEUgAAAAgAAAAIAQMAAAD+wSzIAAAABlBMVEX/AAD//" +
+    "/+l2Z/dAAAAAWJLR0QAiAUdSAAAAAlwSFlzAAALEwAACxMBAJqcGAAAAAd0SU1FB9oIBRELLnJqTAAAAAxJREFUCNdjYGBgAAAABAABJzQnCgAAAABJRU5ErkJggg==",
+  "base64",
+);
+
+const IMAGES = Array.from(
+  { length: 7 },
+  (_, i) => `/public/val/images/image-${i}_0000${i}.png`,
+);
+
+const PROJECT: Record<string, string | Buffer> = {
+  "val.modules.ts": `import { modules } from "@valbuild/core";
+import { config } from "./val.config";
+
+export default modules(config, [
+  { def: () => import("./content/images.val") },
+]);
+`,
+  "content/images.val.ts": `import { c, s } from "../val.config";
+
+export default c.define(
+  "/content/images.val.ts",
+  s.imagedir("/public/val/images").remote(),
+  {
+${IMAGES.map(
+  (image) =>
+    `    "${image}": { width: 8, height: 8, mimeType: "image/png", alt: null },`,
+).join("\n")}
+  },
+);
+`,
+  ...Object.fromEntries(IMAGES.map((image) => [image.slice(1), PNG])),
+};
+
+describe("val validate: a local file in a project with remote files", () => {
+  let root: string;
+  let output: string[];
+  let log: jest.SpyInstance;
+
+  beforeEach(() => {
+    const tmpBase = path.join(__dirname, "..", ".tmp");
+    fs.mkdirSync(tmpBase, { recursive: true });
+    root = fs.mkdtempSync(path.join(tmpBase, "warnings-"));
+    for (const file of ["val.config.ts", "tsconfig.json"]) {
+      fs.copyFileSync(path.join(BASIC_FIXTURE, file), path.join(root, file));
+    }
+    for (const [file, content] of Object.entries(PROJECT)) {
+      fs.mkdirSync(path.dirname(path.join(root, file)), { recursive: true });
+      fs.writeFileSync(path.join(root, file), content);
+    }
+    output = [];
+    log = jest.spyOn(console, "log").mockImplementation((...args) => {
+      output.push(args.join(" "));
+    });
+  });
+
+  afterEach(() => {
+    log.mockRestore();
+    fs.rmSync(root, { recursive: true, force: true });
+  });
+
+  // eslint-disable-next-line no-control-regex
+  const plain = () => output.join("\n").replace(/\u001b\[[0-9;]*m/g, "");
+
+  test("is printed once, over every file it is about, and passes", async () => {
+    expect(await validateOnce({ projectRoot: root, fix: false })).toBe(0);
+    const text = plain();
+    expect(text).toContain("content/images.val.ts  ⚠ 7 warnings");
+    expect(
+      text.match(/Local files in a project with remote files/g),
+    ).toHaveLength(1);
+    expect(text).toContain(IMAGES[0]);
+    expect(text).toContain("… 2 more");
+    expect(text).toContain("→ val validate --fix uploads them");
+    expect(text).toContain("✔ No validation errors · 7 warnings in 1 file");
+  });
+
+  test("fails under --strict", async () => {
+    expect(
+      await validateOnce({ projectRoot: root, fix: false, strict: true }),
+    ).toBe(7);
+    const text = plain();
+    expect(text).toContain(
+      "✘ 7 warnings in 1 file, and --strict fails on warnings",
+    );
+    // Not "passed" and "failed" in one line.
+    expect(text).not.toContain("No validation errors");
+  });
+
+  test("does not hold back val publish, unless --strict", async () => {
+    expect(
+      await validateOnce({ projectRoot: root, fix: false, blockingOnly: true }),
+    ).toBe(0);
+    expect(
+      await validateOnce({
+        projectRoot: root,
+        fix: false,
+        blockingOnly: true,
+        strict: true,
+      }),
+    ).toBe(7);
+  });
+
+  test("fails under --fix when the files cannot be uploaded", async () => {
+    // Not logged in: there is no .val/pat.json in the project.
+    expect(
+      await validateOnce({ projectRoot: root, fix: true }),
+    ).toBeGreaterThan(0);
+    const text = plain();
+    expect(text).toContain("not logged in");
+    expect(text).not.toContain("⚠");
+  });
+
+  test("an image inside rich text is a warning too", async () => {
+    // A rich text image's `src` resolves to the rich text schema, not the
+    // image one, once the schema is serialized -- which the handler read as
+    // "neither image nor file" and reported as an error.
+    fs.writeFileSync(
+      path.join(root, "val.modules.ts"),
+      `import { modules } from "@valbuild/core";
+import { config } from "./val.config";
+
+export default modules(config, [
+  { def: () => import("./content/page.val") },
+]);
+`,
+    );
+    fs.writeFileSync(
+      path.join(root, "content/page.val.ts"),
+      `import { c, s } from "../val.config";
+
+export default c.define(
+  "/content/page.val.ts",
+  s.richtext({ img: s.image().remote() }),
+  [
+    {
+      tag: "p",
+      children: [
+        "Look: ",
+        {
+          tag: "img",
+          src: { path: "${IMAGES[0]}", width: 8, height: 8, mimeType: "image/png" },
+        },
+      ],
+    },
+  ],
+);
+`,
+    );
+    expect(await validateOnce({ projectRoot: root, fix: false })).toBe(0);
+    const text = plain();
+    expect(text).toContain("content/page.val.ts  ⚠ 1 warning");
+    expect(text).not.toContain("neither image nor file");
+  });
+});