@jenga-ai/agent 3.2.0 → 3.5.0

package/project/app/api/parsers/board.js

@@ -0,0 +1,141 @@
+/**
+ * @file project/app/api/parsers/board.js
+ * Parses markdown files from project/board/ into a nested epic→story→task tree.
+ *
+ * E06_S05_T04 — each item whose id is named by an active entry in the project's `project/todo.md`
+ * additionally carries `_queued: true`. This is purely *informational* provenance ("the user has
+ * queued this for execution"); the decision of what to do with it belongs to the consumer. The
+ * Active Sprint tab's column logic (`project/app/ui/src/components/board/kanbanColumns.js`) uses it
+ * to promote `Pending`/`Backlog` items into the In Progress column; the Backlog tab ignores it
+ * entirely. Items that aren't referenced get **no new field at all**, so a project with no
+ * `todo.md` produces a byte-identical payload to the pre-T04 parser.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readTodoRefs } = require('./todo');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — the old `path.resolve(__dirname, '../../../board')` only ever landed correctly when this
+// module ran from this monorepo's own checkout.
+const BOARD_ROOT = path.join(resolveProjectRoot(), 'project', 'board');
+
+/**
+ * Read all .md files from a directory (non-recursive).
+ * @param {string} dir
+ * @returns {{ file: string, data: Object, content: string }[]}
+ */
+function readMarkdownDir(dir) {
+  if (!fs.existsSync(dir)) return [];
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f.endsWith('.md'))
+    .map((f) => {
+      const filePath = path.join(dir, f);
+      try {
+        const raw = fs.readFileSync(filePath, 'utf8');
+        const parsed = matter(raw);
+        return { file: f, data: parsed.data, content: parsed.content.trim() };
+      } catch (err) {
+        console.warn(`[board] Skipping malformed file: ${filePath} — ${err.message}`);
+        return null;
+      }
+    })
+    .filter(Boolean);
+}
+
+/**
+ * Board ids referenced by active entries in the project's `project/todo.md`, as an upper-cased Set
+ * for case-insensitive lookup (E06_S05_T04).
+ *
+ * Failure-tolerant by design: `readTodoRefs()` already reports a missing/unreadable file as
+ * `exists: false` rather than throwing, and this extra guard covers anything unexpected beyond that
+ * (e.g. an unresolvable project root). A broken or absent `todo.md` degrades to "nothing is queued"
+ * — i.e. exactly the pre-T04 behavior — and never turns a working board read into a 500.
+ *
+ * @returns {Set<string>}
+ */
+function loadQueuedIds() {
+  try {
+    const { refs } = readTodoRefs();
+    return new Set(refs.map((r) => String(r).toUpperCase()));
+  } catch (err) {
+    console.warn(`[board] Could not read todo.md refs — ${err.message}. No items will be marked queued.`);
+    return new Set();
+  }
+}
+
+/**
+ * `{ _queued: true }` if `id` is queued, otherwise an empty object — spread into an item so
+ * unreferenced items keep their exact pre-T04 shape (no `_queued: false` noise).
+ * @param {Set<string>} queuedIds
+ * @param {string|undefined} id
+ * @returns {{ _queued?: boolean }}
+ */
+function queuedFlagFor(queuedIds, id) {
+  return typeof id === 'string' && queuedIds.has(id.toUpperCase()) ? { _queued: true } : {};
+}
+
+/**
+ * Parse the full board into an array of epic objects with nested stories and tasks.
+ * @returns {Promise<Object[]>}
+ */
+async function parseBoard() {
+  const queuedIds = loadQueuedIds();
+
+  const epicsDir  = path.join(BOARD_ROOT, 'epics');
+  const storiesDir = path.join(BOARD_ROOT, 'stories');
+  const tasksDir  = path.join(BOARD_ROOT, 'tasks');
+
+  const epicFiles  = readMarkdownDir(epicsDir);
+  const storyFiles = readMarkdownDir(storiesDir);
+  const taskFiles  = readMarkdownDir(tasksDir);
+
+  // Build tasks map keyed by story_id
+  const tasksByStory = {};
+  for (const t of taskFiles) {
+    const sid = t.data.story_id;
+    if (!sid) continue;
+    if (!tasksByStory[sid]) tasksByStory[sid] = [];
+    tasksByStory[sid].push({
+      ...t.data,
+      ...queuedFlagFor(queuedIds, t.data.id),
+      _content: t.content,
+      _file: t.file,
+    });
+  }
+
+  // Build stories map keyed by epic_id
+  const storiesByEpic = {};
+  for (const s of storyFiles) {
+    const eid = s.data.epic_id;
+    if (!eid) continue;
+    if (!storiesByEpic[eid]) storiesByEpic[eid] = [];
+    const storyId = s.data.id;
+    storiesByEpic[eid].push({
+      ...s.data,
+      ...queuedFlagFor(queuedIds, storyId),
+      _content: s.content,
+      _file: s.file,
+      tasks: storyId ? (tasksByStory[storyId] || []) : [],
+    });
+  }
+
+  // Build epic objects
+  const epics = epicFiles.map((e) => {
+    const epicId = e.data.id;
+    return {
+      ...e.data,
+      ...queuedFlagFor(queuedIds, epicId),
+      _content: e.content,
+      _file: e.file,
+      stories: epicId ? (storiesByEpic[epicId] || []) : [],
+    };
+  });
+
+  return epics;
+}
+
+module.exports = { parseBoard };

package/project/app/api/parsers/documentation.js

@@ -0,0 +1,125 @@
+/**
+ * @file project/app/api/parsers/documentation.js
+ * Aggregates the project's curated reference documentation into one flat, categorized list of
+ * full-content entries — the "Documentation" tab's backend source (`E58_S01_T04`, consumed by
+ * `E58_S01_T05`'s `GET /v1/documentation` route).
+ *
+ * Four sources, none of which any existing parser touches today:
+ *   - `project/PROJECT_SUMMARY.md`                    -> category `summary`
+ *   - `README.md` (repo root)                         -> category `readme`
+ *   - `docs/STRATEGY.md`                               -> category `strategy`
+ *   - every `.md` file under `project/documentation/examples/` -> category `example`
+ *
+ * The first three are single named files, read directly and parsed with `gray-matter` for
+ * consistency with the directory-based path even though they rarely carry frontmatter. The fourth
+ * reuses `E58_S01_T01`'s shared `readMarkdownDirRecursive()` directory reader.
+ *
+ * Every returned entry shares the same field shape used by `E58_S01_T03`'s rapports aggregate:
+ *   { file, data, content, category, date }
+ * `readMarkdownDirRecursive()`'s own return contract does not include `date` (see its JSDoc), so
+ * it is added here per entry — same pattern already used by `parsers/ideas.js` (E58_S01_T02) and
+ * `parsers/rapports.js`: prefer frontmatter's `date` field, stringified, else `null`.
+ *
+ * A missing single-file source (e.g. no `docs/STRATEGY.md` yet in some projects) is skipped, not
+ * thrown — the same non-throwing precedent used throughout `api/parsers/`.
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+const { readMarkdownDirRecursive } = require('./lib/markdown-dir-reader');
+
+/**
+ * Derive the `date` field for an entry from its parsed frontmatter, matching the
+ * `rapports.js`/`ideas.js` convention: prefer frontmatter's `date`, stringified; else `null`.
+ *
+ * Unquoted `YYYY-MM-DD` frontmatter values are parsed by gray-matter/js-yaml into a native `Date`
+ * object rather than a plain string (the same gotcha `E06_S05_T03` hit and fixed for
+ * `isStaleDeployedProd()` — see `project/rapports/problems/E06_S05_T03-stale-filter-fails-on-real-gray-matter-date-objects.md`).
+ * A bare `String(date)` on a `Date` produces a full JS date-with-timezone string, not the
+ * `YYYY-MM-DD` form callers expect, so `Date` inputs are explicitly reduced to their ISO calendar
+ * date (`toISOString().slice(0, 10)`) instead.
+ * @param {Object} data - gray-matter-parsed frontmatter object.
+ * @returns {string|null}
+ */
+function deriveDate(data) {
+  if (!data || !data.date) return null;
+  if (data.date instanceof Date) return data.date.toISOString().slice(0, 10);
+  return String(data.date);
+}
+
+/**
+ * Read and parse a single markdown file into an aggregate entry, or `null` if the file does not
+ * exist or fails to read/parse (skipped with a `console.warn`, never thrown).
+ * @param {string} absPath - absolute path to the file.
+ * @param {string} fileLabel - value for the returned entry's `file` field (e.g. "README.md").
+ * @param {string} category - value for the returned entry's `category` field.
+ * @returns {{ file: string, data: Object, content: string, category: string, date: string|null }|null}
+ */
+function readSingleMarkdownFile(absPath, fileLabel, category) {
+  if (!fs.existsSync(absPath)) return null;
+
+  try {
+    const raw = fs.readFileSync(absPath, 'utf8');
+    const parsed = matter(raw);
+    return {
+      file: fileLabel,
+      data: parsed.data,
+      content: parsed.content.trim(),
+      category,
+      date: deriveDate(parsed.data),
+    };
+  } catch (err) {
+    console.warn(`[documentation] Skipping malformed file: ${absPath} — ${err.message}`);
+    return null;
+  }
+}
+
+/**
+ * Aggregate all documentation sources into one flat list of full-content, categorized entries.
+ * Returns [] entries for any source that does not exist rather than throwing.
+ * @returns {Promise<Object[]>}
+ */
+async function readDocumentation() {
+  const root = resolveProjectRoot();
+  const results = [];
+
+  const singleFileSources = [
+    {
+      absPath: path.join(root, 'project', 'PROJECT_SUMMARY.md'),
+      fileLabel: 'PROJECT_SUMMARY.md',
+      category: 'summary',
+    },
+    {
+      absPath: path.join(root, 'README.md'),
+      fileLabel: 'README.md',
+      category: 'readme',
+    },
+    {
+      absPath: path.join(root, 'docs', 'STRATEGY.md'),
+      fileLabel: 'STRATEGY.md',
+      category: 'strategy',
+    },
+  ];
+
+  for (const source of singleFileSources) {
+    const entry = readSingleMarkdownFile(source.absPath, source.fileLabel, source.category);
+    if (entry) results.push(entry);
+  }
+
+  const examplesRoot = path.join(root, 'project', 'documentation', 'examples');
+  // Fixed category for every file under this root, regardless of subdirectory — passed as a
+  // function per readMarkdownDirRecursive()'s categorize contract (a bare string is not one of
+  // its two supported forms and would silently fall back to 'uncategorized').
+  const exampleEntries = readMarkdownDirRecursive(examplesRoot, () => 'example');
+  for (const entry of exampleEntries) {
+    results.push({ ...entry, date: deriveDate(entry.data) });
+  }
+
+  return results;
+}
+
+module.exports = { readDocumentation };

package/project/app/api/parsers/git-log.js

@@ -0,0 +1,52 @@
+/**
+ * @file project/app/api/parsers/git-log.js
+ * Reads git log history as an array of commit objects.
+ */
+
+const { execFile } = require('child_process');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const REPO_ROOT = resolveProjectRoot();
+const SEP = '|||';
+const FORMAT = `%H${SEP}%an${SEP}%aI${SEP}%s${SEP}%b`;
+
+/**
+ * Run git log and return parsed commit entries.
+ * Returns [] if not a git repo or git is unavailable.
+ * @returns {Promise<Object[]>}
+ */
+function readGitLog() {
+  return new Promise((resolve) => {
+    execFile(
+      'git',
+      ['log', `--format=${FORMAT}`, '--max-count=200'],
+      { cwd: REPO_ROOT, timeout: 10000 },
+      (err, stdout) => {
+        if (err) {
+          // Not a git repo or git unavailable — return empty
+          return resolve([]);
+        }
+        const commits = stdout
+          .split('\n')
+          .filter((line) => line.includes(SEP))
+          .map((line) => {
+            const [sha, author, date, subject, ...bodyParts] = line.split(SEP);
+            return {
+              type: 'git_commit',
+              sha: sha.trim(),
+              author: author.trim(),
+              date: date.trim(),
+              subject: subject.trim(),
+              body: bodyParts.join(SEP).trim(),
+            };
+          })
+          .filter((c) => c.sha);
+        resolve(commits);
+      }
+    );
+  });
+}
+
+module.exports = { readGitLog };

package/project/app/api/parsers/ideas.js

@@ -0,0 +1,62 @@
+/**
+ * @file project/app/api/parsers/ideas.js
+ * Parses project/ideas.md — a single flat file (one idea per line, written by the /idea skill)
+ * with no YAML frontmatter — into entries shaped consistently with the directory-reader entries
+ * from E58_S01_T01, so both can be merged into the same aggregate list.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root (E47_S02_T01/T02), not a fixed __dirname
+// climb — see project/app/api/lib/resolve-project-root.js.
+const IDEAS_FILE = path.join(resolveProjectRoot(), 'project', 'ideas.md');
+
+/**
+ * Determine whether a (trimmed) line should be skipped rather than treated as an idea entry.
+ * Mirrors scripts/idea_manager.sh's `real_entries()` filter — blank lines, markdown headers
+ * (`#`), and HTML comments (`<!--`) are structural/template scaffolding, not idea content.
+ * @param {string} trimmedLine
+ * @returns {boolean}
+ */
+function isSkippableLine(trimmedLine) {
+  return trimmedLine === '' || trimmedLine.startsWith('#') || trimmedLine.startsWith('<!--');
+}
+
+/**
+ * Read project/ideas.md and return one entry per non-blank idea line.
+ * Returns [] if project/ideas.md does not exist (same non-throwing precedent as the other parsers).
+ * @returns {Promise<Object[]>}
+ */
+async function readIdeas() {
+  if (!fs.existsSync(IDEAS_FILE)) return [];
+
+  let raw;
+  try {
+    raw = fs.readFileSync(IDEAS_FILE, 'utf8');
+  } catch (err) {
+    console.warn(`[ideas] Skipping unreadable file: ${IDEAS_FILE} — ${err.message}`);
+    return [];
+  }
+
+  const lines = raw.split('\n');
+  const results = [];
+
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (isSkippableLine(trimmed)) continue;
+
+    results.push({
+      file: 'ideas.md',
+      data: {},
+      content: trimmed,
+      category: 'idea',
+      date: null,
+    });
+  }
+
+  return results;
+}
+
+module.exports = { readIdeas };

package/project/app/api/parsers/knowledge-graph.js

@@ -0,0 +1,73 @@
+/**
+ * @file project/app/api/parsers/knowledge-graph.js
+ * Reads `project/knowledge-graph/graph.json` (E20_S09) and transforms it into the UI-facing
+ * `{nodes:[{id,label,type}], edges:[{from,to,label}]}` shape consumed by the Architecture tab's
+ * SAD map — see `project/knowledge-graph/STUB_SCHEMA.md` for the on-disk node/edge shape this
+ * reads from (id/type/label/description/source/status?/superseded_by? for nodes;
+ * id/from/to/type/description for edges).
+ *
+ * Kept deliberately defensive: the stub schema is explicitly throwaway (pending E20_S01's real
+ * schema), so this reader tolerates a missing file, an empty/malformed file, or unexpected field
+ * shapes by degrading to an empty map rather than throwing.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { resolveProjectRoot } = require('../lib/resolve-project-root');
+
+// Resolved relative to the invoking project's own root, not a fixed __dirname climb — same fix as
+// the other 4 parsers (E47_S02_T01/T02). Not one of the 4 files originally named in E47_S02_T02's
+// scope, but it has the identical defect and directly feeds architecture.js's sad_map field, which
+// the story's own Acceptance Criteria names explicitly ("architecture" data must resolve relative
+// to the invoking project) — see E47_S02_T02-plan.md's "Scope addition" section for the full
+// reasoning.
+const ROOT = resolveProjectRoot();
+const GRAPH_JSON_PATH = path.join(ROOT, 'project/knowledge-graph/graph.json');
+
+/**
+ * Safely read and parse a JSON file, returning null on any error (including a missing file).
+ * @param {string} filePath
+ * @returns {Object|null}
+ */
+function readJsonSafe(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Read and transform `project/knowledge-graph/graph.json` into the UI-facing SAD map shape.
+ * `status: superseded` nodes are excluded. Never throws — returns `{ nodes: [], edges: [] }` for
+ * a missing, empty, or malformed graph.json.
+ * @returns {{ nodes: Array<{id: string, label: string, type: string}>, edges: Array<{from: string, to: string, label: string}> }}
+ */
+function readSADMap() {
+  try {
+    const graph = readJsonSafe(GRAPH_JSON_PATH);
+
+    const rawNodes = graph && Array.isArray(graph.nodes) ? graph.nodes : [];
+    const rawEdges = graph && Array.isArray(graph.edges) ? graph.edges : [];
+
+    const nodes = rawNodes
+      .filter((node) => node && node.status !== 'superseded')
+      .map((node) => ({
+        id: node.id,
+        label: node.label,
+        type: node.type,
+      }));
+
+    const edges = rawEdges.map((edge) => ({
+      from: edge.from,
+      to: edge.to,
+      label: edge.description || edge.type,
+    }));
+
+    return { nodes, edges };
+  } catch {
+    return { nodes: [], edges: [] };
+  }
+}
+
+module.exports = { readSADMap };

package/project/app/api/parsers/lib/markdown-dir-reader.js

@@ -0,0 +1,163 @@
+/**
+ * @file project/app/api/parsers/lib/markdown-dir-reader.js
+ * Shared recursive markdown-directory reader with frontmatter parsing and caller-derived
+ * categorization.
+ *
+ * Generalizes two pre-existing, independently-written directory readers in this codebase:
+ *   - `board.js`'s `readMarkdownDir()` — non-recursive, parses frontmatter + content via
+ *     `gray-matter`, but only reads a single flat directory (epics/stories/tasks are each read
+ *     separately).
+ *   - `rapports.js`'s `listMdFiles()` — recursively walks a directory tree, but only collects file
+ *     paths; frontmatter/content extraction happens separately in `readRapports()`.
+ *
+ * This module merges both: a single recursive walk that also parses frontmatter/content per file,
+ * plus a category derived from a mapping supplied by the caller (this module never hardcodes any
+ * category name — different consumers need different taxonomies from the same walk/parse logic).
+ *
+ * ---------------------------------------------------------------------------------------------
+ * RETURN SHAPE CONTRACT (depended on by E58_S01_T03 [rapports.js] and E58_S01_T04
+ * [documentation.js] — do not change without updating both):
+ *
+ *   readMarkdownDirRecursive(rootDir, categorize) -> Array<{
+ *     file: string,     // path relative to rootDir, POSIX-style separators (e.g. "problems/foo.md"
+ *                        // or "foo.md" for a file directly under rootDir). Never an absolute path.
+ *     data: Object,      // gray-matter-parsed frontmatter object (`{}` if the file has none).
+ *     content: string,   // full markdown body, `gray-matter`'s `content` field with leading/
+ *                        // trailing whitespace trimmed (`.trim()`). Never truncated.
+ *     category: string,  // derived via the caller-supplied `categorize` argument — see below.
+ *   }>
+ *
+ * `categorize` contract:
+ *   - May be a function: `(topLevelSegment, relativeFilePath) => string`
+ *       `topLevelSegment` is the first path segment of the file's path relative to `rootDir`
+ *       (e.g. "problems" for "problems/foo.md"), or `null` when the file sits directly under
+ *       `rootDir` with no subdirectory (e.g. "foo.md").
+ *       `relativeFilePath` is the same POSIX-style relative path that ends up in the returned
+ *       entry's `file` field, in case a consumer needs finer-grained categorization than the
+ *       top-level segment alone.
+ *       The function's return value is used verbatim as `category`.
+ *   - May be a plain lookup object: `{ [topLevelSegment]: categoryString }`. Looked up by the
+ *     file's top-level segment; if the segment is `null` (file directly under rootDir) or has no
+ *     matching key, falls back to the object's own `_default` key if present, else `'uncategorized'`.
+ *   - May be omitted entirely, in which case every entry gets `category: 'uncategorized'`.
+ *
+ * Malformed files (parse errors) are skipped with a `console.warn` — matching the existing
+ * `board.js`/`rapports.js` pattern — rather than aborting the whole walk. A root directory that
+ * does not exist returns `[]` rather than throwing (matches the existing `fs.existsSync` guard
+ * used by both `board.js` and `rapports.js`).
+ * ---------------------------------------------------------------------------------------------
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const matter = require('gray-matter');
+
+const DEFAULT_CATEGORY = 'uncategorized';
+
+/**
+ * Recursively collect absolute paths of every `.md` file under `dir`.
+ * Mirrors rapports.js's listMdFiles(), kept private to this module.
+ * @param {string} dir
+ * @returns {string[]} absolute file paths
+ */
+function listMdFilesRecursive(dir) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...listMdFilesRecursive(full));
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      files.push(full);
+    }
+  }
+  return files;
+}
+
+/**
+ * Normalize a relative path to POSIX-style separators so API payloads never leak `\` on Windows
+ * dev environments.
+ * @param {string} relPath
+ * @returns {string}
+ */
+function toPosixPath(relPath) {
+  return relPath.split(path.sep).join('/');
+}
+
+/**
+ * Derive the top-level subdirectory segment of a POSIX-style relative path, or `null` if the file
+ * sits directly under the root with no subdirectory.
+ * @param {string} posixRelPath
+ * @returns {string|null}
+ */
+function topLevelSegmentOf(posixRelPath) {
+  const idx = posixRelPath.indexOf('/');
+  return idx === -1 ? null : posixRelPath.slice(0, idx);
+}
+
+/**
+ * Resolve a category string for a file given the caller-supplied `categorize` mapping.
+ * @param {Function|Object|undefined} categorize
+ * @param {string|null} topLevelSegment
+ * @param {string} posixRelPath
+ * @returns {string}
+ */
+function resolveCategory(categorize, topLevelSegment, posixRelPath) {
+  if (typeof categorize === 'function') {
+    const result = categorize(topLevelSegment, posixRelPath);
+    return typeof result === 'string' && result.length > 0 ? result : DEFAULT_CATEGORY;
+  }
+  if (categorize && typeof categorize === 'object') {
+    if (topLevelSegment !== null && Object.prototype.hasOwnProperty.call(categorize, topLevelSegment)) {
+      return categorize[topLevelSegment];
+    }
+    if (Object.prototype.hasOwnProperty.call(categorize, '_default')) {
+      return categorize._default;
+    }
+    return DEFAULT_CATEGORY;
+  }
+  return DEFAULT_CATEGORY;
+}
+
+/**
+ * Recursively read all `.md` files under `rootDir`, parsing frontmatter + content via
+ * `gray-matter` and deriving a `category` per file via the caller-supplied `categorize` mapping.
+ *
+ * Returns `[]` if `rootDir` does not exist. Skips (with `console.warn`) any file that fails to
+ * read or parse, rather than aborting the whole walk.
+ *
+ * @param {string} rootDir - absolute path to the directory to walk.
+ * @param {Function|Object} [categorize] - see module-level JSDoc for the full contract.
+ * @returns {{ file: string, data: Object, content: string, category: string }[]}
+ */
+function readMarkdownDirRecursive(rootDir, categorize) {
+  if (!fs.existsSync(rootDir)) return [];
+
+  const absolutePaths = listMdFilesRecursive(rootDir);
+  const results = [];
+
+  for (const absPath of absolutePaths) {
+    try {
+      const raw = fs.readFileSync(absPath, 'utf8');
+      const parsed = matter(raw);
+      const posixRelPath = toPosixPath(path.relative(rootDir, absPath));
+      const topLevelSegment = topLevelSegmentOf(posixRelPath);
+      const category = resolveCategory(categorize, topLevelSegment, posixRelPath);
+
+      results.push({
+        file: posixRelPath,
+        data: parsed.data,
+        content: parsed.content.trim(),
+        category,
+      });
+    } catch (err) {
+      console.warn(`[markdown-dir-reader] Skipping malformed file: ${absPath} — ${err.message}`);
+    }
+  }
+
+  return results;
+}
+
+module.exports = { readMarkdownDirRecursive };