@tmlmobilidade/export-data 20260304.1819.11 → 20260421.1529.44

package/dist/index.js

@@ -20,6 +20,7 @@ import { exportTypeLabels, exportTypesWithoutFilters } from './types.js';
 import { initExportContext } from './utils/init-context.js';
 import { intro, log, outro, tasks } from '@clack/prompts';
 import { ASCII_CM_SHORT } from '@tmlmobilidade/consts';
+import { exportExecutiveSummary } from './tasks/executive-summary-setup/index.js';
 /* * */
 await (async function main() {
     //
@@ -106,6 +107,11 @@ await (async function main() {
             task: async (message) => await exportSamsRaw({ context, message }),
             title: exportTypeLabels['sams-raw'],
         },
+        {
+            enabled: exportTypes.includes('executive-summary'),
+            task: async (message) => await exportExecutiveSummary({ context, message }),
+            title: exportTypeLabels['executive-summary'],
+        },
     ]);
     //
     // Terminate the process

package/dist/prompts/export-types.js

@@ -23,6 +23,9 @@ export async function promptExportTypes() {
             '5. SAMs': [
                 { label: exportTypeLabels['sams-raw'], value: 'sams-raw' },
             ],
+            '6. Sumário Executivo': [
+                { label: exportTypeLabels['executive-summary'], value: 'executive-summary' },
+            ],
         },
         required: true,
     });

package/dist/prompts/filter-line-ids.js

@@ -1,25 +1,19 @@
 /* * */
+import { parseIdListWithRanges, validateIdListWithRanges } from '../utils/parse-id-list.js';
 import { note, text } from '@clack/prompts';
 /* * */
+const DIGITS = 4;
 export async function promptFilterByLineIds() {
     //
     note('FILTRAR POR LINE ID:\n'
         + '  • Introduz os Line IDs separados por vírgulas. Exemplo: 1001,1002,etc...\n'
+        + '  • Introduz o intervalo de Line IDs. Exemplo: 1001-1002\n'
+        + '  • Ambos os formatos podem ser introduzidos juntos. Exemplo: 1001-1002,1003,1004\n'
         + '  • Se não introduzires nenhum Line ID, este filtro não será aplicado.');
     const value = await text({
         message: 'Line IDs:',
-        placeholder: '1001,1002,etc...',
-        validate(value) {
-            if (value.length === 0)
-                return;
-            const ids = value.replace(/,$/, '').split(',').map(id => id.trim());
-            const invalidIds = ids.filter(id => !/^\d{4}$/.test(id));
-            if (invalidIds.length > 0)
-                return `Estes IDs são inválidos: ${invalidIds.join(', ')}`;
-            return;
-        },
+        placeholder: '1001-1004 ou 1001,1002,...',
+        validate: v => (v.length ? validateIdListWithRanges(v, DIGITS) : undefined),
     });
-    if (!value)
-        return [];
-    return value.split(',').map(id => id.trim());
+    return value ? parseIdListWithRanges(String(value), DIGITS) : [];
 }

package/dist/prompts/filter-stop-ids.js

@@ -1,26 +1,19 @@
 /* * */
+import { parseIdListWithRanges, validateIdListWithRanges } from '../utils/parse-id-list.js';
 import { note, text } from '@clack/prompts';
 /* * */
+const DIGITS = 6;
 export async function promptFilterByStopIds() {
     //
     note('FILTRAR POR STOP ID:\n'
         + '  • Introduz os Stop IDs separados por vírgulas. Exemplo: 010101,020202,etc...\n'
+        + '  • Introduz o intervalo de Stop IDs. Exemplo: 01001-01002\n'
         + '  • Não te esqueças do zero à esquerda.\n'
         + '  • Se não introduzires nenhum Stop ID, este filtro não será aplicado.');
     const value = await text({
         message: 'Stop IDs:',
-        placeholder: '010101,020202,etc...',
-        validate(value) {
-            if (value.length === 0)
-                return;
-            const ids = value.replace(/,$/, '').split(',').map(id => id.trim());
-            const invalidIds = ids.filter(id => !/^\d{6}$/.test(id));
-            if (invalidIds.length > 0)
-                return `Estes IDs são inválidos: ${invalidIds.join(', ')}`;
-            return;
-        },
+        placeholder: '010001-010004 ou 010101,020202,...',
+        validate: v => (v.length ? validateIdListWithRanges(v, DIGITS) : undefined),
     });
-    if (!value)
-        return [];
-    return value.split(',').map(id => id.trim());
+    return value ? parseIdListWithRanges(String(value), DIGITS) : [];
 }

package/dist/tasks/executive-summary-setup/avg-trips-day.js

@@ -0,0 +1,68 @@
+// ! THIS IS NOT WORKING, BECAUSE THE @tmlmobilidade/go-performance-pckg-dates is not a published package yet.
+// import { type TaskProps } from '../../types.js';
+// import { Dates } from '@tmlmobilidade/dates';
+// import { type CalendarEntry, fetchCalendarData } from '@tmlmobilidade/go-performance-pckg-dates';
+// import { rides } from '@tmlmobilidade/interfaces';
+export {};
+// export interface AgencyAverageRidesByDayTypeResult {
+// 	agencyId: string
+// 	averageRides: number
+// 	dayType: string
+// }
+// export async function calculateAverageRidesByAgencyByDayType(
+// 	{ context, message }: TaskProps,
+// ): Promise<AgencyAverageRidesByDayTypeResult[]> {
+// 	message('Calculating average rides per agency by day type...');
+// 	const ridesCollection = await rides.getCollection();
+// 	const startDateStr = Dates.fromOperationalDate(context.dates.start, 'Europe/Lisbon').unix_timestamp;
+// 	const endDateStr = Dates.fromOperationalDate(context.dates.end, 'Europe/Lisbon').unix_timestamp;
+// 	// Load calendar JSON
+// 	const calendarJson = await fetchCalendarData();
+// 	// Build calendar map: operational_date -> CalendarEntry
+// 	const calendarMap = new Map<string, CalendarEntry>();
+// 	for (const day of calendarJson) {
+// 		calendarMap.set(day.date.toString(), day);
+// 	}
+// 	// Mongo aggregation: count total rides per agency and date
+// 	const aggCursor = ridesCollection.aggregate([
+// 		{
+// 			$match: {
+// 				agency_id: { $exists: true },
+// 				start_time_scheduled: { $gte: startDateStr, $lte: endDateStr },
+// 				system_status: 'complete',
+// 			},
+// 		},
+// 		{
+// 			$group: {
+// 				_id: { agencyId: '$agency_id', operationalDate: '$operational_date' },
+// 				totalTrips: { $sum: 1 },
+// 			},
+// 		},
+// 	]);
+// 	// Map in-memory: (agencyId + dayType) -> totalRides / totalDays
+// 	const aggregationMap = new Map<string, { agencyId: string, dayType: string, totalDays: number, totalRides: number }>();
+// 	for await (const doc of aggCursor) {
+// 		const agencyId = doc._id.agencyId;
+// 		const operationalDate = doc._id.operationalDate;
+// 		const calendarProps = calendarMap.get(operationalDate);
+// 		const dayType = calendarProps?.day_type ?? '1';
+// 		const key = `${agencyId}:${dayType}`;
+// 		if (!aggregationMap.has(key)) {
+// 			aggregationMap.set(key, { agencyId, dayType, totalDays: 0, totalRides: 0 });
+// 		}
+// 		const entry = aggregationMap.get(key);
+// 		entry.totalRides += doc.totalTrips;
+// 		entry.totalDays += 1;
+// 	}
+// 	// Build final results
+// 	const results: AgencyAverageRidesByDayTypeResult[] = [];
+// 	for (const value of aggregationMap.values()) {
+// 		results.push({
+// 			agencyId: value.agencyId,
+// 			averageRides: parseFloat((value.totalRides / value.totalDays).toFixed(2)),
+// 			dayType: value.dayType,
+// 		});
+// 	}
+// 	message(`Processed ${results.length} agency/day-type combinations`);
+// 	return results;
+// }

package/dist/tasks/executive-summary-setup/empty-runs.js

@@ -0,0 +1,100 @@
+import { Dates } from '@tmlmobilidade/dates';
+import { rides } from '@tmlmobilidade/interfaces';
+/* * */
+/**
+ * Calculates observed trips metrics including % of trips with zero passengers
+ */
+export async function calculateObservedTrips({ context, message }) {
+    message('Calculating observed trips metrics...');
+    // Get the rides collection from MongoDB
+    const ridesCollection = await rides.getCollection();
+    // Convert context dates to YYYYMMDD
+    const startDateStr = Dates.fromOperationalDate(context.dates.start, 'Europe/Lisbon').unix_timestamp;
+    const endDateStr = Dates.fromOperationalDate(context.dates.end, 'Europe/Lisbon').unix_timestamp;
+    message(`Date range: ${startDateStr} to ${endDateStr}`);
+    // Trips with passengers_observed = 0
+    const pipelineZero = [
+        {
+            $match: {
+                agency_id: { $exists: true },
+                passengers_observed: 0,
+                start_time_scheduled: { $gte: startDateStr, $lte: endDateStr },
+            },
+        },
+        {
+            $group: {
+                _id: { agencyId: '$agency_id', date: '$operational_date' },
+                tripszeropassengers: { $sum: 1 },
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agencyId: '$_id.agencyId',
+                date: '$_id.date',
+                tripszeropassengers: 1,
+            },
+        },
+    ];
+    const zeroCursor = ridesCollection.aggregate(pipelineZero);
+    const zeroResults = new Map();
+    for await (const doc of zeroCursor) {
+        const key = `${doc.date}-${doc.agencyId}`;
+        zeroResults.set(key, doc);
+    }
+    // Trips with passengers_observed != 0
+    const pipelineNonZero = [
+        {
+            $match: {
+                agency_id: { $exists: true },
+                operational_date: { $gte: startDateStr, $lte: endDateStr },
+                passengers_observed: { $ne: 0 },
+            },
+        },
+        {
+            $group: {
+                _id: { agencyId: '$agency_id', date: '$operational_date' },
+                tripswpassengers: { $sum: 1 },
+            },
+        },
+        {
+            $project: {
+                _id: 0,
+                agencyId: '$_id.agencyId',
+                date: '$_id.date',
+                tripswpassengers: 1,
+            },
+        },
+    ];
+    const nonZeroCursor = ridesCollection.aggregate(pipelineNonZero);
+    const nonZeroResults = new Map();
+    for await (const doc of nonZeroCursor) {
+        const key = `${doc.date}-${doc.agencyId}`;
+        nonZeroResults.set(key, doc);
+    }
+    // Merge results and calculate tripszeropassengers%
+    const mergedResults = [];
+    const allKeys = new Set([...nonZeroResults.keys(), ...zeroResults.keys()]);
+    for (const key of allKeys) {
+        const zero = zeroResults.get(key);
+        const nonZero = nonZeroResults.get(key);
+        const dateStr = zero?.date ?? nonZero?.date ?? '';
+        const agencyId = zero?.agencyId ?? nonZero?.agencyId ?? '';
+        const formattedDate = Dates.fromOperationalDate(dateStr, 'Europe/Lisbon').toFormat('dd/MM/yyyy');
+        const tripszeropassengers = zero?.tripszeropassengers ?? 0;
+        const tripswpassengers = nonZero?.tripswpassengers ?? 0;
+        // Calculate % of trips with zero passengers
+        const tripszeropassengersPct = tripswpassengers > 0
+            ? parseFloat(((tripszeropassengers / tripswpassengers) * 100).toFixed(1))
+            : 0;
+        mergedResults.push({
+            agencyId,
+            date: formattedDate,
+            tripswpassengers,
+            tripszeropassengers,
+            tripszeropassengersPct, // include the percentage
+        });
+    }
+    message(`Processed ${mergedResults.length} observed trips metrics`);
+    return mergedResults;
+}

package/dist/tasks/executive-summary-setup/index.js

@@ -0,0 +1,247 @@
+import { log } from 'node:console';
+import fs from 'node:fs';
+// import { calculateAverageRidesByAgencyByDayType } from './avg-trips-day.js';
+import { calculateObservedTrips } from './empty-runs.js';
+import { calculateSupplyMetrics } from './km.js';
+import { calculateMedianSpeed } from './median-speed.js';
+import { calculateOnBoardSales } from './on-board-sales.js';
+import { calculateAffectedPassengers } from './passenger-impact.js';
+import { calculateDemandFromMetrics } from './passengers-transported.js';
+import { calculatePassengersPerKm } from './paxperkm.js';
+import { calculateCompletedTrips, calculatePlannedTrips } from './trips.js';
+import { calculateDailyServiceCompliance } from './tripstatus.js';
+// Helper
+function normalizeDate(date) {
+    const isoMatch = date.match(/^(\d{4})-(\d{2})-(\d{2})$/);
+    if (isoMatch)
+        return `${isoMatch[3]}/${isoMatch[2]}/${isoMatch[1]}`;
+    const dmyMatch = date.match(/^(\d{2})\/(\d{2})\/(\d{4})$/);
+    if (dmyMatch)
+        return date;
+    const compactMatch = date.match(/^(\d{4})(\d{2})(\d{2})$/);
+    if (compactMatch)
+        return `${compactMatch[3]}/${compactMatch[2]}/${compactMatch[1]}`;
+    throw new Error(`Unknown date format: ${date}`);
+}
+// Export
+export async function exportExecutiveSummary({ context, message }) {
+    message('Starting export of Executive Summary JSON...');
+    // Fetch metrics
+    const medianSpeedResults = await calculateMedianSpeed({ context, message });
+    const demandMetrics = await calculateDemandFromMetrics({ context, message });
+    const plannedTripsMetrics = await calculatePlannedTrips({ context, message });
+    const completedTripsMetrics = await calculateCompletedTrips({ context, message });
+    const observedTripsMetrics = await calculateObservedTrips({ context, message });
+    const circulationMetrics = await calculateSupplyMetrics({ context, message });
+    const affectedPassengersMetrics = await calculateAffectedPassengers({ context, message });
+    const passengersPerKmMetrics = await calculatePassengersPerKm({ context, message });
+    const onBoardSalesMetrics = await calculateOnBoardSales({ context, message });
+    log(`✓ Median Speeds: ${medianSpeedResults.length}`);
+    log(`✓ Demand: ${demandMetrics.length}`);
+    log(`✓ Planned: ${plannedTripsMetrics.length}`);
+    log(`✓ Completed: ${completedTripsMetrics.length}`);
+    log(`✓ Observed trips: ${observedTripsMetrics.length}`);
+    log(`✓ Circulations: ${circulationMetrics.length}`);
+    log(`✓ Affected passengers: ${affectedPassengersMetrics.length}`);
+    log(`✓ Passengers per Km: ${passengersPerKmMetrics.length}`);
+    log(`✓ On-board sales: ${onBoardSalesMetrics.length}`);
+    // Merge all metrics by date + agency
+    const mergedResults = new Map();
+    function ensureRow(date, agencyId) {
+        const key = `${date ?? 'NA'}-${agencyId}`;
+        if (!mergedResults.has(key)) {
+            mergedResults.set(key, {
+                date,
+                agencyId,
+                totalpassengers: 0,
+                byCategory: {},
+                byProduct: {},
+                pax_affected_by_failures: 0,
+                pax_affected_by_delay: 0,
+            });
+        }
+        return mergedResults.get(key);
+    }
+    // Demand
+    for (const row of demandMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.totalpassengers = row.totalpassengers;
+        r.byCategory = {
+            on_board_sale: row.byCategory?.on_board_sale ?? 0,
+            subscription: row.byCategory?.subscription ?? 0,
+            prepaid: row.byCategory?.prepaid ?? 0,
+        };
+        r.byProduct = { ...row.byProduct };
+    }
+    // Planned
+    for (const row of plannedTripsMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.plannedTrips = row.plannedTrips;
+    }
+    // Completed
+    for (const row of completedTripsMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.completedTrips = row.completedTrips;
+    }
+    // Observed Trips
+    for (const row of observedTripsMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.tripsZeroPassengers = row.tripszeropassengers;
+        r.tripsWithPassengers = row.tripswpassengers;
+    }
+    // Circulations (KM)
+    for (const row of circulationMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.vkmsObserved = (r.vkmsObserved ?? 0) + (row.vkmsobserved ?? 0);
+        r.vkmsScheduled = (r.vkmsScheduled ?? 0) + (row.vkmsscheduled ?? 0);
+    }
+    // Median Speed
+    for (const row of medianSpeedResults) {
+        const r = ensureRow(undefined, row.agencyId);
+        r.medianSpeed = row.medianSpeed ?? 0;
+    }
+    // Affected passengers
+    for (const row of affectedPassengersMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.pax_affected_by_failures += row.estimatedpax_affected_by_failures ?? 0;
+    }
+    // Passengers per Km
+    for (const row of passengersPerKmMetrics) {
+        const r = ensureRow(undefined, row.agencyId);
+        r.passengersPerKm = row.passengersPerKm;
+    }
+    // On-board Sales
+    for (const row of onBoardSalesMetrics) {
+        const r = ensureRow(row.date, row.agencyId);
+        r.onBoardSalesPr = (r.onBoardSalesPr ?? 0) + row['onboard-sales-pr'];
+    }
+    // Helper for median calculation
+    function calculateMedian(values) {
+        if (!values.length)
+            return 0;
+        const sorted = [...values].sort((a, b) => a - b);
+        const middle = Math.floor(sorted.length / 2);
+        return sorted.length % 2 === 0
+            ? parseFloat(((sorted[middle - 1] + sorted[middle]) / 2).toFixed(2))
+            : parseFloat(sorted[middle].toFixed(2));
+    }
+    // Aggregate by agency
+    const totalsByAgency = {};
+    for (const row of mergedResults.values()) {
+        const agencyId = row.agencyId;
+        if (!totalsByAgency[agencyId]) {
+            totalsByAgency[agencyId] = {
+                agencyId,
+                totalPassengers: { value: 0 },
+                trips: {
+                    planned: 0,
+                    completed: 0,
+                    completedPct: 0,
+                    withPassengers: 0,
+                    zeroPassengers: { count: 0, percentage: 0 },
+                },
+                category: { on_board_sale: 0, subscription: 0, prepaid: 0 },
+                km: { observed: 0, scheduled: 0, observedPct: 0 },
+                product_id: {
+                    'id-prod-navegante-metro': 0,
+                    'id-prod-navegante-metro-sub23-grat': 0,
+                    'id-prod-navegante-65': 0,
+                    'others': 0,
+                },
+                dailyServiceCompliance: { earlyRides: 0, fiveMinDelays: 0, onTimeRides: 0, earlyRidesPct: 0, fiveMinDelaysPct: 0, onTimeRidesPct: 0 },
+                medianSpeed: 0,
+                passengersPerKm: 0,
+                onBoardSalesPr: 0,
+                pax_affected_by_failures: 0,
+                pax_affected_by_delay: 0,
+                __medianSpeeds: [],
+            };
+        }
+        const t = totalsByAgency[agencyId];
+        t.totalPassengers.value += row.totalpassengers ?? 0;
+        t.pax_affected_by_failures += row.pax_affected_by_failures ?? 0;
+        t.pax_affected_by_delay += row.pax_affected_by_delay ?? 0;
+        t.trips.planned += row.plannedTrips ?? 0;
+        t.trips.completed += row.completedTrips ?? 0;
+        t.trips.withPassengers += row.tripsWithPassengers ?? 0;
+        t.trips.zeroPassengers.count += row.tripsZeroPassengers ?? 0;
+        t.km.observed += row.vkmsObserved ?? 0;
+        t.km.scheduled += row.vkmsScheduled ?? 0;
+        if (row.medianSpeed !== undefined && row.medianSpeed !== null) {
+            t.__medianSpeeds.push(row.medianSpeed);
+        }
+        t.category.on_board_sale += row.byCategory?.on_board_sale ?? 0;
+        t.category.subscription += row.byCategory?.subscription ?? 0;
+        t.category.prepaid += row.byCategory?.prepaid ?? 0;
+        t.onBoardSalesPr += row.onBoardSalesPr ?? 0;
+        const byProduct = { ...row.byProduct };
+        const metro = byProduct['id-prod-navegante-metro'] ?? 0;
+        const sub23 = byProduct['id-prod-navegante-metro-sub23-grat'] ?? 0;
+        const p65 = byProduct['id-prod-navegante-65'] ?? 0;
+        const totalProducts = Object.values(byProduct).reduce((a, b) => a + b, 0);
+        const others = totalProducts - (metro + sub23 + p65);
+        t.product_id['id-prod-navegante-metro'] += metro;
+        t.product_id['id-prod-navegante-metro-sub23-grat'] += sub23;
+        t.product_id['id-prod-navegante-65'] += p65;
+        t.product_id.others += others;
+        t.passengersPerKm += row.passengersPerKm ?? 0;
+    }
+    // Calculate percentages
+    for (const agency of Object.values(totalsByAgency)) {
+        agency.medianSpeed = calculateMedian(agency.__medianSpeeds);
+        delete agency.__medianSpeeds;
+        if (agency.trips.planned > 0)
+            agency.trips.completedPct = parseFloat(((agency.trips.completed / agency.trips.planned) * 100).toFixed(1));
+        if (agency.trips.withPassengers > 0)
+            agency.trips.zeroPassengers.percentage = parseFloat(((agency.trips.zeroPassengers.count / agency.trips.withPassengers) * 100).toFixed(1));
+        if (agency.km.scheduled > 0)
+            agency.km.observedPct = parseFloat(((agency.km.observed / agency.km.scheduled) * 100).toFixed(1));
+    }
+    // Daily service compliance
+    const dailyResults = await calculateDailyServiceCompliance(context);
+    for (const day of Object.keys(dailyResults)) {
+        const dayData = dailyResults[day];
+        for (const agencyId of Object.keys(dayData.agencies)) {
+            if (totalsByAgency[agencyId]) {
+                const dailyMetrics = dayData.agencies[agencyId];
+                const agencyTotals = totalsByAgency[agencyId];
+                agencyTotals.dailyServiceCompliance.earlyRides += dailyMetrics.early_rides;
+                agencyTotals.dailyServiceCompliance.fiveMinDelays += dailyMetrics.five_min_delays;
+                agencyTotals.dailyServiceCompliance.onTimeRides += dailyMetrics.ontime_rides;
+                // Add passengers affected by delays ≥5 min
+                agencyTotals.pax_affected_by_delay = (agencyTotals.pax_affected_by_delay ?? 0) + (dailyMetrics['pax-affected-by-delay'] ?? 0);
+                const total = agencyTotals.dailyServiceCompliance.earlyRides + agencyTotals.dailyServiceCompliance.fiveMinDelays + agencyTotals.dailyServiceCompliance.onTimeRides;
+                if (total > 0) {
+                    agencyTotals.dailyServiceCompliance.earlyRidesPct = parseFloat(((agencyTotals.dailyServiceCompliance.earlyRides / total) * 100).toFixed(1));
+                    agencyTotals.dailyServiceCompliance.fiveMinDelaysPct = parseFloat(((agencyTotals.dailyServiceCompliance.fiveMinDelays / total) * 100).toFixed(1));
+                    agencyTotals.dailyServiceCompliance.onTimeRidesPct = parseFloat(((agencyTotals.dailyServiceCompliance.onTimeRides / total) * 100).toFixed(1));
+                }
+                else {
+                    agencyTotals.dailyServiceCompliance.earlyRidesPct = 0;
+                    agencyTotals.dailyServiceCompliance.fiveMinDelaysPct = 0;
+                    agencyTotals.dailyServiceCompliance.onTimeRidesPct = 0;
+                }
+            }
+        }
+    }
+    // Add avg_trips_day_type
+    // const avgRidesByDayType = await calculateAverageRidesByAgencyByDayType({ context, message });
+    // for (const row of avgRidesByDayType) {
+    // 	const agencyTotals = totalsByAgency[row.agencyId];
+    // 	if (!agencyTotals) continue;
+    // 	const dayTypeKey = `avg_trips_day_type ${row.dayType}` as const;
+    // 	agencyTotals[dayTypeKey] = row.averageRides;
+    // }
+    // Build final output
+    const finalOutput = {
+        timestamp: Date.now(),
+        startDayAnalysis: normalizeDate(context.dates.start),
+        endDayAnalysis: normalizeDate(context.dates.end),
+        totalsByAgency: Object.values(totalsByAgency),
+    };
+    if (!fs.existsSync(context.output))
+        fs.mkdirSync(context.output, { recursive: true });
+    const outputPath = `${context.output}/executive-summary-${context.dates.start}-${context.dates.end}.json`;
+    fs.writeFileSync(outputPath, JSON.stringify(finalOutput, null, 2), 'utf-8');
+    message('✓ Executive Summary JSON export completed');
+}

package/dist/tasks/executive-summary-setup/km.js

@@ -0,0 +1,50 @@
+import { yyyymmddToDashed } from '../../utils/dates-helper.js';
+import { metrics } from '@tmlmobilidade/interfaces';
+/* * */
+export async function calculateSupplyMetrics({ context, message }) {
+    message('Calculating supply metrics...');
+    const metricsCollection = await metrics.getCollection();
+    // Fetch supply documents
+    message('Fetching supply metrics...');
+    const docs = await metricsCollection.find({
+        metric: 'supply_by_agency_by_day',
+    }).toArray();
+    message(`Found ${docs.length} supply metrics`);
+    const results = new Map();
+    const startDate = yyyymmddToDashed(context.dates.start);
+    const endDate = yyyymmddToDashed(context.dates.end);
+    // Process each document
+    for (const doc of docs) {
+        const agencyId = doc.properties.agency_id;
+        for (const [date, dayData] of Object.entries(doc.data)) {
+            // Direct YYYY-MM-DD comparison
+            if (date < startDate || date > endDate)
+                continue;
+            const key = `${date}-${agencyId}`;
+            if (!results.has(key)) {
+                results.set(key, {
+                    agencyId,
+                    date,
+                    vkmsobserved: 0,
+                    vkmsobservedpct: 0,
+                    vkmsscheduled: 0,
+                });
+            }
+            const entry = results.get(key);
+            entry.vkmsobserved += dayData.vkms_observed;
+            entry.vkmsscheduled += dayData.vkms_scheduled;
+        }
+    }
+    // Calculate percentage at the end (after aggregation)
+    const finalResults = Array.from(results.values()).map((entry) => {
+        const pct = entry.vkmsscheduled > 0
+            ? Number(((entry.vkmsobserved / entry.vkmsscheduled) * 100).toFixed(2))
+            : 0;
+        return {
+            ...entry,
+            vkmsobservedpct: pct,
+        };
+    });
+    message(`Processed ${finalResults.length} supply records`);
+    return finalResults;
+}

package/dist/tasks/executive-summary-setup/median-speed.js

@@ -0,0 +1,80 @@
+import { Dates } from '@tmlmobilidade/dates';
+import { rides } from '@tmlmobilidade/interfaces';
+/**
+ * Helper to calculate median from an array of numbers
+ */
+function median(values) {
+    if (values.length === 0)
+        return 0;
+    values.sort((a, b) => a - b);
+    const mid = Math.floor(values.length / 2);
+    if (values.length % 2 === 0) {
+        return (values[mid - 1] + values[mid]) / 2;
+    }
+    else {
+        return values[mid];
+    }
+}
+/**
+ * Calculates median speed per agency (all dates combined)
+ * Considers only rides with positive duration and distance
+ */
+export async function calculateMedianSpeed({ context, message }) {
+    message('Calculating median speeds per agency...');
+    const ridesCollection = await rides.getCollection();
+    const startDateStr = Dates.fromOperationalDate(context.dates.start, 'Europe/Lisbon').unix_timestamp;
+    const endDateStr = Dates.fromOperationalDate(context.dates.end, 'Europe/Lisbon').unix_timestamp;
+    const pipeline = [
+        {
+            $match: {
+                $expr: { $gt: ['$end_time_observed', '$start_time_observed'] },
+                agency_id: { $exists: true },
+                end_time_observed: { $exists: true },
+                extension_scheduled: { $gt: 0 },
+                start_time_observed: { $exists: true },
+                start_time_scheduled: { $gte: startDateStr, $lte: endDateStr },
+            },
+        },
+        {
+            $project: {
+                agencyId: '$agency_id',
+                distanceKilometers: { $divide: ['$extension_scheduled', 1000] },
+                durationHours: {
+                    $divide: [
+                        { $subtract: ['$end_time_observed', '$start_time_observed'] },
+                        60 * 60 * 1000,
+                    ],
+                },
+            },
+        },
+        {
+            $project: {
+                agencyId: 1,
+                speedKmPerHour: {
+                    $cond: [
+                        { $gt: ['$durationHours', 0] },
+                        { $divide: ['$distanceKilometers', '$durationHours'] },
+                        0,
+                    ],
+                },
+            },
+        },
+        {
+            $group: {
+                _id: '$agencyId',
+                speeds: { $push: '$speedKmPerHour' },
+            },
+        },
+    ];
+    const aggCursor = ridesCollection.aggregate(pipeline);
+    const results = [];
+    for await (const doc of aggCursor) {
+        const medianSpeedValue = median(doc.speeds);
+        results.push({
+            agencyId: doc._id,
+            medianSpeed: parseFloat(medianSpeedValue.toFixed(2)),
+        });
+    }
+    message(`Processed ${results.length} agencies`);
+    return results;
+}