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

package/dist/validation/rules/frontmatter.js

@@ -0,0 +1,206 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative, dirname } from 'node:path';
+import matter from 'gray-matter';
+import { Rule } from '../types.js';
+
+const REQUIRED_FIELDS = [
+  { key: "title", type: "string" },
+  { key: "description", type: "string" }
+];
+const OPTIONAL_FIELDS = [{ key: "sidebar_position", type: "number" }];
+function isSlugSafe(raw) {
+  const trimmed = raw.trim().replace(/^\/+|\/+$/g, "");
+  if (!trimmed) {
+    return false;
+  }
+  if (!/^[A-Za-z0-9/_-]+$/.test(trimmed)) {
+    return false;
+  }
+  const segments = trimmed.split("/");
+  return !segments.some((s) => !s || s === "." || s === "..");
+}
+function findFieldLine(raw, key) {
+  const lines = raw.split("\n");
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      break;
+    }
+    if (lines[i].startsWith(`${key}:`)) {
+      return i + 1;
+    }
+  }
+  return void 0;
+}
+function findH1Lines(raw) {
+  const lines = raw.split("\n");
+  let inFrontmatter = false;
+  let passedFrontmatter = false;
+  const result = [];
+  for (let i = 0; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      if (!inFrontmatter) {
+        inFrontmatter = true;
+      } else {
+        passedFrontmatter = true;
+      }
+      continue;
+    }
+    if (passedFrontmatter && /^# /.test(lines[i])) {
+      result.push(i + 1);
+    }
+  }
+  return result;
+}
+async function checkFrontmatter(input) {
+  const diagnostics = [];
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+    return diagnostics;
+  }
+  const mdFiles = entries.filter(
+    (e) => e.isFile() && e.name.endsWith(".md") && !e.parentPath.includes("node_modules") && !e.parentPath.includes("dist")
+  );
+  const records = [];
+  for (const file of mdFiles) {
+    const absolutePath = join(file.parentPath, file.name);
+    const relativePath = relative(input.docsPath, absolutePath);
+    let raw;
+    try {
+      raw = await readFile(absolutePath, "utf-8");
+    } catch {
+      continue;
+    }
+    if (!raw.startsWith("---")) {
+      diagnostics.push({
+        rule: Rule.BlockExists,
+        severity: "error",
+        file: relativePath,
+        line: 1,
+        title: "Missing frontmatter block",
+        detail: "Every page must start with a frontmatter block (---). Add at least title and description."
+      });
+      continue;
+    }
+    let data;
+    try {
+      ({ data } = matter(raw));
+    } catch (err) {
+      diagnostics.push({
+        rule: Rule.ValidYaml,
+        severity: "error",
+        file: relativePath,
+        line: 1,
+        title: "Invalid YAML in frontmatter",
+        detail: err instanceof Error ? err.message : "YAML parse error."
+      });
+      continue;
+    }
+    for (const { key, type } of REQUIRED_FIELDS) {
+      if (!(key in data)) {
+        diagnostics.push({
+          rule: Rule.RequiredFields,
+          severity: "error",
+          file: relativePath,
+          line: 1,
+          title: `Missing required field: ${key}`,
+          detail: `Every page needs a "${key}" (${type}) in its frontmatter.`
+        });
+      } else if (typeof data[key] !== type) {
+        diagnostics.push({
+          rule: Rule.FieldTypes,
+          severity: "error",
+          file: relativePath,
+          line: findFieldLine(raw, key),
+          title: `Wrong type for field: ${key}`,
+          detail: `"${key}" should be a ${type} but got ${typeof data[key]}.`
+        });
+      }
+    }
+    for (const { key, type } of OPTIONAL_FIELDS) {
+      if (key in data && typeof data[key] !== type) {
+        diagnostics.push({
+          rule: Rule.FieldTypes,
+          severity: "error",
+          file: relativePath,
+          line: findFieldLine(raw, key),
+          title: `Wrong type for field: ${key}`,
+          detail: `"${key}" should be a ${type} but got ${typeof data[key]}.`
+        });
+      }
+    }
+    if ("slug" in data && typeof data.slug === "string" && !isSlugSafe(data.slug)) {
+      diagnostics.push({
+        rule: Rule.ValidSlug,
+        severity: "warning",
+        file: relativePath,
+        line: findFieldLine(raw, "slug"),
+        title: "Invalid custom slug",
+        detail: `The slug "${data.slug}" contains unsafe characters. Only letters, digits, underscores, hyphens and forward slashes are allowed.`
+      });
+    }
+    for (const h1Line of findH1Lines(raw)) {
+      diagnostics.push({
+        rule: Rule.NoH1,
+        severity: "warning",
+        file: relativePath,
+        line: h1Line,
+        title: "Avoid h1 headings in content",
+        detail: "The page title comes from frontmatter. Any h1 in the body will be stripped by the parser and replaced by the frontmatter title. Use h2 (##) or lower."
+      });
+    }
+    records.push({
+      relativePath,
+      parentDir: dirname(relativePath),
+      sidebarPosition: typeof data.sidebar_position === "number" ? data.sidebar_position : void 0,
+      sidebarPositionLine: findFieldLine(raw, "sidebar_position"),
+      customSlug: typeof data.slug === "string" && isSlugSafe(data.slug) ? data.slug.trim().replace(/^\/+|\/+$/g, "") : void 0,
+      customSlugLine: findFieldLine(raw, "slug")
+    });
+  }
+  const byDir = Map.groupBy(records, (r) => r.parentDir);
+  for (const siblings of byDir.values()) {
+    const posCounts = /* @__PURE__ */ new Map();
+    for (const record of siblings) {
+      if (record.sidebarPosition !== void 0) {
+        posCounts.set(record.sidebarPosition, (posCounts.get(record.sidebarPosition) ?? 0) + 1);
+      }
+    }
+    for (const record of siblings) {
+      if (record.sidebarPosition === void 0 || (posCounts.get(record.sidebarPosition) ?? 0) <= 1) {
+        continue;
+      }
+      diagnostics.push({
+        rule: Rule.DuplicatePosition,
+        severity: input.strict ? "error" : "warning",
+        file: record.relativePath,
+        line: record.sidebarPositionLine,
+        title: `Duplicate sidebar_position: ${record.sidebarPosition}`,
+        detail: `sidebar_position ${record.sidebarPosition} is shared by multiple siblings. Each sibling page must have a unique position.`
+      });
+    }
+  }
+  const slugCounts = /* @__PURE__ */ new Map();
+  for (const record of records) {
+    if (record.customSlug) {
+      slugCounts.set(record.customSlug, (slugCounts.get(record.customSlug) ?? 0) + 1);
+    }
+  }
+  for (const record of records) {
+    if (!record.customSlug || (slugCounts.get(record.customSlug) ?? 0) <= 1) {
+      continue;
+    }
+    diagnostics.push({
+      rule: Rule.DuplicateSlug,
+      severity: "error",
+      file: record.relativePath,
+      line: record.customSlugLine,
+      title: `Duplicate slug: "${record.customSlug}"`,
+      detail: `Slug "${record.customSlug}" is used by multiple pages. Each page must have a unique URL slug.`
+    });
+  }
+  return diagnostics;
+}
+
+export { checkFrontmatter };

package/dist/validation/rules/index.js

@@ -0,0 +1,17 @@
+import { checkAssets } from './assets.js';
+import { checkCrossFile } from './cross-file.js';
+import { checkFilesystem } from './filesystem.js';
+import { checkFrontmatter } from './frontmatter.js';
+import { checkManifest } from './manifest.js';
+import { checkMarkdown } from './markdown.js';
+
+const allRules = [
+  checkFilesystem,
+  checkFrontmatter,
+  checkAssets,
+  checkMarkdown,
+  checkCrossFile,
+  checkManifest
+];
+
+export { allRules };

package/dist/validation/rules/manifest.js

@@ -0,0 +1,105 @@
+import { readdir } from 'node:fs/promises';
+import { relative, join } from 'node:path';
+import { scanDocsFolder } from '../../scanner.js';
+import { Rule } from '../types.js';
+
+function collectPageFiles(pages) {
+  const refs = [];
+  for (const page of pages) {
+    if (page.file) {
+      refs.push({ file: page.file, slug: page.slug });
+    }
+    if (page.children) {
+      refs.push(...collectPageFiles(page.children));
+    }
+  }
+  return refs;
+}
+function validatePage(page, path, diagnostics) {
+  if (!page.title) {
+    diagnostics.push({
+      rule: Rule.ManifestValid,
+      severity: "error",
+      title: "Manifest page missing title",
+      detail: `Page at "${path}" has no title.`
+    });
+  }
+  if (!page.slug && page.slug !== "") {
+    diagnostics.push({
+      rule: Rule.ManifestValid,
+      severity: "error",
+      title: "Manifest page missing slug",
+      detail: `Page "${page.title || path}" has no slug.`
+    });
+  }
+  if (page.children) {
+    for (let i = 0; i < page.children.length; i++) {
+      validatePage(page.children[i], `${path}/${page.children[i].slug || i}`, diagnostics);
+    }
+  }
+}
+async function checkManifest(input) {
+  const diagnostics = [];
+  let manifest;
+  try {
+    const scanned = await scanDocsFolder(input.docsPath);
+    manifest = scanned.manifest;
+  } catch {
+    return diagnostics;
+  }
+  if (!manifest.version) {
+    diagnostics.push({
+      rule: Rule.ManifestValid,
+      severity: "error",
+      title: "Manifest missing version",
+      detail: "The generated manifest has no version field."
+    });
+  }
+  if (!manifest.pages || !Array.isArray(manifest.pages)) {
+    diagnostics.push({
+      rule: Rule.ManifestValid,
+      severity: "error",
+      title: "Manifest missing pages",
+      detail: "The generated manifest has no pages array."
+    });
+    return diagnostics;
+  }
+  if (manifest.pages.length === 0) {
+    diagnostics.push({
+      rule: Rule.ManifestValid,
+      severity: "error",
+      title: "Manifest has no pages",
+      detail: "The generated manifest has an empty pages array."
+    });
+    return diagnostics;
+  }
+  for (const page of manifest.pages) {
+    validatePage(page, page.slug || "(root)", diagnostics);
+  }
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+    return diagnostics;
+  }
+  const allFiles = new Set(
+    entries.filter((e) => e.isFile()).map((e) => relative(input.docsPath, join(e.parentPath, e.name)))
+  );
+  const pageFiles = collectPageFiles(manifest.pages);
+  for (const { file, slug } of pageFiles) {
+    if (!file) {
+      continue;
+    }
+    if (!allFiles.has(file)) {
+      diagnostics.push({
+        rule: Rule.ManifestRefsExist,
+        severity: "error",
+        title: "Manifest references missing file",
+        detail: `Page "${slug}" references "${file}" which does not exist.`
+      });
+    }
+  }
+  return diagnostics;
+}
+
+export { checkManifest };

package/dist/validation/rules/markdown.js

@@ -0,0 +1,195 @@
+import { readdir, readFile } from 'node:fs/promises';
+import { join, relative } from 'node:path';
+import { Rule } from '../types.js';
+import { getCodeBlockLines } from './utils.js';
+
+const HTML_TAG_RE = /< *\/?([a-zA-Z][a-zA-Z0-9]*)\b[^>]*\/?>/g;
+const ALLOWED_HTML_TAGS = /* @__PURE__ */ new Set(["br", "wbr", "hr", "details", "summary"]);
+const SCRIPT_TAG_RE = /<script\b[^>]*>/gi;
+const EVENT_HANDLER_RE = /\bon[a-z]+\s*=\s*(?:["'][^"']*["']|[^\s>]+)/gi;
+const IMAGE_REF_RE = /!\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const LINK_RE = /\[([^\]]*)\]\(([^)\s]+)(?:\s+"[^"]*")?\)/g;
+const DANGEROUS_URL_RE = /^(javascript|vbscript|data):/i;
+const BASE64_IMAGE_RE = /^data:image\/[^;]+;base64,/i;
+const EXTERNAL_URL_RE = /^https?:\/\//i;
+const PATH_TRAVERSAL_RE = /(?:^|\/)\.\.\//;
+function matchOutsideCode(content, re, 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(re.source, re.flags);
+    let m;
+    while ((m = lineRe.exec(lines[i])) !== null) {
+      results.push({ match: m, line: i + 1 });
+    }
+  }
+  return results;
+}
+async function checkMarkdown(input) {
+  const diagnostics = [];
+  let entries = [];
+  try {
+    entries = await readdir(input.docsPath, { recursive: true, withFileTypes: true });
+  } catch {
+    return diagnostics;
+  }
+  const mdFiles = entries.filter(
+    (e) => e.isFile() && e.name.endsWith(".md") && !e.parentPath.includes("node_modules") && !e.parentPath.includes("dist")
+  );
+  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;
+    }
+    const codeLines = getCodeBlockLines(content);
+    for (const { match, line } of matchOutsideCode(content, SCRIPT_TAG_RE, codeLines)) {
+      diagnostics.push({
+        rule: Rule.NoScriptTags,
+        severity: "error",
+        file: relPath,
+        line,
+        title: "Script tag detected",
+        detail: `"${match[0]}" is not allowed. Script tags pose a security risk.`
+      });
+    }
+    for (const { match, line } of matchOutsideCode(content, EVENT_HANDLER_RE, codeLines)) {
+      diagnostics.push({
+        rule: Rule.NoScriptTags,
+        severity: "error",
+        file: relPath,
+        line,
+        title: "Event handler attribute detected",
+        detail: `"${match[0]}" is not allowed. Inline event handlers pose a security risk.`
+      });
+    }
+    for (const { match, line } of matchOutsideCode(content, HTML_TAG_RE, codeLines)) {
+      const tagName = match[1].toLowerCase();
+      if (tagName === "script" || ALLOWED_HTML_TAGS.has(tagName)) {
+        continue;
+      }
+      diagnostics.push({
+        rule: Rule.NoRawHtml,
+        severity: input.strict ? "error" : "warning",
+        file: relPath,
+        line,
+        title: "Raw HTML tag detected",
+        detail: `<${tagName}> is not allowed. Use markdown syntax instead of raw HTML.`
+      });
+    }
+    for (const { match, line } of matchOutsideCode(content, IMAGE_REF_RE, codeLines)) {
+      const ref = match[2];
+      if (BASE64_IMAGE_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoBase64Images,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Base64-encoded image detected",
+          detail: `Base64-encoded images are not allowed. Save the image as a file in the img/ directory instead.`
+        });
+        continue;
+      }
+      if (EXTERNAL_URL_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoExternalImages,
+          severity: input.strict ? "error" : "warning",
+          file: relPath,
+          line,
+          title: "External image URL detected",
+          detail: `"${ref}" is an external URL. Download the image and place it in the img/ directory.`
+        });
+        continue;
+      }
+      if (DANGEROUS_URL_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoDangerousUrls,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Dangerous URI scheme in image reference",
+          detail: `"${ref}" uses a dangerous URI scheme. Only relative file paths are allowed.`
+        });
+        continue;
+      }
+      if (PATH_TRAVERSAL_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoPathTraversal,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Path traversal in image reference",
+          detail: `"${ref}" contains path traversal. Image references must not use "../".`
+        });
+        continue;
+      }
+      if (ref.startsWith("/")) {
+        diagnostics.push({
+          rule: Rule.ImageRefsRelative,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Image reference is not a relative path",
+          detail: `"${ref}" is an absolute path. Use a relative path like "img/filename.png" instead.`
+        });
+      }
+    }
+    const contentLines = content.split("\n");
+    for (const { match, line } of matchOutsideCode(content, LINK_RE, codeLines)) {
+      const ref = match[2];
+      if (match.index > 0 && contentLines[line - 1][match.index - 1] === "!") {
+        continue;
+      }
+      if (ref.startsWith("#")) {
+        continue;
+      }
+      if (DANGEROUS_URL_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoDangerousUrls,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Dangerous URI scheme in link",
+          detail: `"${ref}" uses a dangerous URI scheme. Use safe URLs only.`
+        });
+        continue;
+      }
+      if (PATH_TRAVERSAL_RE.test(ref)) {
+        diagnostics.push({
+          rule: Rule.NoPathTraversal,
+          severity: "error",
+          file: relPath,
+          line,
+          title: "Path traversal in link",
+          detail: `"${ref}" contains path traversal. Links must not use "../".`
+        });
+        continue;
+      }
+      if (EXTERNAL_URL_RE.test(ref)) {
+        continue;
+      }
+      if (/^[a-z]+:/i.test(ref)) {
+        continue;
+      }
+      if (ref.startsWith("/")) {
+        diagnostics.push({
+          rule: Rule.InternalLinksRelative,
+          severity: input.strict ? "error" : "warning",
+          file: relPath,
+          line,
+          title: "Internal link is not a relative path",
+          detail: `"${ref}" is an absolute path. Use a relative path like "./page.md" instead.`
+        });
+      }
+    }
+  }
+  return diagnostics;
+}
+
+export { checkMarkdown };

package/dist/validation/rules/utils.js

@@ -0,0 +1,18 @@
+function getCodeBlockLines(content) {
+  const lines = content.split("\n");
+  const codeLines = /* @__PURE__ */ new Set();
+  let inCodeBlock = false;
+  for (let i = 0; i < lines.length; i++) {
+    if (/^```/.test(lines[i].trim())) {
+      inCodeBlock = !inCodeBlock;
+      codeLines.add(i + 1);
+      continue;
+    }
+    if (inCodeBlock) {
+      codeLines.add(i + 1);
+    }
+  }
+  return codeLines;
+}
+
+export { getCodeBlockLines };

package/dist/validation/types.js

@@ -0,0 +1,45 @@
+const Rule = {
+  // filesystem rules
+  HasMarkdown: "has-markdown-files",
+  RootIndex: "root-index-exists",
+  NestedDirIndex: "nested-dir-has-index",
+  NoSpaces: "no-spaces-in-names",
+  ValidNaming: "valid-file-naming",
+  NoEmptyDir: "no-empty-directories",
+  NoSymlinks: "no-symlinks",
+  AllowedFileTypes: "allowed-file-types",
+  // frontmatter rules
+  BlockExists: "frontmatter-block-exists",
+  ValidYaml: "frontmatter-valid-yaml",
+  RequiredFields: "frontmatter-required-fields",
+  FieldTypes: "frontmatter-field-types",
+  ValidSlug: "frontmatter-valid-slug",
+  NoH1: "no-h1-heading",
+  DuplicatePosition: "no-duplicate-sidebar-position",
+  DuplicateSlug: "no-duplicate-slugs",
+  // asset rules
+  NoSvg: "no-svg-files",
+  ReferencedImagesExist: "referenced-images-exist",
+  MaxImageSize: "max-image-size",
+  MaxTotalImagesSize: "max-total-images-size",
+  ImageFileNaming: "image-file-naming",
+  NoOrphanedImages: "no-orphaned-images",
+  MaxDataUriSize: "max-data-uri-size",
+  // markdown + security rules
+  NoRawHtml: "no-raw-html",
+  ImageRefsRelative: "image-refs-relative",
+  InternalLinksRelative: "internal-links-relative",
+  NoDangerousUrls: "no-dangerous-urls",
+  NoScriptTags: "no-script-tags",
+  NoPathTraversal: "no-path-traversal",
+  NoBase64Images: "no-base64-images",
+  NoExternalImages: "no-external-images",
+  // cross-file rules
+  InternalLinksResolve: "internal-links-resolve",
+  AnchorLinksResolve: "anchor-links-resolve",
+  // manifest rules
+  ManifestValid: "manifest-valid",
+  ManifestRefsExist: "manifest-refs-exist"
+};
+
+export { Rule };

package/package.json

@@ -1 +1,68 @@
-{"name":"@grafana/plugin-docs-cli","version":"0.0.0","publishConfig":{"access":"public"}}
+{
+  "name": "@grafana/plugin-docs-cli",
+  "version": "0.0.10-canary.2537.23286312909.0",
+  "description": "CLI tool for developing, validating and previewing Grafana plugin documentation locally.",
+  "type": "module",
+  "bin": "./dist/bin/run.js",
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "repository": {
+    "directory": "packages/plugin-docs-cli",
+    "url": "https://github.com/grafana/plugin-tools"
+  },
+  "author": "Grafana",
+  "license": "Apache-2.0",
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "rollup -c ../../rollup.config.ts --configPlugin esbuild",
+    "dev": "rollup -c ../../rollup.config.ts --configPlugin esbuild --watch",
+    "lint": "eslint --cache ./src",
+    "lint:fix": "npm run lint -- --fix",
+    "lint:package": "publint",
+    "test": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "keywords": [
+    "grafana",
+    "plugin",
+    "documentation",
+    "cli",
+    "preview",
+    "validation"
+  ],
+  "bugs": {
+    "url": "https://github.com/grafana/plugin-tools/issues"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "dependencies": {
+    "@grafana/plugin-docs-parser": "0.0.4-canary.2537.23286312909.0",
+    "chokidar": "^5.0.0",
+    "debug": "^4.3.7",
+    "ejs": "^5.0.0",
+    "express": "^5.0.0",
+    "github-slugger": "^1.5.0",
+    "gray-matter": "^4.0.3",
+    "hast-util-to-html": "^9.0.0",
+    "minimist": "^1.2.8"
+  },
+  "devDependencies": {
+    "@types/debug": "^4.1.12",
+    "@types/ejs": "^3.1.5",
+    "@types/express": "^5.0.0",
+    "@types/github-slugger": "^1.3.0",
+    "@types/minimist": "^1.2.5",
+    "@types/supertest": "^7.0.0",
+    "supertest": "^7.0.0"
+  },
+  "gitHead": "557c04d508319ddcb39f34b34c1172ad5f483a07"
+}