@purview-dev/astroc4 1.0.0-prerelease.7 → 1.0.0-prerelease.8

package/README.md

@@ -145,6 +145,7 @@ reload in `astro dev` like any other.
 | `projects` | `{}` | Named LikeC4 project folders, relative to the site root or absolute. See above. |
 | `vitePlugin` | `{}` | Passed to `LikeC4VitePlugin`. Setting `workspace` or `languageServices` takes discovery over: `projects` is then ignored (with a warning). |
 | `fences` | `true` | Turn ` ```likec4 ` fences into diagrams. |
+| `validation` | `'strict'` | Whether a fence that cannot be drawn (bad DSL, missing view, bad `project`, unresolved `file=`) fails the build or only warns. `'relaxed'` warns and leaves it as a highlighted code block; `{ default, collections, relaxed: [globs] }` scopes it by collection or path. See [Fences](docs/wiki/guide/Fences.md#partial-and-invalid-examples). |
 | `highlighting` | `true` | Highlight LikeC4 source. Starlight only — a plain Astro site passes `likec4Language` to Expressive Code. See below. |
 
 ### Syntax highlighting

package/dist/fences.d.ts

@@ -1,4 +1,5 @@
 import type { MdastPluginEntry } from 'satteri';
+import { type ValidationOptions } from './validation.js';
 type LikeC4Api = typeof import('likec4').LikeC4;
 /**
  * Finishes loading LikeC4 before the first page renders, so the load cannot race
@@ -39,8 +40,19 @@ export interface FenceOptions {
      * `project` is checked at build time; without it, only the browser can.
      */
     projects?: string[];
+    /**
+     * How a fence that cannot be turned into a diagram is treated. `strict` (the
+     * default) fails the build and `astro check`; `relaxed` logs a warning and
+     * leaves the fence as a highlighted code block. Relaxing can be scoped by
+     * page path glob or content collection. See `./validation.ts`.
+     */
+    validation?: ValidationOptions;
+    /** The site's content directory, so a page's collection can be resolved. */
+    contentDir?: string;
+    /** Called with the reason for each fence `relaxed` validation leaves as a code block. */
+    onInvalid?: (message: string) => void;
 }
-export declare function likec4Fences({ root, projects }?: FenceOptions): MdastPluginEntry;
+export declare function likec4Fences({ root, projects, validation, contentDir, onInvalid }?: FenceOptions): MdastPluginEntry;
 export interface FencePlaceholder {
     viewId: string;
     /** The laid-out model of an inline or `file=` fence; absent for a project view. */

package/dist/index.d.ts

@@ -3,6 +3,7 @@ import type { AstroIntegration } from 'astro';
 import { missingOptimizedDependencies } from './integration.js';
 import type { LikeC4IntegrationOptions } from './integration.js';
 export { missingOptimizedDependencies };
+export type { ValidationMode, ValidationOptions, ValidationScope } from './validation.js';
 export interface LikeC4HighlightingOptions {
     /** Branch, tag or commit SHA of `likec4/likec4`. Defaults to `main`; also `ASTROC4_REF`. */
     ref?: string;

package/dist/index.js

@@ -37,6 +37,45 @@ var translations = {
   }
 };
 
+// src/validation.ts
+function globToRegExp(pattern) {
+  let body = "";
+  for (let index = 0;index < pattern.length; index += 1) {
+    const char = pattern[index];
+    if (char === "*") {
+      if (pattern[index + 1] === "*") {
+        body += ".*";
+        index += 1;
+      } else {
+        body += "[^/]*";
+      }
+    } else if (char === "?") {
+      body += "[^/]";
+    } else if (".+^${}()|[]\\".includes(char)) {
+      body += `\\${char}`;
+    } else {
+      body += char;
+    }
+  }
+  return new RegExp(`^(?:.*/)?${body}$`);
+}
+var toSlashes = (value) => value.replaceAll("\\", "/");
+function validationModeFor(options, relativePath, collection) {
+  if (options === undefined)
+    return "strict";
+  if (typeof options === "string")
+    return options;
+  const fallback = options.default ?? "strict";
+  const collections = options.collections === undefined ? [] : [options.collections].flat();
+  if (collection !== undefined && collections.includes(collection))
+    return "relaxed";
+  if (relativePath === undefined)
+    return fallback;
+  const patterns = options.relaxed === undefined ? [] : [options.relaxed].flat();
+  const path = toSlashes(relativePath);
+  return patterns.some((pattern) => globToRegExp(pattern).test(path)) ? "relaxed" : fallback;
+}
+
 // src/fences.ts
 var require2 = createRequire(import.meta.url);
 var likec4ApiPromise;
@@ -56,6 +95,7 @@ var IMPORTS = {
   [PROJECT_COMPONENT]: `${PACKAGE_NAME}/components/LikeC4View.astro`
 };
 var STRINGS = translations.en;
+var RELAXED_NOTE = "Left as a highlighted code block because this page is validated in `relaxed` mode.";
 var layoutCache = new Map;
 function parseFenceMeta(meta) {
   const options = {};
@@ -123,7 +163,23 @@ function describe(fileURL) {
     return String(fileURL);
   }
 }
-function likec4Fences({ root, projects } = {}) {
+function pagePath(fileURL, root) {
+  if (!fileURL || !root)
+    return;
+  try {
+    return relative(resolve(root), fileURLToPath(fileURL));
+  } catch {
+    return;
+  }
+}
+function collectionOf(fileURL, contentDir) {
+  const within = pagePath(fileURL, contentDir);
+  if (!within || within.startsWith(".."))
+    return;
+  const [first, ...rest] = within.split(/[\\/]/);
+  return rest.length > 0 ? first : undefined;
+}
+function likec4Fences({ root, projects, validation, contentDir, onInvalid } = {}) {
   return (factory) => {
     if (!factory.source.includes("```" + FENCE_LANG))
       return null;
@@ -134,9 +190,21 @@ function likec4Fences({ root, projects } = {}) {
       async code(node, ctx) {
         if (node.lang !== FENCE_LANG)
           return;
+        const mode = validationModeFor(validation, pagePath(ctx.fileURL, root), collectionOf(ctx.fileURL, contentDir));
+        const fail = (reason) => {
+          if (mode === "strict")
+            throw new Error(reason);
+          onInvalid?.(`${reason} ${RELAXED_NOTE}`);
+        };
         const where = `${describe(ctx.fileURL)}: \`\`\`${FENCE_LANG} fence`;
         const options = parseFenceMeta(node.meta);
-        const source = options.file ? await readFenceFile(options.file, ctx.fileURL, root, where) : (node.value ?? "").trim();
+        let source;
+        try {
+          source = options.file ? await readFenceFile(options.file, ctx.fileURL, root, where) : (node.value ?? "").trim();
+        } catch (error) {
+          fail(error instanceof Error ? error.message : String(error));
+          return;
+        }
         const common = {
           title: options.title,
           description: options.description,
@@ -146,9 +214,14 @@ function likec4Fences({ root, projects } = {}) {
         };
         if (source.length === 0) {
           if (!options.view) {
-            throw new Error(`${where} is empty, so it needs \`view="<id>"\` to name a view in the project model.`);
+            fail(`${where} is empty, so it needs \`view="<id>"\` to name a view in the project model.`);
+            return;
+          }
+          const projectFailure = projectError(options.project, projects, where);
+          if (projectFailure !== undefined) {
+            fail(projectFailure);
+            return;
           }
-          checkProject(options.project, projects, where);
           if (markdown) {
             ctx.replaceNode(node, {
               raw: fencePlaceholder({ ...placeholderOptions(options), viewId: options.view, project: options.project }),
@@ -169,11 +242,13 @@ function likec4Fences({ root, projects } = {}) {
         try {
           layout = await layoutSource(source);
         } catch (error) {
-          throw new Error(`${where} is not valid LikeC4 — ${error instanceof Error ? error.message : String(error)}`);
+          fail(`${where} is not valid LikeC4 — ${error instanceof Error ? error.message : String(error)}`);
+          return;
         }
         const viewId = options.view ?? defaultView(source, layout.viewIds);
         if (!viewId || !layout.viewIds.includes(viewId)) {
-          throw new Error(`${where} has no view "${viewId ?? "(none)"}". Declared: ${layout.viewIds.join(", ") || "(none)"}.`);
+          fail(`${where} has no view "${viewId ?? "(none)"}". Declared: ${layout.viewIds.join(", ") || "(none)"}.`);
+          return;
         }
         if (markdown) {
           ctx.replaceNode(node, {
@@ -198,20 +273,18 @@ function likec4Fences({ root, projects } = {}) {
     };
   };
 }
-function checkProject(project, projects, where) {
+function projectError(project, projects, where) {
   if (projects === undefined)
     return;
   const requested = project?.trim();
   const available = projects.join(", ");
   if (!requested) {
-    if (projects.length > 1) {
-      throw new Error(`${where}: ${STRINGS["likec4.error.projectRequired"].replace("{available}", available)}`);
-    }
-    return;
+    return projects.length > 1 ? `${where}: ${STRINGS["likec4.error.projectRequired"].replace("{available}", available)}` : undefined;
   }
   if (!projects.includes(requested)) {
-    throw new Error(`${where}: ${STRINGS["likec4.error.unknownProject"].replace("{projectId}", requested).replace("{available}", available || "(none)")}`);
+    return `${where}: ${STRINGS["likec4.error.unknownProject"].replace("{projectId}", requested).replace("{available}", available || "(none)")}`;
   }
+  return;
 }
 function defaultView(source, viewIds) {
   for (const match of source.matchAll(/(?<![\w-])view\s+([\w-]+)/g)) {
@@ -728,7 +801,8 @@ function resolvesFrom(specifier, root) {
 function likec4Integration({
   vitePlugin = {},
   projects,
-  fences = true
+  fences = true,
+  validation
 } = {}) {
   let icons;
   return {
@@ -747,7 +821,7 @@ function likec4Integration({
           }
         });
         if (fences) {
-          await registerFences(config, updateConfig, logger, resolved);
+          await registerFences(config, updateConfig, logger, resolved, validation);
           injectScript("page", MD_FENCES_SCRIPT);
         }
         await ensureReactRenderer(config, updateConfig, logger);
@@ -796,12 +870,15 @@ async function ensureReactRenderer(config, updateConfig, logger) {
     logger.warn("@astrojs/react is not installed, so <LikeC4View> cannot render. Install it (`astro add react`).");
   }
 }
-async function registerFences(config, updateConfig, logger, projects) {
+async function registerFences(config, updateConfig, logger, projects, validation) {
   const { satteri, isSatteriProcessor } = await import("@astrojs/markdown-satteri");
   const existing = config.markdown?.processor;
   const fences = () => likec4Fences({
     root: fileURLToPath4(config.root),
-    projects: projects.length > 0 ? projects.map((project) => project.name) : undefined
+    contentDir: config.srcDir ? fileURLToPath4(new URL("content/", config.srcDir)) : undefined,
+    projects: projects.length > 0 ? projects.map((project) => project.name) : undefined,
+    validation,
+    onInvalid: (message) => logger.warn(message)
   });
   if (existing === undefined) {
     updateConfig({ markdown: { processor: satteri({ mdastPlugins: [fences()] }) } });
@@ -1648,7 +1725,8 @@ function starlightLikeC4(options = {}) {
   const integration = likec4Integration({
     vitePlugin: options.vitePlugin,
     projects: options.projects,
-    fences: options.fences
+    fences: options.fences,
+    validation: options.validation
   });
   return {
     name: PACKAGE_NAME2,
@@ -1734,5 +1812,5 @@ export {
   withLikeC4Language
 };
 
-//# debugId=B9FCAC3D36CE7F6464756E2164756E21
+//# debugId=4A4B67FAE347BDD864756E2164756E21
 //# sourceMappingURL=index.js.map