Add interactive Markmap visualization pipeline for repository structure

[Copilot]

Implements auto-generated mind map of repository structure, deployed to GitHub Pages on every push to main. Provides visual navigation with language breakdown and expandable directory tree.

Implementation

Core Generator (scripts/generate-markmap.mjs)

• Pure Node.js (no dependencies) script that walks repository tree
• Generates Markdown with Markmap frontmatter (initialExpandLevel: 2, color scheme)
• Computes language distribution from file extensions (top 12 shown with percentages)
• Conservative limits: 20k entries, 1MB file size, depth 8
• Respects .markmapignore + default excludes (node_modules, .git, dist, build artifacts, binaries)

CI/CD Pipeline (.github/workflows/markmap.yml)

• Triggers: push to main, workflow_dispatch
• Generates markdown → converts to HTML via markmap-cli
• Produces downloadable artifact repo-markmap
• Deploys to GitHub Pages

Configuration

• .markmapignore: Simple line-delimited exclusion list
• .gitignore: Excludes generated markmap/ directory
• README.md: Added navigation link to live map

Output Structure

---
markmap:
  initialExpandLevel: 2
  color: ["#4c78a8", "#f58518", ...]
---

# FortiPath — Codebase Map

## Languages (top)
- Python: 37 files (22.8%)
- Go: 20 files (12.3%)
...

## Structure
- **.specify/**
  - constitution.md
  - **tasks/**

Once merged and Pages enabled, accessible at: https://cywf.github.io/FortiPath/repo-map.html

Warning

Firewall rules blocked me from connecting to one or more addresses (expand for details)

I tried to connect to the following addresses, but was blocked by firewall rules:

• cdn.jsdelivr.net
  • Triggering command: node /usr/local/bin/markmap ./markmap/repo-map.md -o ./markmap/repo-map.html (dns block)
• unpkg.com
  • Triggering command: node /usr/local/bin/markmap ./markmap/repo-map.md -o ./markmap/repo-map.html (dns block)

If you need me to access, download, or install something from one of these locations, you can either:

• Configure Actions setup steps to set up my environment, which run before the firewall is enabled
• Add the appropriate URLs or hosts to the custom allowlist in this repository's Copilot coding agent settings (admins only)

Original prompt

You are operating in the current repository. Create a minimal, maintainable pipeline that generates and publishes an interactive Markmap mind map of the repository’s structure.

GOAL

• On each push to the default branch and on manual dispatch:
  1. Walk the repo, build a Markdown outline of the directory tree (skipping noisy/large dirs & binaries).
  2. Convert it to a Markmap HTML.
  3. Upload as a workflow artifact and deploy to GitHub Pages.

CONSTRAINTS

• Pure Node.js (no third‑party libs). Target Node 20.
• Don’t modify user code. Only add new files.
• Respect a small allowlist/denylist; avoid scanning more than ~20k entries or files >1MB.
• Keep logic self‑contained and documented.

ADD THESE FILES EXACTLY:

1. File: scripts/generate-markmap.mjs

---

#!/usr/bin/env node
// Generates markmap/repo-map.md from the current repo.
// No deps, Node >= 18 (tested on 20). Conservative scan to avoid CI melt-down.

import { promises as fs } from "fs";
import path from "path";

const root = process.cwd();
const outDir = path.join(root, "markmap");
await fs.mkdir(outDir, { recursive: true });

const DEFAULT_IGNORES = new Set([
  ".git", ".github", "node_modules", ".pnpm-store",
  ".venv", "venv", "__pycache__", ".pytest_cache", ".mypy_cache",
  "dist", "build", "out", "coverage", ".next", ".nuxt", ".cache",
  ".gradle", "target", ".idea", ".vscode", ".terraform", "vendor",
  ".dart_tool", ".tox", ".egg-info"
]);

const SKIP_EXTS = new Set([
  ".png",".jpg",".jpeg",".gif",".webp",".svg",".ico",
  ".mp4",".mov",".avi",".mkv",".mp3",".wav",".flac",
  ".zip",".gz",".bz2",".7z",".tar",".tgz",".xz",
  ".pdf",".jar",".exe",".dll",".dylib"
]);

const MAX_FILE_SIZE = 1024 * 1024;     // 1 MB
const MAX_DEPTH = Number(process.env.MARKMAP_MAX_DEPTH || 8);
const MAX_ENTRIES = Number(process.env.MARKMAP_MAX_ENTRIES || 20000);

const LANGUAGE_EXT_MAP = {
  ".ts": "TypeScript", ".tsx": "TypeScript",
  ".js": "JavaScript", ".jsx": "JavaScript",
  ".py": "Python", ".go": "Go", ".rs": "Rust",
  ".java": "Java", ".kt": "Kotlin",
  ".c": "C", ".h": "C", ".cpp": "C++", ".hpp": "C++",
  ".cs": "C#", ".rb": "Ruby", ".php": "PHP",
  ".sh": "Shell", ".ps1": "PowerShell",
  ".scala": "Scala", ".swift": "Swift",
  ".m": "Objective‑C", ".mm": "Objective‑C++",
  ".r": "R", ".lua": "Lua"
};

const ignoreListPath = path.join(root, ".markmapignore");
// Lines in .markmapignore are treated as literal names to skip (dirs or files).
let extraIgnores = [];
try {
  const raw = await fs.readFile(ignoreListPath, "utf8");
  extraIgnores = raw.split(/\r?\n/).map(s => s.trim()).filter(Boolean);
} catch {}
const IGNORES = new Set([...DEFAULT_IGNORES, ...extraIgnores]);

const extCounts = new Map();
let totalEntries = 0;

function langOf(file) {
  const ext = path.extname(file).toLowerCase();
  if (!ext) return "Other";
  return LANGUAGE_EXT_MAP[ext] || ext.toUpperCase().slice(1);
}

async function walk(dir, depth = 0) {
  if (depth > MAX_DEPTH) return "";
  let entries;
  try {
    entries = await fs.readdir(dir, { withFileTypes: true });
  } catch {
    return "";
  }
  entries.sort((a,b) => a.name.localeCompare(b.name));
  let md = "";
  for (const e of entries) {
    if (totalEntries++ > MAX_ENTRIES) break;
    if (e.name === ".DS_Store" || IGNORES.has(e.name)) continue;

    const full = path.join(dir, e.name);
    const rel = path.relative(root, full);

    if (e.isDirectory()) {
      md += `${"  ".repeat(depth)}- **${e.name}/**\n`;
      md += await walk(full, depth + 1);
    } else {
      const ext = path.extname(e.name).toLowerCase();
      if (SKIP_EXTS.has(ext)) continue;
      const st = await fs.stat(full).catch(() => null);
      if (!st || st.size > MAX_FILE_SIZE) continue;
      md += `${"  ".repeat(depth)}- ${e.name}\n`;
      extCounts.set(langOf(e.name), (extCounts.get(langOf(e.name)) || 0) + 1);
    }
  }
  return md;
}

const repo =
  process.env.GITHUB_REPOSITORY?.split("/")?.pop() || path.basename(root);

const tree = await walk(root, 0);
const total = Array.from(extCounts.values()).reduce((a,b) => a + b, 0);
const topLangs = Array.from(extCounts.entries())
  .sort((a, b) => b[1] - a[1])
  .slice(0, 12)
  .map(([k, v]) => {
    const pct = total ? Math.round((v * 1000) / total) / 10 : 0;
    return `- ${k}: ${v} files (${pct}%)`;
  })
  .join("\n");

const frontmatter = `--- 
markmap:
  initialExpandLevel: 2
  maxWidth: 320
  color:
    - "#4c78a8"
    - "#f58518"
    - "#e45756"
    - "#72b7b2"
    - "#54a24b"
---`;

const md = `${frontmatter}

# ${repo} — Codebase Map

## Languages (top)
${topLangs || "- None"}

## Structure
${tree}
`;

await fs.writeFile(path.join(outDir, "repo-map.md"), md, "utf8");
console.log(`Wrote ${path.join("markmap", "repo-map.md")}`);
File: .github/workflows/markmap.yml

yaml
Copy code
name: Codebase Mindmap

on:
  push:
    branches:
      - main
  workflow_dispatch:

permissions:
  contents: read
  pages: write
  id-token: write

concurrency:
  group: "pages"
  ...

</details>



<!-- START COPILOT CODING AGENT TIPS -->
---

💡 You can make Copilot smarter by setting up custom instructions, customizing its development environment and configuring Model Context Protocol (MCP) servers. Learn more [Copilot coding agent tips](https://gh.io/copilot-coding-agent-tips) in the docs.