generate-work-md.js

#!/usr/bin/env node

const fs = require('fs');
const path = require('path');

const repoRoot = process.cwd();
const templatesDir = path.join(repoRoot, 'learning-room', '.github', 'ISSUE_TEMPLATE');
const outputPath = path.join(repoRoot, 'work.md');

function readTemplateFiles() {
  if (!fs.existsSync(templatesDir)) {
    return [];
  }

  return fs.readdirSync(templatesDir)
    .filter((name) => /^(challenge-\d{2}-|bonus-).+\.ya?ml$/i.test(name))
    .sort((a, b) => a.localeCompare(b, undefined, { numeric: true }))
    .map((name) => path.join(templatesDir, name));
}

function extractName(content, fallback) {
  const m = content.match(/^name:\s*"([^"]+)"/m) || content.match(/^name:\s*'([^']+)'/m) || content.match(/^name:\s*(.+)$/m);
  if (!m) return fallback;
  return String(m[1]).trim();
}

function extractBlockScalar(lines, startIndex) {
  const valueLine = lines[startIndex];
  const valueIndent = valueLine.match(/^\s*/)[0].length;
  const minBlockIndent = valueIndent + 2;

  const block = [];
  let i = startIndex + 1;
  for (; i < lines.length; i++) {
    const line = lines[i];
    const rawIndent = line.match(/^\s*/)[0].length;

    if (line.trim() === '') {
      block.push('');
      continue;
    }

    if (rawIndent < minBlockIndent) {
      break;
    }

    block.push(line.slice(minBlockIndent));
  }

  return { text: block.join('\n').trim(), nextIndex: i };
}

function extractAllTemplateContent(content) {
  const lines = content.split(/\r?\n/);
  const parts = [];
  let i = 0;

  while (i < lines.length) {
    // Markdown value block
    if (/^\s*value:\s*\|\s*$/.test(lines[i])) {
      const { text, nextIndex } = extractBlockScalar(lines, i);
      if (text) parts.push({ type: 'markdown', text });
      i = nextIndex;
      continue;
    }

    // Evidence textarea placeholder block
    if (/^\s*placeholder:\s*\|\s*$/.test(lines[i])) {
      const { text, nextIndex } = extractBlockScalar(lines, i);
      if (text) parts.push({ type: 'evidence', text });
      i = nextIndex;
      continue;
    }

    i++;
  }

  return parts;
}

function extractFirstMarkdownBlock(content) {
  const lines = content.split(/\r?\n/);
  for (let i = 0; i < lines.length; i++) {
    if (/^\s*value:\s*\|\s*$/.test(lines[i])) {
      return extractBlockScalar(lines, i).text;
    }
  }
  return '';
}

function cleanupIssueBody(body) {
  if (!body) return '';

  let out = body;

  // Remove repeated H2 heading because the section title is rendered by this generator.
  out = out.replace(/^##\s+.+\n+/m, '');

  // Keep issue task checklists readable in docs.
  out = out.replace(/^- \[ \]/gm, '-');

  // Nest template headings beneath the challenge heading and normalize bold-only
  // pseudo-headings so the generated walkthrough reads like a structured page.
  out = out
    .split('\n')
    .map((line) => {
      const headingMatch = line.match(/^(#{1,5})\s+(.+)$/);
      if (headingMatch) {
        return `${headingMatch[1]}# ${headingMatch[2]}`;
      }

      const boldHeadingMatch = line.match(/^\s*\*\*([^*]+)\*\*$/);
      if (boldHeadingMatch) {
        return `#### ${boldHeadingMatch[1]}`;
      }

      if (line.trim() === '```') {
        return '```text';
      }

      return line;
    })
    .join('\n');

  return out.trim();
}

function toEntry(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8');
  const fileName = path.basename(filePath);

  const fallbackTitle = fileName
    .replace(/\.ya?ml$/i, '')
    .replace(/-/g, ' ')
    .replace(/\b\w/g, (m) => m.toUpperCase());

  const name = extractName(content, fallbackTitle);
  const parts = extractAllTemplateContent(content);

  // Render all content parts in order
  const renderedParts = parts.map((part) => {
    if (part.type === 'markdown') {
      return cleanupIssueBody(part.text);
    }
    if (part.type === 'evidence') {
      return '**Your evidence** (fill in when closing this issue):\n\n```text\n' + part.text + '\n```';
    }
    return '';
  }).filter(Boolean);

  const body = renderedParts.join('\n\n---\n\n');

  return {
    fileName,
    name,
    body,
    isBonus: /^bonus-/i.test(fileName)
  };
}

function render(entries) {
  const core = entries.filter((e) => !e.isBonus);
  const bonus = entries.filter((e) => e.isBonus);

  const section = (title, items) => {
    if (!items.length) return '';

    const blocks = items.map((item) => {
      const sourceLink = `https://github.com/Community-Access/git-going-with-github/blob/main/learning-room/.github/ISSUE_TEMPLATE/${item.fileName}`;
      return `### ${item.name}\n\nSource template: [${item.fileName}](${sourceLink})\n\n${item.body}`.trim();
    });

    return `## ${title}\n\n${blocks.join('\n\n---\n\n')}`;
  };

  return [
    '# Work.md',
    '',
    'Consolidated walkthrough generated from the challenge issue templates in `learning-room/.github/ISSUE_TEMPLATE/`.',
    'Do not edit this file manually. Run `npm run build:html` (or `node scripts/generate-work-md.js`) to regenerate.',
    '',
    section('Core challenges', core),
    '',
    section('Bonus challenges', bonus),
    '',
    '## Authoritative Sources',
    '',
    'Use these official references when you need the current source of truth for the Git and GitHub workflow concepts summarized in this generated walkthrough.',
    '',
    '- [GitHub Docs, home](https://docs.github.com/en)',
    '- [GitHub Changelog](https://github.blog/changelog/)',
    '- [About Git](https://docs.github.com/en/get-started/using-git/about-git)',
    '- [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow)',
    '- [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests)',
    '- [About issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues)',
    '- [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)',
    '',
    '### Section-Level Source Map',
    '',
     '- **Core challenges:** [GitHub Docs, home](https://docs.github.com/en) [GitHub Changelog](https://github.blog/changelog/) [About Git](https://docs.github.com/en/get-started/using-git/about-git)',
    '  [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-pull-requests) [About issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)',
    '- **Bonus challenges:** [GitHub Docs, home](https://docs.github.com/en) [GitHub Changelog](https://github.blog/changelog/) [About Git](https://docs.github.com/en/get-started/using-git/about-git)',
    '  [GitHub flow](https://docs.github.com/en/get-started/using-github/github-flow) [About pull requests](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-references) [About issues](https://docs.github.com/en/issues/tracking-your-work-with-issues/about-issues) [Contributing to a project](https://docs.github.com/en/get-started/exploring-projects-on-github/contributing-to-a-project)',
    ''
  ].join('\n');
}

function main() {
  const files = readTemplateFiles();
  if (!files.length) {
    console.error('No challenge templates found.');
    process.exit(1);
  }

  const entries = files.map(toEntry);
  const output = render(entries);
  fs.writeFileSync(outputPath, output, 'utf-8');

  console.log(`Generated ${path.relative(repoRoot, outputPath)} from ${entries.length} templates.`);
}

main();