Move README heading names into map.json, warn about unmapped README sections, document the README-explorer workflow

.github/workflows/pages.yml

@@ -50,6 +50,9 @@ jobs:
       - name: Test the README parser and map layout
         run: node --test site/parser.test.mjs
 
+      - name: Warn about README sections that are not on the map
+        run: node site/tools/coverage.mjs
+
       - name: Assemble the site
         run: |
           mkdir _site

CONTRIBUTING.md

@@ -32,7 +32,16 @@ Contributions from everyone are welcomed. To keep the roadmap practical, accessi
 - If a new topic is thought to make the roadmap more complete, it may be suggested. New topics should be proposed thoughtfully, considering their usefulness and relevance for other learners.
 - Connections between topics on the map are listed in `site/map.json` under `links` as `["Topic", "Other topic", "why they are related"]`, using the names shown on the map. Connect topics that a learner should study together or that depend on each other, and keep the reason to one short sentence. Tests fail if a name is misspelled, a pair is listed twice or a topic has no connection.
 
-## 6. Versioning and Releases
+## 6. How the README Feeds the Interactive Roadmap
+
+The [interactive roadmap](https://m3y54m.github.io/Embedded-Engineering-Roadmap/) reads `README.md` directly; there is no other copy of the content. Most contributions need no change outside the README.
+
+- **Topics** come from heading depth: `##` is a group, `###` a main topic, `####` and deeper are subtopics. The emojis in headings (✳️ 🔵 🔶 🔸) are decoration only. Renaming a heading changes its link (`#/topic-name`).
+- **Resources** are list items in the form `- [📘👶💎 Title](https://url)`, optionally followed by a dash and a short note. Symbols: 📘 book, 🎞️ video, 📝 article, 🔗 link, 🎧 audio, 👶 beginner, 💎 essential. `python3 .github/scripts/check_readme.py` checks the format and duplicates.
+- **The map** (`site/map.json`) draws only the main topics. Each label on it opens the README heading with the same name. If the wording differs, or the label has no section of its own, add `"Label": ["README heading"]` to `readme` in `site/map.json`. A new main topic needs a README section and a box in `site/map.json` (and at least one entry in `links`), unless it should stay off the map: then list its title or group in `offMap`. CI warns about main topics that are neither.
+- **Preview and test locally:** `python3 -m http.server 8765` from the repository root, then open `/site/`; `node --test site/parser.test.mjs` runs the checks CI runs.
+
+## 7. Versioning and Releases
 
 The roadmap image is versioned as `vMAJOR.MINOR.PATCH`, starting from `v2.0.0`.
 

site/diagram.js

@@ -1,40 +1,6 @@
 // Links the topics drawn on the map (map.json) to README topics, so every topic knows
 // which areas (Software, Hardware, Soft skills) it sits in and how important the map marks it.
 
-// Map labels whose README heading is worded differently.
-const ALIASES = {
-  'ADC / DAC': ['ADC', 'DAC'],
-  'Buildroot / Yocto': ['Buildroot', 'Yocto'],
-  'TDD & Unit Testing': ['Test Driven Development (TDD)', 'Unit Testing'],
-  'Threading / Parallelism': ['Multithreading & Parallel Processing'],
-  'Device Drivers': ['Linux Device Drivers'],
-  'Real-Time OS': ['Real-Time Operating Systems'],
-  'Interfaces & Protocols': ['Interfaces, Protocols & Communication Technologies'],
-  Basic: ['Basic Protocols'],
-  'High-Speed': ['High-Speed Protocols'],
-  Wireless: ['Wireless Protocols'],
-  Industrial: ['Industrial Protocols'],
-  Automotive: ['Automotive Protocols'],
-  Network: ['Network Protocols / Socket Programming'],
-  'TCP/IP': ['Network Protocols / Socket Programming'],
-  UDP: ['Network Protocols / Socket Programming'],
-  Cellular: ['Cellular Communication'],
-  MQTT: ['CoAP & MQTT'],
-  CoAP: ['CoAP & MQTT'],
-  'LTE-M / 5G': ['LTE-M & NB-IoT'],
-  'NB-IoT': ['LTE-M & NB-IoT'],
-  'Basic Math & Calculus': ['Basic Calculus'],
-  'SDLC Models': ['Software Development Life Cycle (SDLC) Models'],
-  'Version Control': ['Version Control Systems'],
-  AUTOSAR: ['AUTOSAR Architecture'],
-  // Drawn on the map but without their own README section: open the protocol family instead.
-  Profinet: ['Industrial Protocols'],
-  LIN: ['Automotive Protocols'],
-  MOST: ['Automotive Protocols'],
-  FlexRay: ['Automotive Protocols'],
-  UWB: ['Wireless Protocols'],
-};
-
 export const AREA_ORDER = ['SOFTWARE', 'HARDWARE', 'SOFT SKILLS'];
 export const IMPORTANCE_LEVELS = ['required', 'recommended', 'possible'];
 const RANK = { required: 3, recommended: 2, possible: 1 };
@@ -61,8 +27,10 @@ function topicIndex(topics) {
 export function linkDiagram(map, data) {
   const index = topicIndex(data.topics);
   const softSkills = data.topics.find((t) => t.depth === 1 && key(t.title) === 'soft skills');
+  // map.json "readme": map labels whose README heading is worded differently (or has no section of its own).
+  const aliases = map.readme || {};
   const resolve = (text, areas = []) => {
-    if (ALIASES[text]) return ALIASES[text].map((title) => index.get(key(title))).filter(Boolean);
+    if (Object.hasOwn(aliases, text)) return [aliases[text]].flat().map((title) => index.get(key(title))).filter(Boolean);
     const topic = index.get(key(text));
     if (topic) return [topic];
     if (softSkills && areas.includes('SOFT SKILLS')) return [softSkills];
@@ -166,6 +134,10 @@ export function linkDiagram(map, data) {
     connections: [...pairs.values()],
     unmatched: boxes.filter((b) => !b.header && !b.topics.length).map((b) => b.text),
     invalidLinks,
-    invalid: boxes.filter((b) => !b.header && !IMPORTANCE_LEVELS.includes(b.importance)).map((b) => `${b.text}: ${b.importance}`),
+    invalidReadme: Object.entries(aliases).flatMap(([label, titles]) => {
+      const onMap = boxes.some((b) => b.text === label) || label in map.groups;
+      const missing = [titles].flat().filter((title) => !index.has(key(title)));
+      return onMap && !missing.length ? [] : [`${label} -> ${[titles].flat().join(' + ')}`];
+    }),    invalid: boxes.filter((b) => !b.header && !IMPORTANCE_LEVELS.includes(b.importance)).map((b) => `${b.text}: ${b.importance}`),
   };
 }

site/map.json

@@ -472,5 +472,37 @@
     "Operating Systems": ["osBase", "linux", "rtos"],
     "Microcontrollers": ["rtos", "mcu"],
     "Interfaces & Protocols": ["basic", "wireless", "highSpeed", "industrial", "cellular", "network", "automotive"]
+  },
+  "offMap": ["Don't Know Where to Start!", "Appendix-A: Advanced Topics"],
+  "readme": {
+    "ADC / DAC": ["ADC", "DAC"],
+    "Buildroot / Yocto": ["Buildroot", "Yocto"],
+    "TDD & Unit Testing": ["Test Driven Development (TDD)", "Unit Testing"],
+    "Threading / Parallelism": ["Multithreading & Parallel Processing"],
+    "Device Drivers": ["Linux Device Drivers"],
+    "Real-Time OS": ["Real-Time Operating Systems"],
+    "Interfaces & Protocols": ["Interfaces, Protocols & Communication Technologies"],
+    "Basic": ["Basic Protocols"],
+    "High-Speed": ["High-Speed Protocols"],
+    "Wireless": ["Wireless Protocols"],
+    "Industrial": ["Industrial Protocols"],
+    "Automotive": ["Automotive Protocols"],
+    "Network": ["Network Protocols / Socket Programming"],
+    "TCP/IP": ["Network Protocols / Socket Programming"],
+    "UDP": ["Network Protocols / Socket Programming"],
+    "Cellular": ["Cellular Communication"],
+    "MQTT": ["CoAP & MQTT"],
+    "CoAP": ["CoAP & MQTT"],
+    "LTE-M / 5G": ["LTE-M & NB-IoT"],
+    "NB-IoT": ["LTE-M & NB-IoT"],
+    "Basic Math & Calculus": ["Basic Calculus"],
+    "SDLC Models": ["Software Development Life Cycle (SDLC) Models"],
+    "Version Control": ["Version Control Systems"],
+    "AUTOSAR": ["AUTOSAR Architecture"],
+    "Profinet": ["Industrial Protocols"],
+    "LIN": ["Automotive Protocols"],
+    "MOST": ["Automotive Protocols"],
+    "FlexRay": ["Automotive Protocols"],
+    "UWB": ["Wireless Protocols"]
   }
 }

site/parser.test.mjs

@@ -56,7 +56,8 @@ const map = JSON.parse(readFileSync(new URL('./map.json', import.meta.url), 'utf
 
 test('places topics in the map areas and their cross-section', () => {
   const plan = linkDiagram(map, data);
-  assert.deepEqual(plan.unmatched, [], 'every map topic matches a README heading (or an alias in diagram.js)');
+  assert.deepEqual(plan.unmatched, [], 'every map topic matches a README heading (or a "readme" entry in map.json)');
+  assert.deepEqual(plan.invalidReadme, [], 'map.json "readme" entries name a topic on the map and existing README headings');
   assert.deepEqual(plan.invalid, [], 'importance is required, recommended or possible');
   assert.deepEqual(find('GPIO').areas, ['SOFTWARE', 'HARDWARE']);
   assert.deepEqual(find('I2C').areas, ['SOFTWARE', 'HARDWARE']);

site/tools/coverage.mjs

@@ -0,0 +1,20 @@
+// Warns (never fails) about README sections that have no place on the map yet.
+// Usage: node site/tools/coverage.mjs        Sections listed in map.json "offMap" (titles or group names) are skipped.
+import { readFileSync } from 'node:fs';
+import { parseRoadmap } from '../parser.js';
+import { linkDiagram } from '../diagram.js';
+
+const read = (path) => readFileSync(new URL(path, import.meta.url), 'utf8');
+const map = JSON.parse(read('../map.json'));
+const data = parseRoadmap(read('../../README.md'));
+const plan = linkDiagram(map, data);
+
+const drawn = new Set(plan.boxes.flatMap((b) => b.topics));
+const onMap = (t) => drawn.has(t) || t.children.some(onMap);
+const skipped = new Set(map.offMap || []);
+const missing = data.root.children.filter((t) => !skipped.has(t.title) && !skipped.has(t.group) && !onMap(t));
+
+for (const t of missing) {
+  console.log(`::warning file=README.md,title=Not on the roadmap map::"${t.title}" has no box on the map. Add it to site/map.json, or to "offMap" if it should stay off the map (see CONTRIBUTING.md).`);
+}
+console.log(missing.length ? `${missing.length} README section(s) are not on the map.` : 'Every README section is on the map or listed in "offMap".');