starlight-cannoli-plugins 2.17.2 → 2.18.0

package/README.md

@@ -144,7 +144,7 @@ dvisvgm --version
 - `removeOrphanedSvgs` (optional, default: `false`): When `true`, SVG files that are no longer referenced by any `tex compile` block are deleted automatically. In dev mode, stale SVGs are removed immediately when a block is edited. On build, any remaining orphans are swept at the end.
 - `svgClassname` (optional): Default CSS class(es) applied to every compiled SVG `<img>` element. Individual blocks can override this with a `class` meta tag value. The `tex-compiled` class is always present and cannot be overridden.
 - `texInputDirs` (optional): Directories added to the TeX input search path (`TEXINPUTS`), allowing `\input{}` and `\include{}` to resolve files from your project. Use a trailing `/` to search only that directory, or `//` to search it recursively. Multiple directories are supported. When any file in these directories changes, all cached SVGs are invalidated and recompiled.
-- `tempOutputDir` (optional): When set, a JPEG copy of each compiled diagram is written to this directory, mirroring the folder structure of `src/content/docs/`. Only blocks that carry a `blockid=<n>` meta tag produce a JPEG — blocks without it are ignored. The filename format is `<originating-file>--<blockid>--<hash>.jpg` (e.g. `tex-test.md--5--abc123.jpg`). JPEGs are deleted automatically when their block is removed, its `blockid` changes, or its content changes. SVG output is unaffected — the JPEG is complementary and intended for local inspection.
+- `debug` (optional): When set, a JPEG copy of each compiled diagram is written to `debug.outputDir` as a flat file list (no mirrored folder structure). Only blocks that carry a `blockid=<n>` meta tag produce a JPEG — blocks without it are ignored. The filename format is `<originating-file>--<blockid>-<8-char-dir-checksum>.jpg` (e.g. `tex-test--5-a1b2c3d4.jpg`), where the checksum is an MD5 hash of the originating file's directory, namespacing files so that same-named files from different directories don't collide. JPEGs are deleted automatically when their block is removed, its `blockid` changes, or its content changes, and the entire `debug.outputDir` is cleared on dev server startup. Every JPEG (re)write is also appended to `debug.logFile`, which rotates automatically once it grows too large (rolling backups `<logFile>-1.log`, `<logFile>-2.log`, etc.). SVG output is unaffected — the JPEG/log output is complementary and intended for local inspection.
 
 ```ts
 astroLatexCompile({

package/dist/{chunk-FDEHNCBK.js → chunk-GVS36MVT.js}

@@ -9,18 +9,67 @@ import { join as join2, relative as relative2, resolve as resolve2 } from "path"
 import { visit, SKIP } from "unist-util-visit";
 import { MetaOptions } from "@expressive-code/core";
 
+// src/plugins/utils/rotating-file-logger.ts
+import { existsSync, mkdirSync, renameSync, rmSync, statSync } from "fs";
+import { appendFile } from "fs/promises";
+import { dirname, extname } from "path";
+function rotatedPath(filePath, index) {
+  const ext = extname(filePath);
+  const base = filePath.slice(0, filePath.length - ext.length);
+  return `${base}-${index}${ext}`;
+}
+function formatTimestamp(date) {
+  const pad = (n, width = 2) => String(n).padStart(width, "0");
+  const datePart = `${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}`;
+  const timePart = `${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())},${pad(date.getMilliseconds(), 3)}`;
+  return `${datePart} ${timePart}`;
+}
+function rotate(options) {
+  const { filePath, backupCount } = options;
+  const oldestPath = rotatedPath(filePath, backupCount);
+  if (existsSync(oldestPath)) {
+    rmSync(oldestPath);
+  }
+  for (let index = backupCount - 1; index >= 1; index--) {
+    const source = rotatedPath(filePath, index);
+    if (existsSync(source)) {
+      renameSync(source, rotatedPath(filePath, index + 1));
+    }
+  }
+  if (backupCount >= 1) {
+    renameSync(filePath, rotatedPath(filePath, 1));
+  } else {
+    rmSync(filePath);
+  }
+}
+var RotatingFileLogger = class {
+  options;
+  constructor(options) {
+    this.options = options;
+    mkdirSync(dirname(options.filePath), { recursive: true });
+  }
+  async write(message) {
+    const { filePath, maxSizeBytes, identifier } = this.options;
+    const line = `[${identifier}] ${formatTimestamp(/* @__PURE__ */ new Date())} ${message}${message.endsWith("\n") ? "" : "\n"}`;
+    if (existsSync(filePath) && statSync(filePath).size >= maxSizeBytes) {
+      rotate(this.options);
+    }
+    await appendFile(filePath, line);
+  }
+};
+
 // src/plugins/astro-latex-compile/utils.ts
 import { createHash } from "crypto";
 import {
-  existsSync,
-  mkdirSync,
+  existsSync as existsSync2,
+  mkdirSync as mkdirSync2,
   readdirSync,
   readFileSync,
   writeFileSync,
-  rmSync,
+  rmSync as rmSync2,
   mkdtempSync
 } from "fs";
-import { basename, dirname, join, relative, resolve } from "path";
+import { basename, dirname as dirname2, extname as extname2, join, relative, resolve } from "path";
 import { tmpdir } from "os";
 import sharp from "sharp";
 
@@ -251,18 +300,18 @@ function html(literalValues, ...interpolatedValues) {
 
 // src/plugins/astro-latex-compile/utils.ts
 var CONTENT_ROOT = "src/content/docs/";
-function computeJpgPath(tempOutputDir, filePath, blockId) {
+function computeJpgPath(outputDir, filePath, blockId) {
   const normalized = filePath.replace(/\\/g, "/");
   const idx = normalized.indexOf(CONTENT_ROOT);
   const relativePath = idx !== -1 ? normalized.slice(idx + CONTENT_ROOT.length) : basename(normalized);
-  const dir = dirname(relativePath);
-  const filename = basename(relativePath);
-  const jpgFilename = `${filename}--${blockId}.jpg`;
-  const base = resolve(tempOutputDir);
-  return dir === "." ? join(base, jpgFilename) : join(base, dir, jpgFilename);
+  const dir = dirname2(relativePath);
+  const filename = basename(relativePath, extname2(relativePath));
+  const dirChecksum = createHash("md5").update(dir).digest("hex").slice(0, 8);
+  const jpgFilename = `${filename}--${blockId}-${dirChecksum}.jpg`;
+  return join(resolve(outputDir), jpgFilename);
 }
 async function writeJpgFromSvg(svgPath, jpgPath) {
-  mkdirSync(dirname(jpgPath), { recursive: true });
+  mkdirSync2(dirname2(jpgPath), { recursive: true });
   await sharp(svgPath, { density: 300 }).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
 function stripAnsi(text) {
@@ -313,7 +362,7 @@ async function writeJpgError(jpgPath, header, errorText) {
   <text x="${padding}" y="${padding + 40}" font-family="monospace" font-size="12" fill="#666666">${escapeXml(header)}</text>
   ${textLines}
 </svg>`;
-  mkdirSync(dirname(jpgPath), { recursive: true });
+  mkdirSync2(dirname2(jpgPath), { recursive: true });
   await sharp(Buffer.from(svg)).flatten({ background: { r: 255, g: 255, b: 255 } }).jpeg({ quality: 90 }).toFile(jpgPath);
 }
 function computeLineOffset(_latexCode) {
@@ -418,10 +467,10 @@ function buildLatexSource(latexCode) {
 async function compileLatexToSvg(latexCode, svgOutputDir, texInputDirs = [], inputsSalt = "") {
   const hash = hashLatexCode(latexCode, inputsSalt);
   const svgPath = join(svgOutputDir, `${hash}.svg`);
-  if (existsSync(svgPath)) {
+  if (existsSync2(svgPath)) {
     return { hash, svgPath, wasCompiled: false };
   }
-  mkdirSync(svgOutputDir, { recursive: true });
+  mkdirSync2(svgOutputDir, { recursive: true });
   const workDir = mkdtempSync(join(tmpdir(), "latex-compile-"));
   const texFile = join(workDir, "diagram.tex");
   const pdfFile = join(workDir, "diagram.pdf");
@@ -479,7 +528,7 @@ Error: ${errorOutput}`
     }
   } finally {
     try {
-      rmSync(workDir, { recursive: true, force: true });
+      rmSync2(workDir, { recursive: true, force: true });
     } catch {
     }
   }
@@ -487,6 +536,8 @@ Error: ${errorOutput}`
 }
 
 // src/plugins/astro-latex-compile/index.ts
+var DEBUG_LOG_MAX_SIZE_BYTES = 5 * 1024 * 1024;
+var DEBUG_LOG_BACKUP_COUNT = 3;
 function getFrontmatterOffset(absoluteFilePath) {
   try {
     const original = readFileSync2(absoluteFilePath, "utf-8");
@@ -499,6 +550,12 @@ function getFrontmatterOffset(absoluteFilePath) {
 }
 function latexCompileTransformer(options) {
   const svgOutputDir = resolve2(options.svgOutputDir);
+  const debugLogger = options.debug ? new RotatingFileLogger({
+    identifier: "astro-latex-compile",
+    filePath: options.debug.logFile,
+    maxSizeBytes: DEBUG_LOG_MAX_SIZE_BYTES,
+    backupCount: DEBUG_LOG_BACKUP_COUNT
+  }) : null;
   return async function transformer(tree, file) {
     const nodes = [];
     visit(tree, "code", (node, index, parent) => {
@@ -516,7 +573,7 @@ function latexCompileTransformer(options) {
       nodes.map(async ({ node, index, parent }) => {
         const lineNumberStr = node.position?.start.line !== void 0 ? String(node.position.start.line + frontmatterOffset) : "?";
         const blockId = new MetaOptions(node.meta ?? "").getInteger("blockid");
-        const jpgPath = options.tempOutputDir && blockId !== void 0 ? computeJpgPath(options.tempOutputDir, filePath, blockId) : null;
+        const jpgPath = options.debug && blockId !== void 0 ? computeJpgPath(options.debug.outputDir, filePath, blockId) : null;
         try {
           const result = await compileLatexToSvg(
             node.value,
@@ -532,8 +589,8 @@ function latexCompileTransformer(options) {
           options._referencedHashes?.add(result.hash);
           if (jpgPath) {
             await writeJpgFromSvg(result.svgPath, jpgPath);
-            console.log(
-              `[astro-latex-compile] ${relFilePath}:${lineNumberStr}: wrote ${jpgPath}`
+            await debugLogger?.write(
+              `${relFilePath}:${lineNumberStr}: wrote ${jpgPath}`
             );
           }
           return {
@@ -588,7 +645,7 @@ ${details}`
       );
       options._fileHashMap.set(filePath, newHashes);
     }
-    if (options.tempOutputDir && options._fileJpgPathMap) {
+    if (options.debug && options._fileJpgPathMap) {
       const newJpgPaths = new Set(
         results.map((r) => r.jpgPath).filter(Boolean)
       );

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 } from "./chunk-3UMY7T6G.js";
 import {
   latexCompileTransformer
-} from "./chunk-FDEHNCBK.js";
+} from "./chunk-GVS36MVT.js";
 import {
   astroNormalizePaths
 } from "./chunk-TLOFSB33.js";
@@ -311,12 +311,24 @@ function astroLatexCompile(options) {
         if (command === "build") {
           await clearContentLayerCache(config);
         }
+        if (command === "dev" && options.debug) {
+          const debugOutputDir = resolve2(options.debug.outputDir);
+          let entries;
+          try {
+            entries = await readdir(debugOutputDir);
+          } catch {
+            entries = [];
+          }
+          await Promise.all(
+            entries.filter((f) => f.endsWith(".jpg")).map((f) => rm(join3(debugOutputDir, f), { force: true }))
+          );
+        }
         const existingPlugins = Array.isArray(config.markdown?.remarkPlugins) ? config.markdown.remarkPlugins.filter(Boolean) : [];
         const pluginOptions = {
           ...options,
           _fileHashMap: options.removeOrphanedSvgs ? fileHashMap : void 0,
           _referencedHashes: command === "build" && options.removeOrphanedSvgs ? referencedHashes : void 0,
-          _fileJpgPathMap: options.tempOutputDir ? fileJpgPathMap : void 0
+          _fileJpgPathMap: options.debug ? fileJpgPathMap : void 0
         };
         updateConfig({
           markdown: {

package/dist/plugins/astro-latex-compile.d.ts

@@ -36,14 +36,20 @@ interface LatexCompilePluginOptions {
      */
     texInputDirs?: string[];
     /**
-     * When set, a JPEG copy of each compiled diagram is written here, mirroring
-     * the folder structure of `src/content/docs/`. Only blocks that carry a
-     * `blockid=<n>` meta tag produce a JPEG. Filename format:
-     * `<originating-file>--<blockid>--<hash>.jpg`.
+     * When set, a JPEG copy of each compiled diagram is written to a flat
+     * directory. Only blocks that carry a `blockid=<n>` meta tag produce a
+     * JPEG. Filename format: `<originating-file>-<8-char-dir-checksum>--<blockid>.jpg`,
+     * where the checksum namespaces files originating from different
+     * directories to avoid collisions between files with the same name.
      * JPEGs are deleted automatically when their block is removed or its content
      * changes. Intended for local inspection, not for publishing.
      */
-    tempOutputDir?: string;
+    debug?: {
+        /** Directory where debug JPEGs are written, as a flat file list. */
+        outputDir: string;
+        /** Path to a log file that records every JPEG (re)write. Rotates by size. */
+        logFile: string;
+    };
     /**
      * @internal Populated by the Astro integration to track which hashes were
      * referenced during a build, used for full orphan cleanup at build:done.

package/dist/plugins/astro-latex-compile.js

@@ -1,7 +1,7 @@
 import {
   compileLatexToSvg,
   latexCompileTransformer
-} from "../chunk-FDEHNCBK.js";
+} from "../chunk-GVS36MVT.js";
 import "../chunk-7D2KLZGE.js";
 import "../chunk-4VNS5WPM.js";
 export {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "starlight-cannoli-plugins",
   "type": "module",
-  "version": "2.17.2",
+  "version": "2.18.0",
   "description": "Starlight plugins for automatic sidebar generation and link validation",
   "license": "ISC",
   "main": "./dist/index.js",