@nowline/export-xlsx 0.2.0

package/dist/zip-normalize.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Overwrite every per-entry timestamp inside a ZIP buffer with a
+ * deterministic value derived from `date`. Mutates `bytes` in place and
+ * returns it for chaining.
+ *
+ * Throws if the buffer is not a well-formed single-disk ZIP (no EOCD found,
+ * or the central-directory walk hits a bad signature).
+ */
+export declare function normalizeZipTimestamps(bytes: Uint8Array, date: Date): Uint8Array;
+//# sourceMappingURL=zip-normalize.d.ts.map

package/dist/zip-normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-normalize.d.ts","sourceRoot":"","sources":["../src/zip-normalize.ts"],"names":[],"mappings":"AAyBA;;;;;;;GAOG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,UAAU,EAAE,IAAI,EAAE,IAAI,GAAG,UAAU,CAuChF"}

package/dist/zip-normalize.js

@@ -0,0 +1,128 @@
+// ZIP timestamp normalizer.
+//
+// XLSX is a ZIP archive. ExcelJS uses JSZip internally, and JSZip's default
+// per-entry mtime is `new Date()` — which means two consecutive calls to
+// `wb.xlsx.writeBuffer()` produce different bytes whenever the wall clock
+// advances between them. The workbook's own `created`/`modified` properties
+// are pinned in `index.ts`, but the per-entry ZIP headers are not.
+//
+// This module overwrites the `last mod time` / `last mod date` fields in
+// every Local File Header and Central Directory File Header with a
+// deterministic value derived from a fixed Date. CRC32s, compressed sizes,
+// and the compressed payloads themselves are not part of those fields, so
+// patching is safe and does not require re-deflating any data.
+//
+// References:
+//   - APPNOTE.TXT (ZIP spec) §4.3.7, §4.4.6, §4.5
+//   - DOS date/time encoding: APPNOTE.TXT §4.4.6
+const SIG_LFH = 0x04034b50; // "PK\x03\x04"
+const SIG_CDFH = 0x02014b50; // "PK\x01\x02"
+const SIG_EOCD = 0x06054b50; // "PK\x05\x06"
+const EXTRA_EXTENDED_TIMESTAMP = 0x5455; // "UT" — Info-ZIP extended timestamp
+const EXTRA_NTFS = 0x000a; // NTFS file times
+/**
+ * Overwrite every per-entry timestamp inside a ZIP buffer with a
+ * deterministic value derived from `date`. Mutates `bytes` in place and
+ * returns it for chaining.
+ *
+ * Throws if the buffer is not a well-formed single-disk ZIP (no EOCD found,
+ * or the central-directory walk hits a bad signature).
+ */
+export function normalizeZipTimestamps(bytes, date) {
+    const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+    const dosTime = toDosTime(date);
+    const dosDate = toDosDate(date);
+    const unixSeconds = Math.floor(date.getTime() / 1000);
+    const eocdOffset = findEocd(view);
+    const cdSize = view.getUint32(eocdOffset + 12, true);
+    const cdOffset = view.getUint32(eocdOffset + 16, true);
+    const cdEnd = cdOffset + cdSize;
+    let p = cdOffset;
+    while (p < cdEnd) {
+        if (view.getUint32(p, true) !== SIG_CDFH) {
+            throw new Error(`normalizeZipTimestamps: bad CDFH signature at offset ${p}`);
+        }
+        const nameLen = view.getUint16(p + 28, true);
+        const extraLen = view.getUint16(p + 30, true);
+        const commentLen = view.getUint16(p + 32, true);
+        const lfhOffset = view.getUint32(p + 42, true);
+        view.setUint16(p + 12, dosTime, true);
+        view.setUint16(p + 14, dosDate, true);
+        patchExtraTimestamps(view, p + 46 + nameLen, extraLen, unixSeconds);
+        if (view.getUint32(lfhOffset, true) !== SIG_LFH) {
+            throw new Error(`normalizeZipTimestamps: bad LFH signature at offset ${lfhOffset}`);
+        }
+        const lfhNameLen = view.getUint16(lfhOffset + 26, true);
+        const lfhExtraLen = view.getUint16(lfhOffset + 28, true);
+        view.setUint16(lfhOffset + 10, dosTime, true);
+        view.setUint16(lfhOffset + 12, dosDate, true);
+        patchExtraTimestamps(view, lfhOffset + 30 + lfhNameLen, lfhExtraLen, unixSeconds);
+        p += 46 + nameLen + extraLen + commentLen;
+    }
+    return bytes;
+}
+function patchExtraTimestamps(view, start, length, unixSeconds) {
+    let p = start;
+    const end = start + length;
+    while (p + 4 <= end) {
+        const id = view.getUint16(p, true);
+        const size = view.getUint16(p + 2, true);
+        const dataStart = p + 4;
+        const dataEnd = dataStart + size;
+        if (dataEnd > end)
+            return;
+        if (id === EXTRA_EXTENDED_TIMESTAMP && size >= 5) {
+            // Layout: flags(1) | mtime(4) | [atime(4)] | [ctime(4)]
+            const flags = view.getUint8(dataStart);
+            let off = dataStart + 1;
+            if (off + 4 <= dataEnd) {
+                view.setUint32(off, unixSeconds, true);
+                off += 4;
+            }
+            if ((flags & 0x02) !== 0 && off + 4 <= dataEnd) {
+                view.setUint32(off, unixSeconds, true);
+                off += 4;
+            }
+            if ((flags & 0x04) !== 0 && off + 4 <= dataEnd) {
+                view.setUint32(off, unixSeconds, true);
+            }
+        }
+        else if (id === EXTRA_NTFS && size >= 32) {
+            // Layout: reserved(4) | tag1=0x0001 | size1=24 | mtime(8) | atime(8) | ctime(8)
+            // Times are Win32 FILETIME (100-ns intervals since 1601-01-01).
+            const fileTime = unixSecondsToFiletime(unixSeconds);
+            const attrStart = dataStart + 4 + 4; // skip reserved + tag/size
+            view.setBigUint64(attrStart + 0, fileTime, true);
+            view.setBigUint64(attrStart + 8, fileTime, true);
+            view.setBigUint64(attrStart + 16, fileTime, true);
+        }
+        p = dataEnd;
+    }
+}
+function findEocd(view) {
+    const len = view.byteLength;
+    const minSize = 22;
+    const maxComment = 0xffff;
+    const searchStart = Math.max(0, len - minSize - maxComment);
+    for (let i = len - minSize; i >= searchStart; i--) {
+        if (view.getUint32(i, true) === SIG_EOCD)
+            return i;
+    }
+    throw new Error('normalizeZipTimestamps: end-of-central-directory record not found');
+}
+function toDosTime(d) {
+    return (((d.getUTCHours() & 0x1f) << 11) |
+        ((d.getUTCMinutes() & 0x3f) << 5) |
+        (Math.floor(d.getUTCSeconds() / 2) & 0x1f));
+}
+function toDosDate(d) {
+    // DOS year is offset from 1980; clamp to that floor so any pre-1980 Date
+    // produces a valid (zero) field rather than overflowing.
+    const year = Math.max(0, d.getUTCFullYear() - 1980);
+    return ((year & 0x7f) << 9) | (((d.getUTCMonth() + 1) & 0xf) << 5) | (d.getUTCDate() & 0x1f);
+}
+const FILETIME_EPOCH_OFFSET = 11644473600n; // seconds between 1601-01-01 and 1970-01-01
+function unixSecondsToFiletime(unixSeconds) {
+    return (BigInt(unixSeconds) + FILETIME_EPOCH_OFFSET) * 10000000n;
+}
+//# sourceMappingURL=zip-normalize.js.map

package/dist/zip-normalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"zip-normalize.js","sourceRoot":"","sources":["../src/zip-normalize.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@nowline/export-xlsx",
+  "version": "0.2.0",
+  "description": "Nowline XLSX exporter — five-sheet workbook via ExcelJS",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/",
+    "src/"
+  ],
+  "dependencies": {
+    "exceljs": "4.4.0",
+    "@nowline/export-core": "0.2.0",
+    "@nowline/core": "0.2.0",
+    "@nowline/layout": "0.2.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "langium": "~4.2.2",
+    "typescript": "~5.7.0",
+    "vitest": "^3.1.0"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "watch": "tsc -b tsconfig.json --watch",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}

package/src/duration.ts

@@ -0,0 +1,49 @@
+// Convert Nowline duration tokens into a numeric working-day count for the
+// XLSX "Duration" column. Spec: specs/handoffs/m2c.md § 7
+// "Resolution 5: numeric working-day duration".
+//
+// We expose two artifacts:
+//   - `durationToWorkingDays(literal)` for the cell value (Number type so
+//     Excel SUM / sort / filter work).
+//   - `durationLiteralToText(literal)` for the optional display column
+//     (preserves the original DSL text — `2w`, `xl`, `1m`, …).
+
+const SIZE_BUCKET_DAYS: Readonly<Record<string, number>> = {
+    xs: 1,
+    sm: 3,
+    s: 3,
+    md: 5,
+    m: 5,
+    lg: 10,
+    l: 10,
+    xl: 15,
+};
+
+const NUMERIC_RE = /^(\d+(?:\.\d+)?)\s*(d|w|m|y)?$/i;
+
+const WORKING_DAYS_PER_WEEK = 5;
+const WORKING_DAYS_PER_MONTH = 22;
+const WORKING_DAYS_PER_YEAR = 252;
+
+/** 0 if the literal is missing/invalid (Excel sums treat 0 as no-op). */
+export function durationToWorkingDays(literal: string | undefined): number {
+    if (!literal) return 0;
+    const trimmed = literal.trim().toLowerCase();
+    if (!trimmed) return 0;
+    if (trimmed in SIZE_BUCKET_DAYS) return SIZE_BUCKET_DAYS[trimmed];
+    const match = NUMERIC_RE.exec(trimmed);
+    if (!match) return 0;
+    const value = Number(match[1]);
+    if (!Number.isFinite(value) || value <= 0) return 0;
+    const unit = (match[2] ?? 'd').toLowerCase();
+    if (unit === 'd') return value;
+    if (unit === 'w') return value * WORKING_DAYS_PER_WEEK;
+    if (unit === 'm') return value * WORKING_DAYS_PER_MONTH;
+    if (unit === 'y') return value * WORKING_DAYS_PER_YEAR;
+    return 0;
+}
+
+export function durationLiteralToText(literal: string | undefined): string {
+    if (!literal) return '';
+    return literal.trim();
+}

package/src/index.ts

@@ -0,0 +1,384 @@
+// XLSX exporter — five-sheet workbook via ExcelJS.
+//
+// Spec: specs/handoffs/m2c.md § 7 + specs/rendering.md § XLSX Export.
+// Decisions:
+//   - Resolution 5 (working-day duration): the "Duration" cell is a NUMBER
+//     of working days; an extra "Duration (text)" column preserves the
+//     original DSL literal. Excel can SUM and filter the numeric column
+//     without a custom formatter.
+//   - Resolution 8 (deterministic ExcelJS): pin a single ExcelJS version in
+//     `package.json`. Any zip-level non-determinism is patched at write time
+//     by re-emitting the package's content streams in deterministic order.
+//
+// Determinism contract:
+//   - workbook.created = `inputs.today` (UTC midnight) — never `new Date()`
+//     in default code path.
+//   - Sheet 1 ("Roadmap") "Generated" cell takes the same `today`.
+//   - Style ids and column orders are explicit so ExcelJS's id allocator
+//     emits the same numbers across runs.
+//   - JSZip (used by ExcelJS to pack the .xlsx archive) stamps every entry
+//     with `new Date()` by default; we rewrite all per-entry `last mod
+//     time/date` fields to `generated` after `writeBuffer()` so two
+//     consecutive calls with identical inputs produce byte-identical
+//     output. See `zip-normalize.ts` for the patcher.
+
+import type {
+    AnchorDeclaration,
+    GroupBlock,
+    GroupContent,
+    ItemDeclaration,
+    MilestoneDeclaration,
+    NowlineFile,
+    ParallelBlock,
+    PersonDeclaration,
+    SwimlaneContent,
+    SwimlaneDeclaration,
+    TeamDeclaration,
+} from '@nowline/core';
+import type { ExportInputs } from '@nowline/export-core';
+import { displayLabel, getProp, getProps, roadmapTitle } from '@nowline/export-core';
+import ExcelJS from 'exceljs';
+
+import { durationLiteralToText, durationToWorkingDays } from './duration.js';
+import { normalizeZipTimestamps } from './zip-normalize.js';
+
+export interface XlsxOptions {
+    /** Override the workbook author / Roadmap-sheet "Author" cell. */
+    author?: string;
+    /** Override the "Generated" timestamp; defaults to `inputs.today`. */
+    generated?: Date;
+}
+
+export async function exportXlsx(
+    inputs: ExportInputs,
+    options: XlsxOptions = {},
+): Promise<Uint8Array> {
+    const wb = new ExcelJS.Workbook();
+    const today = options.generated ?? inputs.today ?? new Date(Date.UTC(2026, 0, 5));
+    const generated = new Date(
+        Date.UTC(today.getUTCFullYear(), today.getUTCMonth(), today.getUTCDate()),
+    );
+    wb.creator = options.author ?? inferAuthor(inputs.ast) ?? 'nowline';
+    wb.lastModifiedBy = wb.creator;
+    wb.created = generated;
+    wb.modified = generated;
+    wb.title = roadmapTitle(inputs.ast.roadmapDecl ?? undefined);
+
+    buildRoadmapSheet(wb, inputs, generated);
+    buildItemsSheet(wb, inputs.ast);
+    buildMilestonesSheet(wb, inputs.ast);
+    buildAnchorsSheet(wb, inputs.ast);
+    buildPeopleAndTeamsSheet(wb, inputs.ast);
+
+    const buf = (await wb.xlsx.writeBuffer()) as ArrayBuffer | Buffer;
+    const bytes = Buffer.isBuffer(buf)
+        ? new Uint8Array(buf.buffer, buf.byteOffset, buf.byteLength)
+        : new Uint8Array(buf);
+    return normalizeZipTimestamps(bytes, generated);
+}
+
+function inferAuthor(ast: NowlineFile): string | undefined {
+    const decl = ast.roadmapDecl;
+    if (!decl) return undefined;
+    return decl.properties.find((p) => p.key === 'author')?.value;
+}
+
+// ---------- Sheet 1: Roadmap ----------
+
+function buildRoadmapSheet(wb: ExcelJS.Workbook, inputs: ExportInputs, generated: Date): void {
+    const sheet = wb.addWorksheet('Roadmap');
+    const decl = inputs.ast.roadmapDecl;
+    const scale = decl ? getProp(decl, 'scale') : undefined;
+    const start = decl ? getProp(decl, 'start') : undefined;
+
+    const rows: [string, string | number | Date | undefined][] = [
+        ['Roadmap', roadmapTitle(decl ?? undefined)],
+        ['Author', inputs.ast.roadmapDecl ? (getProp(inputs.ast.roadmapDecl, 'author') ?? '') : ''],
+        ['Scale', scale ?? ''],
+        ['Start', start ?? ''],
+        ['Generated', generated],
+    ];
+    rows.forEach((row, idx) => {
+        const r = sheet.addRow(row);
+        r.getCell(1).font = { bold: true };
+        if (idx === 4) r.getCell(2).numFmt = 'yyyy-mm-dd';
+    });
+    sheet.columns = [
+        { key: 'field', width: 16 },
+        { key: 'value', width: 36 },
+    ];
+}
+
+// ---------- Sheet 2: Items ----------
+
+const ITEM_HEADERS: ReadonlyArray<{ header: string; key: string; width: number }> = [
+    { header: 'ID', key: 'id', width: 18 },
+    { header: 'Title', key: 'title', width: 28 },
+    { header: 'Swimlane', key: 'swimlane', width: 22 },
+    { header: 'Group', key: 'group', width: 18 },
+    { header: 'Parallel', key: 'parallel', width: 18 },
+    { header: 'Duration', key: 'duration', width: 12 },
+    { header: 'Duration (text)', key: 'durationText', width: 16 },
+    { header: 'Status', key: 'status', width: 14 },
+    { header: 'Remaining', key: 'remaining', width: 12 },
+    { header: 'Owner', key: 'owner', width: 14 },
+    { header: 'After', key: 'after', width: 24 },
+    { header: 'Before', key: 'before', width: 24 },
+    { header: 'Labels', key: 'labels', width: 18 },
+    { header: 'Link', key: 'link', width: 24 },
+    { header: 'Description', key: 'description', width: 36 },
+];
+
+const STATUS_FILLS: Readonly<Record<string, string>> = {
+    done: 'FFC8E6C9', // green
+    'in-progress': 'FFBBDEFB', // blue
+    'at-risk': 'FFFFF59D', // yellow
+    blocked: 'FFFFCDD2', // red
+    planned: 'FFE0E0E0', // grey
+};
+
+interface ItemRow {
+    id: string;
+    title: string;
+    swimlane: string;
+    group: string;
+    parallel: string;
+    duration: number;
+    durationText: string;
+    status: string;
+    remaining: string;
+    owner: string;
+    after: string;
+    before: string;
+    labels: string;
+    link: string;
+    description: string;
+}
+
+function buildItemsSheet(wb: ExcelJS.Workbook, ast: NowlineFile): void {
+    const sheet = wb.addWorksheet('Items', {
+        views: [{ state: 'frozen', xSplit: 0, ySplit: 1 }],
+    });
+    sheet.columns = [...ITEM_HEADERS];
+
+    const rows: ItemRow[] = [];
+    for (const entry of ast.roadmapEntries) {
+        if (entry.$type === 'SwimlaneDeclaration') {
+            collectFromSwimlane(entry as SwimlaneDeclaration, [entry.name ?? ''], rows, '', '');
+        }
+    }
+    for (const r of rows) sheet.addRow(r);
+
+    // Status conditional formatting via per-row fill; ExcelJS ConditionalFormat
+    // is supported but the per-row fill is simpler and equally deterministic.
+    sheet.eachRow({ includeEmpty: false }, (row, rowNumber) => {
+        if (rowNumber === 1) return;
+        const status = String(row.getCell('status').value ?? '');
+        const fill = STATUS_FILLS[status];
+        if (fill) {
+            row.getCell('status').fill = {
+                type: 'pattern',
+                pattern: 'solid',
+                fgColor: { argb: fill },
+            };
+        }
+    });
+
+    sheet.getRow(1).font = { bold: true };
+    sheet.autoFilter = {
+        from: { row: 1, column: 1 },
+        to: { row: Math.max(rows.length + 1, 1), column: ITEM_HEADERS.length },
+    };
+}
+
+function collectFromSwimlane(
+    lane: SwimlaneDeclaration,
+    breadcrumb: readonly string[],
+    rows: ItemRow[],
+    group: string,
+    parallel: string,
+): void {
+    const breadcrumbStr = breadcrumb.filter((s) => s.length > 0).join('.');
+    for (const child of lane.content) {
+        addSwimlaneChild(child, breadcrumbStr, group, parallel, rows);
+    }
+}
+
+function addSwimlaneChild(
+    child: SwimlaneContent,
+    swimlane: string,
+    group: string,
+    parallel: string,
+    rows: ItemRow[],
+): void {
+    if (child.$type === 'ItemDeclaration') {
+        rows.push(itemRow(child, swimlane, group, parallel));
+        return;
+    }
+    if (child.$type === 'GroupBlock') {
+        const g = child.name ?? displayLabel(child);
+        for (const grandchild of (child as GroupBlock).content as GroupContent[]) {
+            addGroupChild(grandchild, swimlane, g, parallel, rows);
+        }
+        return;
+    }
+    if (child.$type === 'ParallelBlock') {
+        const p = child.name ?? displayLabel(child);
+        for (const grandchild of (child as ParallelBlock).content) {
+            if (grandchild.$type === 'ItemDeclaration') {
+                rows.push(itemRow(grandchild, swimlane, group, p));
+            } else if (grandchild.$type === 'GroupBlock') {
+                const g = grandchild.name ?? displayLabel(grandchild);
+                for (const inner of (grandchild as GroupBlock).content as GroupContent[]) {
+                    addGroupChild(inner, swimlane, g, p, rows);
+                }
+            }
+        }
+    }
+}
+
+function addGroupChild(
+    child: GroupContent,
+    swimlane: string,
+    group: string,
+    parallel: string,
+    rows: ItemRow[],
+): void {
+    if (child.$type === 'ItemDeclaration') {
+        rows.push(itemRow(child, swimlane, group, parallel));
+    } else if (child.$type === 'GroupBlock') {
+        const sub = child.name ?? displayLabel(child);
+        const nested = group ? `${group}.${sub}` : sub;
+        for (const grandchild of (child as GroupBlock).content as GroupContent[]) {
+            addGroupChild(grandchild, swimlane, nested, parallel, rows);
+        }
+    } else if (child.$type === 'ParallelBlock') {
+        const p = child.name ?? displayLabel(child);
+        for (const grandchild of (child as ParallelBlock).content) {
+            if (grandchild.$type === 'ItemDeclaration') {
+                rows.push(itemRow(grandchild, swimlane, group, p));
+            }
+        }
+    }
+}
+
+function itemRow(
+    item: ItemDeclaration,
+    swimlane: string,
+    group: string,
+    parallel: string,
+): ItemRow {
+    const durationLiteral = getProp(item, 'duration') ?? getProp(item, 'size');
+    return {
+        id: item.name ?? '',
+        title: item.title ?? '',
+        swimlane,
+        group,
+        parallel,
+        duration: durationToWorkingDays(durationLiteral),
+        durationText: durationLiteralToText(durationLiteral),
+        status: getProp(item, 'status') ?? '',
+        remaining: getProp(item, 'remaining') ?? '',
+        owner: getProp(item, 'owner') ?? '',
+        after: getProps(item, 'after').join('; '),
+        before: getProps(item, 'before').join('; '),
+        labels: getProps(item, 'labels').join('; '),
+        link: getProp(item, 'link') ?? '',
+        description: item.description?.text ?? '',
+    };
+}
+
+// ---------- Sheet 3: Milestones ----------
+
+function buildMilestonesSheet(wb: ExcelJS.Workbook, ast: NowlineFile): void {
+    const sheet = wb.addWorksheet('Milestones', {
+        views: [{ state: 'frozen', xSplit: 0, ySplit: 1 }],
+    });
+    sheet.columns = [
+        { header: 'ID', key: 'id', width: 18 },
+        { header: 'Title', key: 'title', width: 28 },
+        { header: 'Date', key: 'date', width: 14 },
+        { header: 'Depends', key: 'depends', width: 28 },
+    ];
+    for (const entry of ast.roadmapEntries) {
+        if (entry.$type === 'MilestoneDeclaration') {
+            const m = entry as MilestoneDeclaration;
+            sheet.addRow({
+                id: m.name ?? '',
+                title: m.title ?? '',
+                date: getProp(m, 'date') ?? '',
+                depends: getProps(m, 'depends').join('; '),
+            });
+        }
+    }
+    sheet.getRow(1).font = { bold: true };
+}
+
+// ---------- Sheet 4: Anchors ----------
+
+function buildAnchorsSheet(wb: ExcelJS.Workbook, ast: NowlineFile): void {
+    const sheet = wb.addWorksheet('Anchors', {
+        views: [{ state: 'frozen', xSplit: 0, ySplit: 1 }],
+    });
+    sheet.columns = [
+        { header: 'ID', key: 'id', width: 18 },
+        { header: 'Title', key: 'title', width: 28 },
+        { header: 'Date', key: 'date', width: 14 },
+    ];
+    for (const entry of ast.roadmapEntries) {
+        if (entry.$type === 'AnchorDeclaration') {
+            const a = entry as AnchorDeclaration;
+            sheet.addRow({
+                id: a.name ?? '',
+                title: a.title ?? '',
+                date: getProp(a, 'date') ?? '',
+            });
+        }
+    }
+    sheet.getRow(1).font = { bold: true };
+}
+
+// ---------- Sheet 5: People and Teams ----------
+
+function buildPeopleAndTeamsSheet(wb: ExcelJS.Workbook, ast: NowlineFile): void {
+    const sheet = wb.addWorksheet('People and Teams', {
+        views: [{ state: 'frozen', xSplit: 0, ySplit: 1 }],
+    });
+    sheet.columns = [
+        { header: 'ID', key: 'id', width: 18 },
+        { header: 'Title', key: 'title', width: 28 },
+        { header: 'Type', key: 'type', width: 10 },
+        { header: 'Parent Team', key: 'parent', width: 18 },
+        { header: 'Link', key: 'link', width: 28 },
+    ];
+    for (const entry of ast.roadmapEntries) {
+        if (entry.$type === 'PersonDeclaration') {
+            const p = entry as PersonDeclaration;
+            sheet.addRow({
+                id: p.name ?? '',
+                title: p.title ?? '',
+                type: 'person',
+                parent: '',
+                link: getProp(p, 'link') ?? '',
+            });
+        } else if (entry.$type === 'TeamDeclaration') {
+            walkTeam(entry as TeamDeclaration, '', sheet);
+        }
+    }
+    sheet.getRow(1).font = { bold: true };
+}
+
+function walkTeam(team: TeamDeclaration, parent: string, sheet: ExcelJS.Worksheet): void {
+    sheet.addRow({
+        id: team.name ?? '',
+        title: team.title ?? '',
+        type: 'team',
+        parent,
+        link: getProp(team, 'link') ?? '',
+    });
+    for (const child of team.content) {
+        if (child.$type === 'TeamDeclaration') {
+            walkTeam(child as TeamDeclaration, team.name ?? '', sheet);
+        }
+    }
+}