@grafana/plugin-docs-cli 0.0.0 → 0.0.10-canary.2537.23286312909.0

package/dist/utils/utils.plugin.js

@@ -0,0 +1,30 @@
+import { readFile } from 'node:fs/promises';
+import { join, resolve } from 'node:path';
+import createDebug from 'debug';
+
+const debug = createDebug("plugin-docs-cli:utils:plugin");
+async function resolveDocsPath(projectRoot) {
+  const root = process.cwd();
+  const pluginJsonPath = join(root, "src", "plugin.json");
+  debug("Looking for plugin.json at: %s", pluginJsonPath);
+  let raw;
+  try {
+    raw = await readFile(pluginJsonPath, "utf-8");
+  } catch {
+    throw new Error(`Could not find src/plugin.json in ${root}`);
+  }
+  let pluginJson;
+  try {
+    pluginJson = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(`Failed to parse ${pluginJsonPath}: ${error instanceof Error ? error.message : error}`);
+  }
+  if (!pluginJson.docsPath) {
+    throw new Error('"docsPath" is not set in src/plugin.json');
+  }
+  const docsPath = resolve(root, pluginJson.docsPath);
+  debug("Resolved docsPath from plugin.json: %s -> %s", pluginJson.docsPath, docsPath);
+  return docsPath;
+}
+
+export { resolveDocsPath };

package/dist/validation/engine.js

@@ -0,0 +1,11 @@
+async function validate(input, rules) {
+  const diagnostics = [];
+  for (const run of rules) {
+    const results = await run(input);
+    diagnostics.push(...results);
+  }
+  const valid = diagnostics.every((d) => d.severity !== "error");
+  return { valid, diagnostics };
+}
+
+export { validate };

package/dist/validation/format.js

@@ -0,0 +1,43 @@
+const SEVERITY_LABEL = {
+  error: "error",
+  warning: "warn ",
+  info: "info "
+};
+function formatResult(result) {
+  const lines = [];
+  if (result.diagnostics.length === 0) {
+    lines.push("\u2713 Documentation is valid");
+    return lines.join("\n");
+  }
+  const counts = { error: 0, warning: 0, info: 0 };
+  for (const d of result.diagnostics) {
+    counts[d.severity]++;
+  }
+  const { error: errors, warning: warnings, info: infos } = counts;
+  const parts = [];
+  if (errors > 0) {
+    parts.push(`${errors} error${errors !== 1 ? "s" : ""}`);
+  }
+  if (warnings > 0) {
+    parts.push(`${warnings} warning${warnings !== 1 ? "s" : ""}`);
+  }
+  if (infos > 0) {
+    parts.push(`${infos} info`);
+  }
+  const icon = errors > 0 ? "\u2717" : "\u26A0";
+  lines.push(`${icon} Documentation has ${parts.join(" and ")}`);
+  lines.push("");
+  for (const d of result.diagnostics) {
+    const label = SEVERITY_LABEL[d.severity] ?? d.severity;
+    const location = d.file ? d.line ? `  ${d.file}:${d.line}` : `  ${d.file}` : "";
+    lines.push(`  ${label}${location}`);
+    lines.push(`         ${d.title}`);
+    if (d.detail) {
+      lines.push(`         ${d.detail}`);
+    }
+    lines.push("");
+  }
+  return lines.join("\n");
+}
+
+export { formatResult };

package/dist/validation/rules/assets.js

@@ -0,0 +1,167 @@
+import { readdir, stat, readFile } from 'node:fs/promises';
+import { extname, join, normalize, dirname, relative } from 'node:path';
+import { Rule } from '../types.js';
+import { ALLOWED_IMAGE_EXTENSIONS } from './filesystem.js';
+
+const IMAGE_FILE_NAME_RE = /^[a-zA-Z0-9\-_.]+$/;
+const MAX_STATIC_SIZE = 300 * 1024;
+const MAX_GIF_SIZE = 1024 * 1024;
+const MAX_TOTAL_SIZE = 5 * 1024 * 1024;
+const MAX_DATA_URI_SIZE = 300 * 1024;
+function formatBytes(bytes) {
+  if (bytes < 1024) {
+    return `${bytes}B`;
+  }
+  const kb = bytes / 1024;
+  if (kb < 1024) {
+    return `${Math.round(kb)}KB`;
+  }
+  const mb = kb / 1024;
+  return `${mb.toFixed(1)}MB`;
+}
+function findRefLine(content, ref) {
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].includes(ref)) {
+      return i + 1;
+    }
+  }
+  return void 0;
+}
+async function checkAssets(input) {
+  const diagnostics = [];
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+    return diagnostics;
+  }
+  const allFiles = entries.filter((e) => e.isFile());
+  const imageFiles = allFiles.filter((e) => ALLOWED_IMAGE_EXTENSIONS.has(extname(e.name).toLowerCase()));
+  const svgFiles = allFiles.filter((e) => extname(e.name).toLowerCase() === ".svg");
+  const mdFiles = allFiles.filter((e) => e.name.endsWith(".md"));
+  function rel(entry) {
+    return relative(input.docsPath, join(entry.parentPath, entry.name));
+  }
+  for (const svg of svgFiles) {
+    diagnostics.push({
+      rule: Rule.NoSvg,
+      severity: "error",
+      file: rel(svg),
+      title: "SVG files are not allowed",
+      detail: `"${svg.name}" is an SVG file. SVG files can contain embedded scripts and pose an XSS risk. Use PNG or WebP instead.`
+    });
+  }
+  for (const img of imageFiles) {
+    if (!IMAGE_FILE_NAME_RE.test(img.name)) {
+      diagnostics.push({
+        rule: Rule.ImageFileNaming,
+        severity: input.strict ? "error" : "info",
+        file: rel(img),
+        title: "Image filename contains invalid characters",
+        detail: `"${img.name}" should use only letters, digits, hyphens, underscores and dots.`
+      });
+    }
+  }
+  let totalSize = 0;
+  for (const img of imageFiles) {
+    const absPath = join(img.parentPath, img.name);
+    let size;
+    try {
+      const st = await stat(absPath);
+      size = st.size;
+    } catch {
+      continue;
+    }
+    totalSize += size;
+    const ext = extname(img.name).toLowerCase();
+    const isGif = ext === ".gif";
+    const maxSize = isGif ? MAX_GIF_SIZE : MAX_STATIC_SIZE;
+    const maxLabel = isGif ? "1MB" : "300KB";
+    if (size > maxSize) {
+      diagnostics.push({
+        rule: Rule.MaxImageSize,
+        severity: input.strict ? "error" : "info",
+        file: rel(img),
+        title: `Image exceeds ${maxLabel} limit`,
+        detail: `"${img.name}" is ${formatBytes(size)} which exceeds the ${maxLabel} limit for ${isGif ? "GIF" : "static"} images. Compress or resize the image.`
+      });
+    }
+  }
+  if (input.strict && totalSize > MAX_TOTAL_SIZE) {
+    diagnostics.push({
+      rule: Rule.MaxTotalImagesSize,
+      severity: "warning",
+      title: "Total image size exceeds 5MB",
+      detail: `Total image size is ${formatBytes(totalSize)} which exceeds the 5MB limit. Reduce the number or size of images.`
+    });
+  }
+  const allFilePaths = new Set(allFiles.map((e) => rel(e)));
+  const referencedPaths = /* @__PURE__ */ new Set();
+  for (const md of mdFiles) {
+    const absPath = join(md.parentPath, md.name);
+    const mdRelPath = rel(md);
+    let content;
+    try {
+      content = await readFile(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    const imageRefRe = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+    let match;
+    while ((match = imageRefRe.exec(content)) !== null) {
+      const ref = match[2];
+      if (/^https?:\/\//i.test(ref) || /^\/\//.test(ref) || /^blob:/i.test(ref)) {
+        continue;
+      }
+      if (/^data:/i.test(ref)) {
+        const commaIdx = ref.indexOf(",");
+        if (commaIdx !== -1) {
+          const encoded = ref.slice(commaIdx + 1);
+          const isBase64 = /;base64$/i.test(ref.slice(0, commaIdx));
+          const byteSize = isBase64 ? Math.ceil(encoded.length * 3 / 4) : encoded.length;
+          if (byteSize > MAX_DATA_URI_SIZE) {
+            diagnostics.push({
+              rule: Rule.MaxDataUriSize,
+              severity: input.strict ? "error" : "info",
+              file: mdRelPath,
+              line: findRefLine(content, ref),
+              title: "Data URI exceeds 300KB limit",
+              detail: `Inline data URI is approximately ${formatBytes(byteSize)} which exceeds the 300KB limit. Use a file reference instead.`
+            });
+          }
+        }
+        continue;
+      }
+      const resolvedPath = ref.startsWith("/") ? normalize(ref.slice(1)) : normalize(join(dirname(mdRelPath), ref));
+      referencedPaths.add(resolvedPath);
+      if (!allFilePaths.has(resolvedPath)) {
+        diagnostics.push({
+          rule: Rule.ReferencedImagesExist,
+          severity: "error",
+          file: mdRelPath,
+          line: findRefLine(content, ref),
+          title: "Referenced image does not exist",
+          detail: `Image "${ref}" referenced in markdown does not exist on disk.`
+        });
+      }
+    }
+  }
+  if (input.strict) {
+    for (const img of imageFiles) {
+      const relPath = rel(img);
+      if (!referencedPaths.has(relPath)) {
+        diagnostics.push({
+          rule: Rule.NoOrphanedImages,
+          severity: "info",
+          file: relPath,
+          title: "Unreferenced image",
+          detail: `"${img.name}" is not referenced by any markdown file. Remove it if it is no longer needed.`
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+export { checkAssets };

package/dist/validation/rules/cross-file.js

@@ -0,0 +1,129 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { relative, join, normalize, dirname } from 'node:path';
+import GithubSlugger from 'github-slugger';
+import { Rule } from '../types.js';
+import { getCodeBlockLines } from './utils.js';
+
+const LINK_RE = /\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const SKIP_URL_RE = /^(https?:\/\/|mailto:|tel:|data:|javascript:|vbscript:)/i;
+const HEADING_RE = /^(#{2,6})\s+(.+)$/;
+function extractHeadingIds(content) {
+  const ids = /* @__PURE__ */ new Set();
+  const slugger = new GithubSlugger();
+  const lines = content.split("\n");
+  const codeLines = getCodeBlockLines(content);
+  for (let i = 0; i < lines.length; i++) {
+    if (codeLines.has(i + 1)) {
+      continue;
+    }
+    const match = HEADING_RE.exec(lines[i]);
+    if (match) {
+      const text = match[2].replace(/\*\*([^*]+)\*\*/g, "$1").replace(/\*([^*]+)\*/g, "$1").replace(/`([^`]+)`/g, "$1").replace(/\[([^\]]+)\]\([^)]+\)/g, "$1").trim();
+      ids.add(slugger.slug(text));
+    }
+  }
+  return ids;
+}
+function extractLinks(content, codeLines) {
+  const results = [];
+  const lines = content.split("\n");
+  for (let i = 0; i < lines.length; i++) {
+    if (codeLines.has(i + 1)) {
+      continue;
+    }
+    const lineRe = new RegExp(LINK_RE.source, LINK_RE.flags);
+    let m;
+    while ((m = lineRe.exec(lines[i])) !== null) {
+      if (m.index > 0 && lines[i][m.index - 1] === "!") {
+        continue;
+      }
+      results.push({ ref: m[2], line: i + 1 });
+    }
+  }
+  return results;
+}
+async function checkCrossFile(input) {
+  const diagnostics = [];
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+    return diagnostics;
+  }
+  const allFiles = entries.filter(
+    (e) => e.isFile() && !e.parentPath.includes("node_modules") && !e.parentPath.includes("dist")
+  );
+  const mdFiles = allFiles.filter((e) => e.name.endsWith(".md"));
+  const allFilePaths = new Set(allFiles.map((e) => relative(input.docsPath, join(e.parentPath, e.name))));
+  const fileHeadings = /* @__PURE__ */ new Map();
+  const fileContents = /* @__PURE__ */ new Map();
+  for (const md of mdFiles) {
+    const absPath = join(md.parentPath, md.name);
+    const relPath = relative(input.docsPath, absPath);
+    let content;
+    try {
+      content = await readFile(absPath, "utf-8");
+    } catch {
+      continue;
+    }
+    fileContents.set(relPath, content);
+    fileHeadings.set(relPath, extractHeadingIds(content));
+  }
+  for (const [relPath, content] of fileContents) {
+    const codeLines = getCodeBlockLines(content);
+    const links = extractLinks(content, codeLines);
+    for (const { ref, line } of links) {
+      if (SKIP_URL_RE.test(ref)) {
+        continue;
+      }
+      const [pathPart, anchor] = ref.split("#", 2);
+      if (!pathPart) {
+        if (anchor) {
+          const headings = fileHeadings.get(relPath);
+          if (headings && !headings.has(anchor)) {
+            diagnostics.push({
+              rule: Rule.AnchorLinksResolve,
+              severity: input.strict ? "error" : "warning",
+              file: relPath,
+              line,
+              title: "Anchor link does not resolve",
+              detail: `"#${anchor}" does not match any heading in this file.`
+            });
+          }
+        }
+        continue;
+      }
+      if (pathPart.startsWith("/") || /^\.\.\//.test(pathPart)) {
+        continue;
+      }
+      const resolvedPath = normalize(join(dirname(relPath), pathPart));
+      if (!allFilePaths.has(resolvedPath)) {
+        diagnostics.push({
+          rule: Rule.InternalLinksResolve,
+          severity: input.strict ? "error" : "warning",
+          file: relPath,
+          line,
+          title: "Internal link does not resolve",
+          detail: `"${pathPart}" does not point to an existing file.`
+        });
+        continue;
+      }
+      if (anchor) {
+        const targetHeadings = fileHeadings.get(resolvedPath);
+        if (targetHeadings && !targetHeadings.has(anchor)) {
+          diagnostics.push({
+            rule: Rule.AnchorLinksResolve,
+            severity: input.strict ? "error" : "warning",
+            file: relPath,
+            line,
+            title: "Anchor link does not resolve",
+            detail: `"#${anchor}" does not match any heading in "${pathPart}".`
+          });
+        }
+      }
+    }
+  }
+  return diagnostics;
+}
+
+export { checkCrossFile };

package/dist/validation/rules/filesystem.js

@@ -0,0 +1,113 @@
+import { readdir } from 'node:fs/promises';
+import { extname, join, sep } from 'node:path';
+import { Rule } from '../types.js';
+
+const SLUG_SAFE_RE = /^[a-z0-9-]+$/;
+const ALLOWED_IMAGE_EXTENSIONS = /* @__PURE__ */ new Set([".png", ".jpg", ".jpeg", ".webp", ".gif"]);
+const ALLOWED_EXTENSIONS = /* @__PURE__ */ new Set([".md", ...ALLOWED_IMAGE_EXTENSIONS]);
+async function checkFilesystem(input) {
+  const diagnostics = [];
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+  }
+  const mdFiles = entries.filter((e) => e.isFile() && extname(e.name).toLowerCase() === ".md");
+  const dirs = entries.filter((e) => e.isDirectory());
+  const symlinks = entries.filter((e) => e.isSymbolicLink());
+  const nonMdFiles = entries.filter((e) => e.isFile() && extname(e.name).toLowerCase() !== ".md");
+  for (const link of symlinks) {
+    diagnostics.push({
+      rule: Rule.NoSymlinks,
+      severity: "error",
+      file: join(link.parentPath, link.name),
+      title: "Symlinks are not allowed",
+      detail: `"${link.name}" is a symbolic link. Use actual files instead of symlinks.`
+    });
+  }
+  for (const file of nonMdFiles) {
+    const ext = extname(file.name).toLowerCase();
+    if (!ALLOWED_EXTENSIONS.has(ext)) {
+      diagnostics.push({
+        rule: Rule.AllowedFileTypes,
+        severity: input.strict ? "error" : "info",
+        file: join(file.parentPath, file.name),
+        title: "File type not allowed",
+        detail: `"${file.name}" is not an allowed file type. Only .md and image files (png, jpg, jpeg, webp, gif) are permitted in the docs folder.`
+      });
+    }
+  }
+  if (mdFiles.length === 0) {
+    diagnostics.push({
+      rule: Rule.HasMarkdown,
+      severity: "error",
+      title: "Docs folder must contain at least one .md file",
+      detail: "The docs folder must contain at least one markdown file. Add markdown files with valid frontmatter to get started."
+    });
+  }
+  const hasRootIndex = mdFiles.some((e) => e.name === "index.md" && e.parentPath === input.docsPath);
+  if (!hasRootIndex) {
+    diagnostics.push({
+      rule: Rule.RootIndex,
+      severity: "error",
+      title: "Root index.md must exist",
+      detail: "The docs folder must contain an index.md file at its root. This serves as the landing page for your plugin documentation."
+    });
+  }
+  for (const dir of dirs) {
+    const dirPath = join(dir.parentPath, dir.name);
+    const hasAllowed = entries.some(
+      (e) => e.isFile() && ALLOWED_EXTENSIONS.has(extname(e.name).toLowerCase()) && (e.parentPath === dirPath || e.parentPath.startsWith(dirPath + sep))
+    );
+    if (!hasAllowed) {
+      diagnostics.push({
+        rule: Rule.NoEmptyDir,
+        severity: input.strict ? "error" : "warning",
+        file: dirPath,
+        title: "Directory contains no documentation files",
+        detail: `"${dir.name}" contains no .md or image files and serves no purpose in the documentation structure. Remove it or add documentation files.`
+      });
+      continue;
+    }
+    const hasMd = mdFiles.some((e) => e.parentPath === dirPath || e.parentPath.startsWith(dirPath + sep));
+    if (!hasMd) {
+      continue;
+    }
+    const hasIndex = mdFiles.some((e) => e.name === "index.md" && e.parentPath === dirPath);
+    if (!hasIndex) {
+      diagnostics.push({
+        rule: Rule.NestedDirIndex,
+        severity: "warning",
+        file: dirPath,
+        title: "Subdirectory is missing index.md",
+        detail: `"${dir.name}" has no index.md. Without one, it will appear as an unnamed category using a title-cased directory name.`
+      });
+    }
+  }
+  const namesToCheck = [
+    ...mdFiles.map((e) => ({ slug: e.name.slice(0, -3), label: e.name, path: join(e.parentPath, e.name) })),
+    ...dirs.map((e) => ({ slug: e.name, label: e.name, path: join(e.parentPath, e.name) }))
+  ];
+  for (const item of namesToCheck) {
+    if (/\s/.test(item.slug)) {
+      diagnostics.push({
+        rule: Rule.NoSpaces,
+        severity: "error",
+        file: item.path,
+        title: "Name contains spaces",
+        detail: `"${item.label}" contains spaces which break URL slugs. Use hyphens instead.`
+      });
+    } else if (!SLUG_SAFE_RE.test(item.slug)) {
+      diagnostics.push({
+        rule: Rule.ValidNaming,
+        severity: input.strict ? "error" : "warning",
+        file: item.path,
+        title: "Name contains non-slug characters",
+        detail: `"${item.label}" should use only lowercase letters, digits and hyphens for clean URL slugs.`
+      });
+    }
+  }
+  return diagnostics;
+}
+
+export { ALLOWED_EXTENSIONS, ALLOWED_IMAGE_EXTENSIONS, checkFilesystem };