@growthbeaker/vscode-help-docs 0.1.0

package/dist/markdown-renderer.js

@@ -0,0 +1,139 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseFrontmatter = parseFrontmatter;
+exports.validateFrontmatterFields = validateFrontmatterFields;
+exports.renderMarkdown = renderMarkdown;
+exports.titleCaseFilename = titleCaseFilename;
+const gray_matter_1 = __importDefault(require("gray-matter"));
+const markdown_it_1 = __importDefault(require("markdown-it"));
+function createMarkdownIt(enableMermaid) {
+    const instance = new markdown_it_1.default({
+        html: false,
+        linkify: true,
+        typographer: true,
+    });
+    // Try to load markdown-it-anchor if available
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const anchor = require('markdown-it-anchor');
+        instance.use(anchor);
+    }
+    catch {
+        // markdown-it-anchor is optional
+    }
+    if (enableMermaid) {
+        applyMermaidPlugin(instance);
+    }
+    return instance;
+}
+/**
+ * markdown-it plugin: converts ```mermaid code blocks into
+ * <div class="mermaid"> containers for client-side rendering.
+ */
+function applyMermaidPlugin(md) {
+    const defaultFence = md.renderer.rules.fence.bind(md.renderer.rules);
+    md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+        const token = tokens[idx];
+        if (token.info.trim().toLowerCase() === 'mermaid') {
+            // Wrap diagram source in a div that mermaid.js will find and render
+            const escaped = md.utils.escapeHtml(token.content);
+            return `<div class="mermaid">${escaped}</div>\n`;
+        }
+        return defaultFence(tokens, idx, options, env, self);
+    };
+}
+// Default instance (no mermaid)
+const md = createMarkdownIt(false);
+// Mermaid-enabled instance (created lazily)
+let mdMermaid = null;
+/**
+ * Parse frontmatter from a markdown file with graceful error handling.
+ *
+ * Implements:
+ * - AC 1.8.2: Malformed YAML Frontmatter Graceful Degradation
+ * - AC 1.8.3: Frontmatter Field Type Validation
+ */
+function parseFrontmatter(filePath, rawContent) {
+    try {
+        const result = (0, gray_matter_1.default)(rawContent);
+        const frontmatter = validateFrontmatterFields(filePath, result.data);
+        return { frontmatter, content: result.content };
+    }
+    catch (error) {
+        // AC 1.8.2: Malformed YAML — apply defaults, strip frontmatter, log warning
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`Malformed frontmatter in ${filePath}: ${errorMessage}`);
+        // Strip the malformed frontmatter block from content
+        const content = stripFrontmatter(rawContent);
+        return { frontmatter: {}, content };
+    }
+}
+/**
+ * Validate frontmatter field types, logging warnings for invalid types.
+ *
+ * Implements AC 1.8.3: Frontmatter Field Type Validation
+ */
+function validateFrontmatterFields(filePath, data) {
+    const result = {};
+    const invalidFields = [];
+    if ('title' in data) {
+        if (typeof data.title === 'string') {
+            result.title = data.title;
+        }
+        else {
+            invalidFields.push(`title (expected string, got ${typeof data.title})`);
+        }
+    }
+    if ('order' in data) {
+        if (typeof data.order === 'number' && !isNaN(data.order)) {
+            result.order = data.order;
+        }
+        else {
+            invalidFields.push(`order (expected number, got ${typeof data.order})`);
+        }
+    }
+    if ('hidden' in data) {
+        if (typeof data.hidden === 'boolean') {
+            result.hidden = data.hidden;
+        }
+        else {
+            invalidFields.push(`hidden (expected boolean, got ${typeof data.hidden})`);
+        }
+    }
+    if (invalidFields.length > 0) {
+        console.warn(`Invalid frontmatter field types in ${filePath}: ${invalidFields.join(', ')}`);
+    }
+    return result;
+}
+/** Render markdown content to HTML */
+function renderMarkdown(content, enableMermaid = false) {
+    if (enableMermaid) {
+        if (!mdMermaid) {
+            mdMermaid = createMarkdownIt(true);
+        }
+        return mdMermaid.render(content);
+    }
+    return md.render(content);
+}
+/**
+ * Convert a filename to a title-cased display name.
+ * Strips .md extension, replaces hyphens/underscores with spaces,
+ * removes leading numeric prefixes (e.g., "01-"), and title-cases each word.
+ */
+function titleCaseFilename(filename) {
+    return filename
+        .replace(/\.md$/i, '')
+        .replace(/^\d+-/, '')
+        .replace(/[-_]/g, ' ')
+        .replace(/\b\w/g, (char) => char.toUpperCase())
+        .trim();
+}
+/** Strip a frontmatter block from raw markdown content */
+function stripFrontmatter(rawContent) {
+    // Match opening --- through closing --- (or end of leading block)
+    return rawContent.replace(/^---[\s\S]*?(?:---\s*\n|---\s*$)/, '').trim();
+}
+//# sourceMappingURL=markdown-renderer.js.map

package/dist/nav-tree.d.ts

@@ -0,0 +1,19 @@
+import { NavNode, FolderMeta } from './types';
+export interface BuildNavTreeOptions {
+    metaFilename?: string;
+    maxDepth?: number;
+}
+/**
+ * Build a navigation tree from a documentation folder structure.
+ *
+ * Implements: flow:navigation-tree-construction
+ * Covers: AC 1.2.3 (malformed _meta.json), AC 1.2.4 (circular symlinks, depth limits)
+ */
+export declare function buildNavTree(contentRoot: string, options?: BuildNavTreeOptions): Promise<NavNode[]>;
+/**
+ * Parse a folder's _meta.json file with graceful error handling.
+ *
+ * Implements AC 1.2.3: Graceful Handling of Malformed _meta.json Files
+ */
+export declare function parseFolderMeta(dirPath: string, metaFilename?: string): FolderMeta;
+//# sourceMappingURL=nav-tree.d.ts.map

package/dist/nav-tree.js

@@ -0,0 +1,215 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildNavTree = buildNavTree;
+exports.parseFolderMeta = parseFolderMeta;
+const fs = __importStar(require("fs"));
+const path = __importStar(require("path"));
+const markdown_renderer_1 = require("./markdown-renderer");
+const DEFAULT_MAX_DEPTH = 20;
+const DEFAULT_META_FILENAME = '_meta.json';
+/**
+ * Build a navigation tree from a documentation folder structure.
+ *
+ * Implements: flow:navigation-tree-construction
+ * Covers: AC 1.2.3 (malformed _meta.json), AC 1.2.4 (circular symlinks, depth limits)
+ */
+async function buildNavTree(contentRoot, options) {
+    const metaFilename = options?.metaFilename ?? DEFAULT_META_FILENAME;
+    const maxDepth = options?.maxDepth ?? DEFAULT_MAX_DEPTH;
+    const visitedRealPaths = new Set();
+    return scanDirectory(contentRoot, contentRoot, metaFilename, 0, maxDepth, visitedRealPaths);
+}
+/**
+ * Recursively scan a directory to build NavNode children.
+ */
+async function scanDirectory(dirPath, contentRoot, metaFilename, depth, maxDepth, visitedRealPaths) {
+    // AC 1.2.4: Check max depth
+    if (depth > maxDepth) {
+        console.warn(`Max nesting depth (${maxDepth}) exceeded at ${dirPath}, skipping`);
+        return [];
+    }
+    // AC 1.2.4: Check circular symlinks
+    try {
+        const realPath = fs.realpathSync(dirPath);
+        if (visitedRealPaths.has(realPath)) {
+            const stats = fs.lstatSync(dirPath);
+            if (stats.isSymbolicLink()) {
+                console.warn(`Circular symlink detected at ${dirPath} (points to ${realPath}), skipping`);
+            }
+            return [];
+        }
+        visitedRealPaths.add(realPath);
+    }
+    catch {
+        // If we can't stat the directory, skip it
+        return [];
+    }
+    let entries;
+    try {
+        entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    const nodes = [];
+    for (const entry of entries) {
+        // Skip hidden and meta entries
+        if (entry.name.startsWith('_') || entry.name.startsWith('.')) {
+            continue;
+        }
+        const entryPath = path.join(dirPath, entry.name);
+        const relativePath = path.relative(contentRoot, entryPath);
+        if (entry.isDirectory() || entry.isSymbolicLink()) {
+            // Check if symlink points to a directory
+            if (entry.isSymbolicLink()) {
+                try {
+                    const targetStats = fs.statSync(entryPath);
+                    if (!targetStats.isDirectory()) {
+                        continue;
+                    }
+                }
+                catch {
+                    continue;
+                }
+            }
+            // Recurse into subdirectory
+            const childVisited = new Set(visitedRealPaths);
+            const children = await scanDirectory(entryPath, contentRoot, metaFilename, depth + 1, maxDepth, childVisited);
+            // Skip empty folders (no page children)
+            if (children.length === 0) {
+                continue;
+            }
+            // Read folder metadata
+            const meta = parseFolderMeta(entryPath, metaFilename);
+            nodes.push({
+                type: 'folder',
+                title: meta.title ?? (0, markdown_renderer_1.titleCaseFilename)(entry.name),
+                order: meta.order ?? Infinity,
+                path: relativePath,
+                children,
+                collapsed: meta.collapsed ?? false,
+            });
+        }
+        else if (entry.name.endsWith('.md')) {
+            // Parse markdown file
+            try {
+                const rawContent = fs.readFileSync(entryPath, 'utf-8');
+                const { frontmatter } = (0, markdown_renderer_1.parseFrontmatter)(entryPath, rawContent);
+                // Skip hidden files
+                if (frontmatter.hidden === true) {
+                    continue;
+                }
+                nodes.push({
+                    type: 'page',
+                    title: frontmatter.title ?? (0, markdown_renderer_1.titleCaseFilename)(entry.name),
+                    order: frontmatter.order ?? Infinity,
+                    path: relativePath,
+                });
+            }
+            catch {
+                // If we can't read the file, skip it
+                continue;
+            }
+        }
+    }
+    // Sort: by order ascending, then by title alphabetically
+    nodes.sort((a, b) => {
+        if (a.order !== b.order) {
+            return a.order - b.order;
+        }
+        return a.title.localeCompare(b.title);
+    });
+    return nodes;
+}
+/**
+ * Parse a folder's _meta.json file with graceful error handling.
+ *
+ * Implements AC 1.2.3: Graceful Handling of Malformed _meta.json Files
+ */
+function parseFolderMeta(dirPath, metaFilename = DEFAULT_META_FILENAME) {
+    const metaPath = path.join(dirPath, metaFilename);
+    if (!fs.existsSync(metaPath)) {
+        return {};
+    }
+    let rawContent;
+    try {
+        rawContent = fs.readFileSync(metaPath, 'utf-8');
+    }
+    catch {
+        return {};
+    }
+    let data;
+    try {
+        data = JSON.parse(rawContent);
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        console.warn(`Malformed ${metaFilename} at ${dirPath}: ${errorMessage}`);
+        return {};
+    }
+    // Validate field types (same pattern as frontmatter validation)
+    const result = {};
+    const invalidFields = [];
+    if ('title' in data) {
+        if (typeof data.title === 'string') {
+            result.title = data.title;
+        }
+        else {
+            invalidFields.push('title');
+        }
+    }
+    if ('order' in data) {
+        if (typeof data.order === 'number' && !isNaN(data.order)) {
+            result.order = data.order;
+        }
+        else {
+            invalidFields.push('order');
+        }
+    }
+    if ('collapsed' in data) {
+        if (typeof data.collapsed === 'boolean') {
+            result.collapsed = data.collapsed;
+        }
+        else {
+            invalidFields.push('collapsed');
+        }
+    }
+    if (invalidFields.length > 0) {
+        console.warn(`Invalid field types in ${metaPath}: ${invalidFields.join(', ')}`);
+    }
+    return result;
+}
+//# sourceMappingURL=nav-tree.js.map

package/dist/types.d.ts

@@ -0,0 +1,95 @@
+import * as vscode from 'vscode';
+/** Configuration for creating a Help Viewer panel */
+export interface HelpViewerConfig {
+    /** Absolute path to the root folder containing markdown docs */
+    contentRoot: string;
+    /** Extension context (needed for webview URI resolution) */
+    extensionContext: vscode.ExtensionContext;
+    /** Panel title shown in the VS Code tab */
+    title?: string;
+    /** Column to open the panel in */
+    viewColumn?: vscode.ViewColumn;
+    /** Optional CSS to inject (appended after base theme styles) */
+    customCss?: string;
+    /** Optional path to a CSS file to inject */
+    customCssPath?: string;
+    /** Enable anchor link scrolling within documents */
+    enableAnchors?: boolean;
+    /** Enable Mermaid diagram rendering in code blocks */
+    enableMermaid?: boolean;
+    /** Folder metadata filename */
+    metaFilename?: string;
+    /** Default page to show on open (relative path from contentRoot) */
+    defaultPage?: string;
+}
+/** A node in the navigation tree */
+export interface NavNode {
+    type: 'folder' | 'page';
+    title: string;
+    order: number;
+    /** Relative path from contentRoot */
+    path: string;
+    /** Child nodes (folders only) */
+    children?: NavNode[];
+    /** Initial collapsed state (folders only) */
+    collapsed?: boolean;
+}
+/** YAML frontmatter metadata from a markdown file */
+export interface Frontmatter {
+    title?: string;
+    order?: number;
+    hidden?: boolean;
+}
+/** Metadata from a folder's _meta.json file */
+export interface FolderMeta {
+    title?: string;
+    order?: number;
+    collapsed?: boolean;
+}
+/** Public API handle returned by createHelpPanel */
+export interface IHelpPanel {
+    /** The underlying VS Code WebviewPanel */
+    readonly panel: vscode.WebviewPanel;
+    /** Navigate to a specific doc page (relative path from contentRoot) */
+    navigateTo(relativePath: string): void;
+    /** Refresh the nav tree (e.g., after docs are updated) */
+    refresh(): void;
+    /** Dispose the panel */
+    dispose(): void;
+}
+/** Messages sent between extension host and webview */
+export type ExtensionToWebviewMessage = {
+    type: 'contentLoaded';
+    html: string;
+    title: string;
+    path: string;
+} | {
+    type: 'navTree';
+    tree: NavNode[];
+} | {
+    type: 'error';
+    message: string;
+} | {
+    type: 'anchorNotFound';
+    anchor: string;
+} | {
+    type: 'scrollToAnchor';
+    anchor: string;
+} | {
+    type: 'scrollToTop';
+};
+/** Messages sent from webview to extension host */
+export type WebviewToExtensionMessage = {
+    type: 'navigateTo';
+    path: string;
+} | {
+    type: 'navigateToAnchor';
+    path?: string;
+    anchor: string;
+} | {
+    type: 'openExternal';
+    url: string;
+} | {
+    type: 'ready';
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@growthbeaker/vscode-help-docs",
+  "version": "0.1.0",
+  "description": "A reusable VS Code webview panel that renders a folder of markdown files with a navigation sidebar",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "keywords": [
+    "vscode",
+    "webview",
+    "help",
+    "documentation",
+    "markdown",
+    "navigation"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/growth-beaker/vscode-help-docs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/growth-beaker/vscode-help-docs/issues"
+  },
+  "homepage": "https://github.com/growth-beaker/vscode-help-docs#readme",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage"
+  },
+  "files": [
+    "dist/**/*.js",
+    "dist/**/*.d.ts",
+    "src/webview/**",
+    "README.md"
+  ],
+  "dependencies": {
+    "gray-matter": "^4.0.3",
+    "markdown-it": "^14.1.0",
+    "mermaid": "^11.14.0"
+  },
+  "optionalDependencies": {
+    "markdown-it-anchor": "^9.2.0"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "@types/node": "^25.5.0",
+    "@types/vscode": "^1.85.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.1.0"
+  },
+  "peerDependencies": {
+    "vscode": "^1.85.0"
+  },
+  "peerDependenciesMeta": {
+    "vscode": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "vscode": "^1.85.0"
+  },
+  "license": "MIT"
+}