feat: warn on stale JS output blocks

Author: jderochervlk

scripts/__tests__/test-examples.test.mjs

@@ -54,3 +54,83 @@ test("run compiles a real example block from an injected workspace", () => {
     /module M_0 = \{[\s\S]*let greeting = "hello"/,
   );
 });
+
+test("warns about stale JS Output blocks without rewriting the file", () => {
+  let fixture = `# Demo
+
+<div className="hidden">
+
+\`\`\`res prelude
+@val external alert: string => unit = "alert"
+\`\`\`
+
+</div>
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+\`\`\`res example
+alert("hello")
+\`\`\`
+
+\`\`\`js
+console.log("stale");
+\`\`\`
+
+</CodeTab>
+`;
+
+  let { docsRoot, tempRoot, file } = makeWorkspace(fixture);
+  let { logger, warnings } = makeLogger();
+
+  let result = run({ docsRoot, tempRoot, logger });
+  let nextContent = fs.readFileSync(file, "utf8");
+
+  assert.equal(result.success, true);
+  assert.equal(result.warningCount, 1);
+  assert.match(warnings[0], /sample\.mdx/);
+  assert.match(warnings[0], /--update/);
+  assert.match(nextContent, /console\.log\("stale"\);/);
+});
+
+test("ignores standalone javascript fences outside a matching CodeTab", () => {
+  let fixture = `# Demo
+
+\`\`\`res example
+let value = 1
+\`\`\`
+
+\`\`\`js
+console.log("leave me alone");
+\`\`\`
+`;
+
+  let { docsRoot, tempRoot } = makeWorkspace(fixture);
+  let { logger } = makeLogger();
+
+  let result = run({ docsRoot, tempRoot, logger });
+
+  assert.equal(result.success, true);
+  assert.equal(result.warningCount, 0);
+});
+
+test("warns and skips malformed CodeTabs that never provide a JS Output fence", () => {
+  let fixture = `# Demo
+
+<CodeTab labels={["ReScript", "JS Output"]}>
+
+\`\`\`res example
+let value = 1
+\`\`\`
+
+</CodeTab>
+`;
+
+  let { docsRoot, tempRoot } = makeWorkspace(fixture);
+  let { logger, warnings } = makeLogger();
+
+  let result = run({ docsRoot, tempRoot, logger });
+
+  assert.equal(result.success, true);
+  assert.equal(result.warningCount, 1);
+  assert.match(warnings[0], /missing paired JS Output block/);
+});

scripts/test-examples.mjs

@@ -62,6 +62,151 @@ let parseFile = (content) => {
     .join("\n");
 };
 
+let splitLines = (content) => content.split("\n");
+
+let fenceKind = (line) => {
+  if (line.startsWith("```res")) {
+    return "res";
+  }
+
+  if (line.startsWith("```js") || line.startsWith("```javascript")) {
+    return "js";
+  }
+
+  return null;
+};
+
+let collectPreludeBlocks = (content) => {
+  let lines = splitLines(content);
+  let preludes = [];
+
+  for (let i = 0; i < lines.length; i++) {
+    if (!lines[i].startsWith("```res prelude")) {
+      continue;
+    }
+
+    let start = i + 1;
+    let end = start;
+    while (end < lines.length && !lines[end].startsWith("```")) {
+      end++;
+    }
+
+    preludes.push({
+      line: i + 1,
+      content: lines.slice(start, end).join("\n"),
+    });
+
+    i = end;
+  }
+
+  return preludes;
+};
+
+let collectCodeTabPairs = (content) => {
+  let lines = splitLines(content);
+  let pairs = [];
+  let warnings = [];
+  let inTargetTab = false;
+  let pendingRes = null;
+
+  for (let i = 0; i < lines.length; i++) {
+    let line = lines[i];
+
+    if (line.includes('<CodeTab labels={["ReScript", "JS Output"]}>')) {
+      inTargetTab = true;
+      pendingRes = null;
+      continue;
+    }
+
+    if (inTargetTab && line.includes("</CodeTab>")) {
+      if (pendingRes != null) {
+        warnings.push({
+          line: pendingRes.line,
+          message: "missing paired JS Output block",
+        });
+      }
+
+      inTargetTab = false;
+      pendingRes = null;
+      continue;
+    }
+
+    if (!inTargetTab) {
+      continue;
+    }
+
+    let kind = fenceKind(line);
+
+    if (kind === "res") {
+      let start = i + 1;
+      let end = start;
+      while (end < lines.length && !lines[end].startsWith("```")) {
+        end++;
+      }
+
+      pendingRes = {
+        line: i + 1,
+        content: lines.slice(start, end).join("\n"),
+      };
+      i = end;
+      continue;
+    }
+
+    if (kind === "js" && pendingRes != null) {
+      let start = i + 1;
+      let end = start;
+      while (end < lines.length && !lines[end].startsWith("```")) {
+        end++;
+      }
+
+      pairs.push({
+        line: pendingRes.line,
+        res: pendingRes,
+        js: {
+          content: lines.slice(start, end).join("\n"),
+        },
+      });
+
+      pendingRes = null;
+      i = end;
+    }
+  }
+
+  return { pairs, warnings };
+};
+
+let stripCompilerBoilerplate = (output) => {
+  let normalized = output.replace(
+    /^\/\/ Generated by ReScript, PLEASE EDIT WITH CARE\n'use strict';\n\n/,
+    "",
+  );
+
+  return normalized.replace(/\n\/\*.*\*\/\s*$/s, "").trimEnd();
+};
+
+let buildSnippetSource = ({ preludes, pair }) => {
+  let visiblePreludes = preludes
+    .filter((prelude) => prelude.line < pair.line)
+    .map((prelude) => prelude.content)
+    .filter(Boolean);
+
+  return [...visiblePreludes, pair.res.content].filter(Boolean).join("\n\n");
+};
+
+let compileSnippet = (tempRoot, source) => {
+  fs.writeFileSync(path.join(tempRoot, "src", "_tempFile.res"), source);
+  child_process.execFileSync(
+    "npm",
+    ["exec", "rescript", "build", tempRoot, "--", "--quiet"],
+    {
+      cwd: projectRoot,
+      stdio: "pipe",
+    },
+  );
+
+  return fs.readFileSync(path.join(tempRoot, "src", "_tempFile.js"), "utf8");
+};
+
 let ensureTempProject = (tempRoot) => {
   fs.mkdirSync(path.join(tempRoot, "src"), { recursive: true });
   fs.writeFileSync(path.join(tempRoot, "rescript.json"), rescriptJson);
@@ -87,6 +232,7 @@ export let run = ({
   ensureTempProject(tempRoot);
 
   let success = true;
+  let warningCount = 0;
 
   globSync("{manual,react}/**/*.mdx", {
     cwd: docsRoot,
@@ -111,10 +257,33 @@ export let run = ({
       );
     } catch {
       success = false;
+      return;
+    }
+
+    let preludes = collectPreludeBlocks(content);
+    let { pairs, warnings: malformedWarnings } = collectCodeTabPairs(content);
+
+    for (let warning of malformedWarnings) {
+      logger.warn(`${file}:${warning.line} ${warning.message}`);
+      warningCount++;
+    }
+
+    for (let pair of pairs) {
+      let snippetSource = buildSnippetSource({ preludes, pair });
+      let compiledJs = compileSnippet(tempRoot, snippetSource);
+      let expectedJs = stripCompilerBoilerplate(compiledJs);
+      let currentJs = pair.js.content.trimEnd();
+
+      if (expectedJs !== currentJs) {
+        logger.warn(
+          `${file}:${pair.line} JS Output is stale. Run scripts/test-examples.mjs --update`,
+        );
+        warningCount++;
+      }
     }
   });
 
-  return { success, warningCount: 0 };
+  return { success, warningCount };
 };
 
 if (process.argv[1] && path.resolve(process.argv[1]) === __filename) {