@nightkatana/kronosys-app 1.0.0-beta.0

package/lib/reportingDatePresets.ts

@@ -0,0 +1,41 @@
+/** Date du calendrier local au format `YYYY-MM-DD` pour `<input type="date">`. */
+export function toDateInputValue(d: Date): string {
+  const y = d.getFullYear();
+  const m = String(d.getMonth() + 1).padStart(2, "0");
+  const day = String(d.getDate()).padStart(2, "0");
+  return `${y}-${m}-${day}`;
+}
+
+/** Jour calendaire : début = fin = ce jour (référence : maintenant). */
+export function reportingPresetDay(ref: Date = new Date()): { from: string; to: string } {
+  const d = toDateInputValue(ref);
+  return { from: d, to: d };
+}
+
+/**
+ * Semaine du lundi au dimanche contenant `ref` (habitude ISO / Europe).
+ */
+export function reportingPresetWeek(ref: Date = new Date()): { from: string; to: string } {
+  const x = new Date(ref.getFullYear(), ref.getMonth(), ref.getDate());
+  const dow = x.getDay();
+  const mondayOffset = dow === 0 ? -6 : 1 - dow;
+  x.setDate(x.getDate() + mondayOffset);
+  const start = new Date(x.getFullYear(), x.getMonth(), x.getDate());
+  const end = new Date(start);
+  end.setDate(end.getDate() + 6);
+  return { from: toDateInputValue(start), to: toDateInputValue(end) };
+}
+
+/** Mois calendaire contenant `ref`. */
+export function reportingPresetMonth(ref: Date = new Date()): { from: string; to: string } {
+  const start = new Date(ref.getFullYear(), ref.getMonth(), 1);
+  const end = new Date(ref.getFullYear(), ref.getMonth() + 1, 0);
+  return { from: toDateInputValue(start), to: toDateInputValue(end) };
+}
+
+/** Année civile contenant `ref`. */
+export function reportingPresetYear(ref: Date = new Date()): { from: string; to: string } {
+  const start = new Date(ref.getFullYear(), 0, 1);
+  const end = new Date(ref.getFullYear(), 11, 31);
+  return { from: toDateInputValue(start), to: toDateInputValue(end) };
+}

package/lib/reportingMetricHelp.ts

@@ -0,0 +1,430 @@
+/** Textes d’aide (?) pour les métriques de la page Rapports — FR / EN. */
+export type ReportingMetricHelpBlock = {
+  metricHelpSessionsAria: string;
+  metricHelpSessionsBody: string;
+  metricHelpTaskRowsAria: string;
+  metricHelpTaskRowsBody: string;
+  metricHelpKronoFocusCompletedAria: string;
+  metricHelpKronoFocusCompletedBody: string;
+  metricHelpKronoFocusTasksUsedAria: string;
+  metricHelpKronoFocusTasksUsedBody: string;
+  metricHelpKronoFocusCyclesAria: string;
+  metricHelpKronoFocusCyclesBody: string;
+  metricHelpTaskTimeAria: string;
+  metricHelpTaskTimeBody: string;
+  metricHelpSessionCodingAria: string;
+  metricHelpSessionCodingBody: string;
+  metricHelpSessionActiveAria: string;
+  metricHelpSessionActiveBody: string;
+  metricHelpLinesTotalAria: string;
+  metricHelpLinesTotalBody: string;
+  metricHelpLinesHumanAria: string;
+  metricHelpLinesHumanBody: string;
+  metricHelpLinesAiAria: string;
+  metricHelpLinesAiBody: string;
+  metricHelpLocByLangTitleAria: string;
+  metricHelpLocByLangTitleBody: string;
+  metricHelpCodingSignalsTitleAria: string;
+  metricHelpCodingSignalsTitleBody: string;
+  metricHelpChartSessionsAria: string;
+  metricHelpChartSessionsBody: string;
+  metricHelpChartTasksAria: string;
+  metricHelpChartTasksBody: string;
+  metricHelpChartTaskTimeAria: string;
+  metricHelpChartTaskTimeBody: string;
+  metricHelpChartSessionWallAria: string;
+  metricHelpChartSessionWallBody: string;
+  metricHelpTblDayAria: string;
+  metricHelpTblDayBody: string;
+  metricHelpTblSessionsAria: string;
+  metricHelpTblSessionsBody: string;
+  metricHelpTblDoneAria: string;
+  metricHelpTblDoneBody: string;
+  metricHelpTblActiveAria: string;
+  metricHelpTblActiveBody: string;
+  metricHelpTblTaskTimeAria: string;
+  metricHelpTblTaskTimeBody: string;
+  metricHelpTblSessionCodingAria: string;
+  metricHelpTblSessionCodingBody: string;
+  metricHelpTblSessionWallAria: string;
+  metricHelpTblSessionWallBody: string;
+  metricHelpSessionWallSummaryAria: string;
+  metricHelpSessionWallSummaryBody: string;
+  metricHelpTagTimeSectionAria: string;
+  metricHelpTagTimeSectionBody: string;
+  metricHelpTagTimeDayTableAria: string;
+  metricHelpTagTimeDayTableBody: string;
+  metricHelpTagTimeWeekTableAria: string;
+  metricHelpTagTimeWeekTableBody: string;
+  metricHelpTagWeekCalendarAria: string;
+  metricHelpTagWeekCalendarBody: string;
+  metricHelpTagWeekStartsOnAria: string;
+  metricHelpTagWeekStartsOnBody: string;
+  metricHelpWeekNavAria: string;
+  metricHelpWeekNavBody: string;
+  metricHelpTagTimeColTagAria: string;
+  metricHelpTagTimeColTagBody: string;
+  metricHelpTagTimeColDayAria: string;
+  metricHelpTagTimeColDayBody: string;
+  metricHelpTagTimeColWeekAria: string;
+  metricHelpTagTimeColWeekBody: string;
+  metricHelpTagTimeColMinutesAria: string;
+  metricHelpTagTimeColMinutesBody: string;
+  metricHelpProjectTitleAria: string;
+  metricHelpProjectTitleBody: string;
+  metricHelpProjectCalendarAria: string;
+  metricHelpProjectCalendarBody: string;
+  metricHelpProjectColProjAria: string;
+  metricHelpProjectColProjBody: string;
+  metricHelpProjectColTasksAria: string;
+  metricHelpProjectColTasksBody: string;
+  metricHelpProjectColTimeAria: string;
+  metricHelpProjectColTimeBody: string;
+  metricHelpWorkspaceTitleAria: string;
+  metricHelpWorkspaceTitleBody: string;
+  metricHelpWsTotalLinesAria: string;
+  metricHelpWsTotalLinesBody: string;
+  metricHelpWsFileCountAria: string;
+  metricHelpWsFileCountBody: string;
+  metricHelpWsColLangAria: string;
+  metricHelpWsColLangBody: string;
+  metricHelpWsColLinesAria: string;
+  metricHelpWsColLinesBody: string;
+  metricHelpWsColPercentAria: string;
+  metricHelpWsColPercentBody: string;
+  metricHelpAggLocColLangAria: string;
+  metricHelpAggLocColLangBody: string;
+  metricHelpAggLocColLinesAria: string;
+  metricHelpAggLocColLinesBody: string;
+  metricHelpAggSigColLangAria: string;
+  metricHelpAggSigColLangBody: string;
+  metricHelpAggSigColCountAria: string;
+  metricHelpAggSigColCountBody: string;
+  metricHelpLegendDoneAria: string;
+  metricHelpLegendDoneBody: string;
+  metricHelpLegendActiveAria: string;
+  metricHelpLegendActiveBody: string;
+  metricHelpLegendSessionsAria: string;
+  metricHelpLegendSessionsBody: string;
+  metricHelpAssiduityRefAria: string;
+  metricHelpAssiduityRefBody: string;
+  metricHelpAssiduityLateCountAria: string;
+  metricHelpAssiduityLateCountBody: string;
+  metricHelpAssiduityLateTotalAria: string;
+  metricHelpAssiduityLateTotalBody: string;
+  metricHelpAssiduityAvgLateAria: string;
+  metricHelpAssiduityAvgLateBody: string;
+};
+
+export const reportingMetricHelpEn: ReportingMetricHelpBlock = {
+  metricHelpSessionsAria: "Help: sessions in range",
+  metricHelpSessionsBody:
+    "Count of sessions whose calendar day (savedAt, or endAt, or startAt) falls inside the selected range. If you use tag filters, a session is included only when at least one of its tasks matches the tags.",
+  metricHelpTaskRowsAria: "Help: task rows in range",
+  metricHelpTaskRowsBody:
+    "Number of task records counted toward aggregates: task day (end or start) must fall in the range, and the task must pass the tag filter. Archived-session rules apply (unfinished tasks may be excluded).",
+  metricHelpKronoFocusCompletedAria: "Help: KronoFocus sessions completed",
+  metricHelpKronoFocusCompletedBody:
+    "Sum of the session-level “sessions completed” counter stored on each session snapshot, for sessions whose day is in the range. This is not per-task; it reflects the KronoFocus state saved with the session.",
+  metricHelpKronoFocusTasksUsedAria: "Help: tasks with KronoFocus used",
+  metricHelpKronoFocusTasksUsedBody:
+    "How many tasks in the range have usedKronoFocus set, after tag and archived-session filters.",
+  metricHelpKronoFocusCyclesAria: "Help: KronoFocus cycles (tasks)",
+  metricHelpKronoFocusCyclesBody:
+    "Sum of kronoFocusCycles over tasks included in the range (same filters as other task metrics).",
+  metricHelpTaskTimeAria: "Help: recorded task time",
+  metricHelpTaskTimeBody:
+    "Total recorded task duration (from durationMs) for included tasks, shown as hours/minutes. Task day and tag filters apply.",
+  metricHelpSessionCodingAria: "Help: session coding time",
+  metricHelpSessionCodingBody:
+    "Sum of coding minutes saved on each session (codingMinutesSession) for sessions whose day is in the range. Independent of task timers.",
+  metricHelpSessionActiveAria: "Help: session active time",
+  metricHelpSessionActiveBody:
+    "Sum of active minutes saved on each session (activeMinutes) for sessions in the range. Based on IDE activity signals, not task time.",
+  metricHelpLinesTotalAria: "Help: lines written (sessions in range)",
+  metricHelpLinesTotalBody:
+    "Sum of linesWrittenTotal from each session snapshot included in the range (net lines from tracked edits, same definition as the dashboard).",
+  metricHelpLinesHumanAria: "Help: lines — human (estimated)",
+  metricHelpLinesHumanBody:
+    "Sum of human-estimated lines (linesWrittenHuman) per session in the range. Split uses a heuristic on each edit, not exact attribution.",
+  metricHelpLinesAiAria: "Help: lines — AI (estimated)",
+  metricHelpLinesAiBody:
+    "Sum of AI-estimated lines (linesWrittenAi) per session in the range. Large or multi-range edits are more likely classified as AI-style.",
+  metricHelpLocByLangTitleAria: "Help: lines by language (aggregated)",
+  metricHelpLocByLangTitleBody:
+    "Merges each session’s locByLanguage tuples for sessions in the range: total net lines attributed to each language id.",
+  metricHelpCodingSignalsTitleAria: "Help: coding signals by language (aggregated)",
+  metricHelpCodingSignalsTitleBody:
+    "Merges codingSignalsByLanguage from included sessions: counts of coding-context events (open, save, edit, active editor, etc.) per language.",
+  metricHelpChartSessionsAria: "Help: sessions per day",
+  metricHelpChartSessionsBody:
+    "For each calendar day in the chart, how many sessions had their session day in that bucket. Range and tag rules match the summary cards.",
+  metricHelpChartTasksAria: "Help: tasks per day by status",
+  metricHelpChartTasksBody:
+    "Per day: green = tasks marked done in the range; amber = tasks still in progress. Task day and filters apply; archived sessions use stricter completion rules.",
+  metricHelpChartTaskTimeAria: "Help: recorded task time per day",
+  metricHelpChartTaskTimeBody:
+    "For each day, sum of recorded task durations (durationMs → minutes) for tasks whose task day falls in that bucket. Same tag and archived-session rules as task counts. Bar height scales to the largest day in view.",
+  metricHelpChartSessionWallAria: "Help: session wall-clock time per day",
+  metricHelpChartSessionWallBody:
+    "Per calendar day, sum of session wall-clock minutes: saved sessionDurationMinutes when present, otherwise time span from startAt to endAt. Bucketed by session day (same as the session count). Not the same as coding time (pauses when idle).",
+  metricHelpTblDayAria: "Help: table column — day",
+  metricHelpTblDayBody: "Calendar day key (local date) or “undated” when no date could be derived.",
+  metricHelpTblSessionsAria: "Help: table column — sessions",
+  metricHelpTblSessionsBody: "Number of sessions attributed to that day (same rules as the sessions chart).",
+  metricHelpTblDoneAria: "Help: table column — done",
+  metricHelpTblDoneBody: "Count of completed tasks attributed to that day.",
+  metricHelpTblActiveAria: "Help: table column — active",
+  metricHelpTblActiveBody: "Count of in-progress tasks attributed to that day.",
+  metricHelpTblTaskTimeAria: "Help: table column — recorded task time",
+  metricHelpTblTaskTimeBody:
+    "Sum of durationMs (as minutes) for tasks attributed to that calendar day — the same basis as “Recorded task time” in the summary and as Jira-style worklog totals per day.",
+  metricHelpTblSessionCodingAria: "Help: table column — session coding time",
+  metricHelpTblSessionCodingBody:
+    "Sum of codingMinutesSession for sessions whose session day is that row. Uses session day (not task day), matching the session count column.",
+  metricHelpTblSessionWallAria: "Help: table column — session wall-clock",
+  metricHelpTblSessionWallBody:
+    "Total wall-clock minutes for sessions on that session day: persisted session duration or startAt→endAt. Compare with “Session coding” (active coding only).",
+  metricHelpSessionWallSummaryAria: "Help: session wall-clock (summary)",
+  metricHelpSessionWallSummaryBody:
+    "Sum of wall-clock minutes for every session included in the range (session day and tag rules). Independent of task timers; complements coding/active minutes.",
+  metricHelpTagTimeSectionAria: "Help: time by tag (SAP / WBS style)",
+  metricHelpTagTimeSectionBody:
+    "Recorded task time (durationMs) attributed to each task’s #tags. The full duration is counted for every tag on the task (summing tag rows can exceed the KPI total when tasks carry multiple tags). Tasks without explicit tags roll into the default bucket (shown as “default” in English). Same date, tag filter, and archived-session rules as other task metrics.",
+  metricHelpTagTimeDayTableAria: "Help: tag time by day table",
+  metricHelpTagTimeDayTableBody:
+    "One row per tag and task calendar day with the summed minutes for that bucket. Rows are grouped by calendar day; several `project#code` tags for the same project on the same day appear under one @project summary row—expand to see each tag line.",
+  metricHelpTagTimeWeekTableAria: "Help: weekly tag calendar",
+  metricHelpTagTimeWeekTableBody:
+    "Seven day cells plus a week total: recorded task minutes per calendar day within each row’s week, in column order from the chosen week start (Monday, Sunday, or Saturday). The date quick filter “Week” still uses Monday–Sunday; only this grid follows your week-start preference.",
+  metricHelpTagWeekCalendarAria: "Help: weekly calendar columns",
+  metricHelpTagWeekCalendarBody:
+    "For each calendar week, the period is shown once above a single table: one row per tag, columns are the seven local days (from your week-start setting) plus a week total. Each column header shows the weekday and the real calendar date; hover a header or a day cell for the exact date (YYYY-MM-DD). When several tags use the same `project#code` pattern for one project, they are grouped under one @project summary row; use the chevron to expand and see each tag’s row and minutes.",
+  metricHelpTagWeekStartsOnAria: "Help: week start preference",
+  metricHelpTagWeekStartsOnBody:
+    "Chooses which weekday begins the 7-day strip: Monday (ISO-style), Sunday (US-style), or Saturday. Saved in this browser only (localStorage).",
+  metricHelpWeekNavAria: "Help: week navigation",
+  metricHelpWeekNavBody:
+    "Previous / next move one week at a time through weeks that have session wall-clock time or at least one session in the filtered range. If none qualify, weeks come from recorded task time by tag or by @project. All bar charts, the day-by-day table, and both weekly calendars (tags and projects) show only the selected week (seven local days from your week-start setting).",
+  metricHelpTagTimeColTagAria: "Help: tag column",
+  metricHelpTagTimeColTagBody: "Kronosys #tag; use as a label for your external posting key (e.g. WBS).",
+  metricHelpTagTimeColDayAria: "Help: day column",
+  metricHelpTagTimeColDayBody: "Task day (end or start timestamp), YYYY-MM-DD.",
+  metricHelpTagTimeColWeekAria: "Help: week period line",
+  metricHelpTagTimeColWeekBody:
+    "This line names the calendar week once for the table below (local dates). The week boundary matches your “week starts on” setting.",
+  metricHelpTagTimeColMinutesAria: "Help: minutes column",
+  metricHelpTagTimeColMinutesBody:
+    "Sum of attributed task minutes for that tag and period. Minutes are not split across tags: a multi-tag task contributes its full duration to each tag row.",
+  metricHelpProjectTitleAria: "Help: recorded time by project",
+  metricHelpProjectTitleBody:
+    "Recorded task duration (durationMs) split by each task’s @project, shown as a weekly calendar: one period line per week, then one table with a row per project and seven day columns plus a week total. Same date range, tag filter, archived-session rules, and week navigation as the tag calendar.",
+  metricHelpProjectCalendarAria: "Help: project weekly calendar",
+  metricHelpProjectCalendarBody:
+    "Same layout as the tag calendar: for each week, the date span appears once; each row is one @project. Column headers show weekday and calendar date; day cells use task day (end or start); hover a header or cell for YYYY-MM-DD.",
+  metricHelpProjectColProjAria: "Help: project column",
+  metricHelpProjectColProjBody: "Project name from the task, or “no project” when none is set.",
+  metricHelpProjectColTasksAria: "Help: tasks column",
+  metricHelpProjectColTasksBody: "Number of task rows summed into that project row.",
+  metricHelpProjectColTimeAria: "Help: recorded time column",
+  metricHelpProjectColTimeBody:
+    "Total recorded task minutes for that @project over the seven days of the row (from durationMs).",
+  metricHelpWorkspaceTitleAria: "Help: open folder snapshot",
+  metricHelpWorkspaceTitleBody:
+    "Snapshot of the first workspace folder: line counts by language from Git-tracked files or a folder walk. Not tied to Kronosys sessions; cached ~5 minutes. See the paragraph below for details.",
+  metricHelpWsTotalLinesAria: "Help: total lines (approx.)",
+  metricHelpWsTotalLinesBody:
+    "Approximate total lines read from source files (known extensions), summed for the snapshot.",
+  metricHelpWsFileCountAria: "Help: files scanned",
+  metricHelpWsFileCountBody: "Number of files that contributed to the snapshot (after size and type filters).",
+  metricHelpWsColLangAria: "Help: language column",
+  metricHelpWsColLangBody: "Language id (TextMate-style) inferred from the file extension.",
+  metricHelpWsColLinesAria: "Help: lines column",
+  metricHelpWsColLinesBody: "Line count for that language in the scanned files.",
+  metricHelpWsColPercentAria: "Help: share column",
+  metricHelpWsColPercentBody: "Percentage of total lines in the snapshot for that language (may not add to exactly 100% after rounding).",
+  metricHelpAggLocColLangAria: "Help: language (aggregated lines)",
+  metricHelpAggLocColLangBody: "Language id (TextMate-style); values are summed across sessions in the range.",
+  metricHelpAggLocColLinesAria: "Help: lines (aggregated)",
+  metricHelpAggLocColLinesBody: "Total net lines written in that language for included sessions.",
+  metricHelpAggSigColLangAria: "Help: language (signals)",
+  metricHelpAggSigColLangBody: "Language id for aggregated coding-signal counts.",
+  metricHelpAggSigColCountAria: "Help: signals count",
+  metricHelpAggSigColCountBody: "Total coding-context signals for that language across included sessions.",
+  metricHelpLegendDoneAria: "Help: legend — done tasks",
+  metricHelpLegendDoneBody: "Green segment: tasks with isDone in that day’s bucket (same filters as the chart).",
+  metricHelpLegendActiveAria: "Help: legend — in progress",
+  metricHelpLegendActiveBody: "Amber segment: tasks not done in that day’s bucket.",
+  metricHelpLegendSessionsAria: "Help: legend — sessions",
+  metricHelpLegendSessionsBody: "Each bar’s height is the number of sessions whose session day matches that column (same range and tag rules).",
+  metricHelpAssiduityRefAria: "Help: sessions with a scheduled start reference",
+  metricHelpAssiduityRefBody:
+    "Sessions in the range whose host recorded a planned start instant when the session was opened (optional `scheduledStartAt` on `newSession`). The dashboard action alone does not set this: the value comes from the integration that starts sessions from your work schedule. Same session-day and tag rules as the session count above.",
+  metricHelpAssiduityLateCountAria: "Help: late sessions (punctuality)",
+  metricHelpAssiduityLateCountBody:
+    "Of those with a reference time, how many started after the planned instant (strictly positive offset in minutes). Early or on-time starts are not counted here.",
+  metricHelpAssiduityLateTotalAria: "Help: cumulative late time",
+  metricHelpAssiduityLateTotalBody:
+    "Sum of positive per-session delays (minutes) in the range — the total time “behind” the planned start across late sessions. On-time and early starts contribute 0.",
+  metricHelpAssiduityAvgLateAria: "Help: average late when late",
+  metricHelpAssiduityAvgLateBody:
+    "Cumulative late minutes divided by the number of late sessions (unchanged if there are zero late sessions, shown as —). A simple punctuality read when a reference time was stored.",
+};
+
+export const reportingMetricHelpFr: ReportingMetricHelpBlock = {
+  metricHelpSessionsAria: "Aide : sessions dans la plage",
+  metricHelpSessionsBody:
+    "Nombre de sessions dont le jour calendaire (savedAt, ou endAt, ou startAt) tombe dans la plage choisie. Avec un filtre d’étiquettes, une session n’est comptée que si au moins une de ses tâches correspond.",
+  metricHelpTaskRowsAria: "Aide : lignes de tâches dans la plage",
+  metricHelpTaskRowsBody:
+    "Nombre d’enregistrements de tâches pris en compte : le jour de la tâche (fin ou début) doit être dans la plage et la tâche doit passer le filtre d’étiquettes. Les règles des sessions archivées s’appliquent (tâches non terminées parfois exclues).",
+  metricHelpKronoFocusCompletedAria: "Aide : sessions KronoFocus terminées",
+  metricHelpKronoFocusCompletedBody:
+    "Somme du compteur « sessions terminées » au niveau session enregistré sur chaque instantané, pour les sessions dont le jour est dans la plage. Ce n’est pas par tâche ; c’est l’état KronoFocus sauvegardé avec la session.",
+  metricHelpKronoFocusTasksUsedAria: "Aide : tâches avec KronoFocus utilisé",
+  metricHelpKronoFocusTasksUsedBody:
+    "Nombre de tâches dans la plage avec usedKronoFocus, après filtres d’étiquettes et règles d’archivage.",
+  metricHelpKronoFocusCyclesAria: "Aide : cycles KronoFocus (tâches)",
+  metricHelpKronoFocusCyclesBody:
+    "Somme des kronoFocusCycles sur les tâches incluses dans la plage (mêmes filtres que les autres métriques tâche).",
+  metricHelpTaskTimeAria: "Aide : temps enregistré sur les tâches",
+  metricHelpTaskTimeBody:
+    "Durée totale enregistrée (durationMs) des tâches incluses, affichée en heures/minutes. Filtres de jour et d’étiquettes appliqués.",
+  metricHelpSessionCodingAria: "Aide : temps de codage (sessions)",
+  metricHelpSessionCodingBody:
+    "Somme des minutes de codage sauvegardées par session (codingMinutesSession) pour les sessions dont le jour est dans la plage. Indépendant des minuteurs de tâche.",
+  metricHelpSessionActiveAria: "Aide : temps actif (sessions)",
+  metricHelpSessionActiveBody:
+    "Somme des minutes actives sauvegardées par session (activeMinutes) pour les sessions dans la plage. Basé sur les signaux d’activité de l’IDE, pas sur le temps tâche.",
+  metricHelpLinesTotalAria: "Aide : lignes écrites (sessions dans la plage)",
+  metricHelpLinesTotalBody:
+    "Somme des linesWrittenTotal de chaque session incluse dans la plage (lignes nettes des modifications suivies, même définition que le tableau de bord).",
+  metricHelpLinesHumanAria: "Aide : lignes — humain (estim.)",
+  metricHelpLinesHumanBody:
+    "Somme des lignes estimées « humain » (linesWrittenHuman) par session dans la plage. La répartition repose sur une heuristique par modification, pas sur une attribution exacte.",
+  metricHelpLinesAiAria: "Aide : lignes — IA (estim.)",
+  metricHelpLinesAiBody:
+    "Somme des lignes estimées « IA » (linesWrittenAi) par session dans la plage. Les gros blocs ou les modifications multi-plages sont plus souvent classés côté IA.",
+  metricHelpLocByLangTitleAria: "Aide : lignes par langage (agrégé)",
+  metricHelpLocByLangTitleBody:
+    "Fusion des couples locByLanguage de chaque session dans la plage : total de lignes nettes par identifiant de langage.",
+  metricHelpCodingSignalsTitleAria: "Aide : signaux de codage par langage (agrégé)",
+  metricHelpCodingSignalsTitleBody:
+    "Fusion des codingSignalsByLanguage des sessions incluses : nombre d’événements de contexte de codage (ouverture, enregistrement, édition, éditeur actif, etc.) par langage.",
+  metricHelpChartSessionsAria: "Aide : sessions par jour",
+  metricHelpChartSessionsBody:
+    "Pour chaque jour du graphique, combien de sessions ont leur jour de session dans ce compartiment. Mêmes règles de plage et d’étiquettes que les cartes récapitulatives.",
+  metricHelpChartTasksAria: "Aide : tâches par jour et par statut",
+  metricHelpChartTasksBody:
+    "Par jour : vert = tâches terminées dans la plage ; ambre = tâches encore en cours. Filtres de jour et d’étiquettes ; les sessions archivées ont des règles de complétion plus strictes.",
+  metricHelpChartTaskTimeAria: "Aide : temps enregistré sur les tâches par jour",
+  metricHelpChartTaskTimeBody:
+    "Pour chaque jour, somme des durées enregistrées sur les tâches (durationMs → minutes) dont le jour de tâche tombe dans ce compartiment. Mêmes règles d’étiquettes et d’archivage que les décomptes de tâches. La hauteur des barres est proportionnelle au jour le plus chargé dans la vue.",
+  metricHelpChartSessionWallAria: "Aide : durée murale des sessions par jour",
+  metricHelpChartSessionWallBody:
+    "Par jour calendaire, somme des minutes « murales » de session : sessionDurationMinutes enregistré si présent, sinon écart entre startAt et endAt. Rattachement au jour de session (comme le décompte des sessions). Diffère du temps de codage (les pauses inactivité ne comptent pas comme codage).",
+  metricHelpTblDayAria: "Aide : colonne jour",
+  metricHelpTblDayBody: "Clé de jour calendaire (date locale) ou « sans date » si aucune date n’a pu être dérivée.",
+  metricHelpTblSessionsAria: "Aide : colonne sessions",
+  metricHelpTblSessionsBody: "Nombre de sessions rattachées à ce jour (mêmes règles que le graphique des sessions).",
+  metricHelpTblDoneAria: "Aide : colonne terminées",
+  metricHelpTblDoneBody: "Nombre de tâches terminées rattachées à ce jour.",
+  metricHelpTblActiveAria: "Aide : colonne en cours",
+  metricHelpTblActiveBody: "Nombre de tâches encore en cours rattachées à ce jour.",
+  metricHelpTblTaskTimeAria: "Aide : colonne — temps enregistré (tâches)",
+  metricHelpTblTaskTimeBody:
+    "Somme des durationMs (en minutes) pour les tâches rattachées à ce jour calendaire — même base que « Temps enregistré sur les tâches » dans la synthèse et qu’un total type feuille de temps / Jira par jour.",
+  metricHelpTblSessionCodingAria: "Aide : colonne — temps de codage (sessions)",
+  metricHelpTblSessionCodingBody:
+    "Somme des codingMinutesSession pour les sessions dont le jour de session correspond à cette ligne. Repose sur le jour de session (pas le jour de tâche), comme la colonne « Sessions ».",
+  metricHelpTblSessionWallAria: "Aide : colonne — durée murale (sessions)",
+  metricHelpTblSessionWallBody:
+    "Total des minutes « murales » pour les sessions de ce jour de session : durée persistée ou startAt→endAt. À comparer au « Codage (sessions) » (temps de frappe actif seulement).",
+  metricHelpSessionWallSummaryAria: "Aide : durée murale des sessions (synthèse)",
+  metricHelpSessionWallSummaryBody:
+    "Somme des minutes murales pour chaque session incluse dans la plage (règles de jour de session et d’étiquettes). Indépendant des minuteurs de tâche ; complète les temps de codage et d’activité.",
+  metricHelpTagTimeSectionAria: "Aide : temps par étiquette (type WBS / SAP)",
+  metricHelpTagTimeSectionBody:
+    "Temps enregistré sur les tâches (durationMs) rattaché à chaque #tag. La durée complète est comptée pour chaque étiquette de la tâche (en additionnant les lignes par étiquette, le total peut dépasser celui des indicateurs lorsque des tâches portent plusieurs étiquettes). Les tâches sans étiquette explicite sont regroupées dans le compartiment par défaut (affiché « défaut » en français). Mêmes filtres de dates, d’étiquettes et règles d’archivage que les autres métriques tâche.",
+  metricHelpTagTimeDayTableAria: "Aide : tableau temps par étiquette et par jour",
+  metricHelpTagTimeDayTableBody:
+    "Une ligne par étiquette et par jour de tâche, avec la somme des minutes pour ce couple. Les lignes sont regroupées par jour calendaire ; plusieurs étiquettes `projet#code` pour un même projet le même jour sont sous une ligne de synthèse @projet — développez pour voir chaque étiquette.",
+  metricHelpTagTimeWeekTableAria: "Aide : calendrier hebdomadaire par étiquette",
+  metricHelpTagTimeWeekTableBody:
+    "Sept cases pour les jours de la semaine plus une colonne total : minutes enregistrées sur les tâches pour chaque date, dans l’ordre imposé par le premier jour de semaine choisi (lundi, dimanche ou samedi). La période rapide « Semaine » des filtres reste lundi–dimanche ; seule cette grille suit votre réglage.",
+  metricHelpTagWeekCalendarAria: "Aide : colonnes du calendrier hebdomadaire",
+  metricHelpTagWeekCalendarBody:
+    "Pour chaque semaine calendaire, la période s’affiche une seule fois au-dessus d’un tableau unique : une ligne par étiquette, les colonnes sont les sept jours locaux (selon le premier jour de semaine) plus le total de la semaine. Chaque en-tête de colonne indique le jour de la semaine et la date calendaire réelle ; survolez un en-tête ou une case jour pour la date exacte (AAAA-MM-JJ). Lorsque plusieurs étiquettes suivent le motif `projet#code` pour un même projet, elles sont regroupées sous une ligne de synthèse @projet ; le chevron permet de développer le détail par étiquette et par minutes.",
+  metricHelpTagWeekStartsOnAria: "Aide : premier jour de la semaine",
+  metricHelpTagWeekStartsOnBody:
+    "Détermine quel jour commence la bande des 7 jours : lundi (habitude ISO), dimanche (habitude nord-américaine) ou samedi. Mémorisé uniquement dans ce navigateur (localStorage).",
+  metricHelpWeekNavAria: "Aide : navigation par semaine",
+  metricHelpWeekNavBody:
+    "Précédente / suivante fait défiler une semaine à la fois parmi les semaines qui ont une durée murale de session ou au moins une session dans la plage filtrée. Sinon, les semaines proviennent du temps enregistré par étiquette ou par @projet. Les graphiques en barres, le tableau par jour et les deux calendriers hebdomadaires (étiquettes et projets) ne montrent que la semaine sélectionnée (sept jours locaux selon le premier jour de semaine).",
+  metricHelpTagTimeColTagAria: "Aide : colonne étiquette",
+  metricHelpTagTimeColTagBody: "Étiquette Kronosys (#tag) ; peut servir de libellé pour la clé saisie à l’extérieur (ex. élément WBS).",
+  metricHelpTagTimeColDayAria: "Aide : colonne jour",
+  metricHelpTagTimeColDayBody: "Jour de la tâche (horodatage de fin ou de début), AAAA-MM-JJ.",
+  metricHelpTagTimeColWeekAria: "Aide : ligne de période",
+  metricHelpTagTimeColWeekBody:
+    "Cette ligne nomme la semaine calendaire une seule fois pour le tableau ci-dessous (dates locales). La frontière de semaine suit le réglage « La semaine commence ».",
+  metricHelpTagTimeColMinutesAria: "Aide : colonne minutes",
+  metricHelpTagTimeColMinutesBody:
+    "Somme des minutes de tâche attribuées à cette étiquette sur la période de la ligne. Les minutes ne sont pas réparties entre les étiquettes : une tâche multi-étiquettes compte sa durée entière sur chaque ligne d’étiquette.",
+  metricHelpProjectTitleAria: "Aide : temps enregistré par projet",
+  metricHelpProjectTitleBody:
+    "Durée enregistrée sur les tâches (durationMs) ventilée par @projet, sous forme de calendrier hebdomadaire : une ligne de période par semaine, puis un tableau avec une ligne par projet et sept colonnes jour plus le total de la semaine. Mêmes plage de dates, filtre d’étiquettes, règles d’archivage et navigation par semaine que le calendrier par étiquette.",
+  metricHelpProjectCalendarAria: "Aide : calendrier hebdomadaire par projet",
+  metricHelpProjectCalendarBody:
+    "Même présentation que le calendrier par étiquette : pour chaque semaine, la plage de dates s’affiche une fois ; chaque ligne correspond à un @projet. Les en-têtes de colonnes indiquent le jour de la semaine et la date calendaire ; les cases jour utilisent le jour de la tâche (fin ou début) ; survol d’un en-tête ou d’une case pour AAAA-MM-JJ.",
+  metricHelpProjectColProjAria: "Aide : colonne projet",
+  metricHelpProjectColProjBody: "Nom du projet sur la tâche, ou « sans projet » si absent.",
+  metricHelpProjectColTasksAria: "Aide : colonne tâches",
+  metricHelpProjectColTasksBody: "Nombre de lignes de tâches agrégées pour ce projet.",
+  metricHelpProjectColTimeAria: "Aide : colonne temps enregistré",
+  metricHelpProjectColTimeBody:
+    "Total des minutes enregistrées sur les tâches pour ce @projet sur les sept jours de la ligne (durationMs).",
+  metricHelpWorkspaceTitleAria: "Aide : instantané du dossier ouvert",
+  metricHelpWorkspaceTitleBody:
+    "Instantané du premier dossier du workspace : lignes par langage à partir des fichiers suivis par Git ou d’un parcours du dossier. Indépendant des sessions Kronosys ; mis en cache ~5 minutes. Voir le paragraphe descriptif sous le titre.",
+  metricHelpWsTotalLinesAria: "Aide : total de lignes (approx.)",
+  metricHelpWsTotalLinesBody:
+    "Total approximatif de lignes lues dans les fichiers source (extensions reconnues), pour cet instantané.",
+  metricHelpWsFileCountAria: "Aide : fichiers parcourus",
+  metricHelpWsFileCountBody: "Nombre de fichiers ayant contribué à l’instantané (après filtres de taille et de type).",
+  metricHelpWsColLangAria: "Aide : colonne langage",
+  metricHelpWsColLangBody: "Identifiant de langage (style TextMate) déduit de l’extension du fichier.",
+  metricHelpWsColLinesAria: "Aide : colonne lignes",
+  metricHelpWsColLinesBody: "Nombre de lignes pour ce langage dans les fichiers parcourus.",
+  metricHelpWsColPercentAria: "Aide : colonne part",
+  metricHelpWsColPercentBody:
+    "Pourcentage du total de lignes de l’instantané pour ce langage (la somme des arrondis peut différer légèrement de 100 %).",
+  metricHelpAggLocColLangAria: "Aide : langage (lignes agrégées)",
+  metricHelpAggLocColLangBody:
+    "Identifiant de langage (style TextMate) ; les valeurs sont additionnées sur les sessions dans la plage.",
+  metricHelpAggLocColLinesAria: "Aide : lignes (agrégé)",
+  metricHelpAggLocColLinesBody: "Total des lignes nettes écrites dans ce langage pour les sessions incluses.",
+  metricHelpAggSigColLangAria: "Aide : langage (signaux)",
+  metricHelpAggSigColLangBody: "Identifiant de langage pour les comptes de signaux agrégés.",
+  metricHelpAggSigColCountAria: "Aide : nombre de signaux",
+  metricHelpAggSigColCountBody: "Total de signaux de contexte de codage pour ce langage sur les sessions incluses.",
+  metricHelpLegendDoneAria: "Aide : légende — tâches terminées",
+  metricHelpLegendDoneBody: "Segment vert : tâches marquées terminées pour ce jour (mêmes filtres que le graphique).",
+  metricHelpLegendActiveAria: "Aide : légende — en cours",
+  metricHelpLegendActiveBody: "Segment ambre : tâches non terminées pour ce jour.",
+  metricHelpLegendSessionsAria: "Aide : légende — sessions",
+  metricHelpLegendSessionsBody:
+    "Hauteur de chaque barre : nombre de sessions dont le jour de session correspond à cette colonne (mêmes règles de plage et d’étiquettes).",
+  metricHelpAssiduityRefAria: "Aide : sessions avec heure de début de référence",
+  metricHelpAssiduityRefBody:
+    "Sessions de la plage pour lesquelles l’hôte a enregistré un instant de début prévu à l’ouverture (`scheduledStartAt` sur l’action `newSession`). Seul l’enchaînement qui lance la session (p. ex. moteur d’horaire) fournit en général ce champ : une nouvelle session lancée depuis le seul tableau de bord n’y a pas, sauf intégration. Mêmes règles de jour de session et d’étiquettes que le comptage des sessions.",
+  metricHelpAssiduityLateCountAria: "Aide : sessions en retard (assiduité)",
+  metricHelpAssiduityLateCountBody:
+    "Parmi les sessions référencées, combien ont démarré après l’instant prévu (écart strictement positif en minutes). Un démarrage à l’heure ou en avance n’augmente pas ce compteur.",
+  metricHelpAssiduityLateTotalAria: "Aide : retard cumulé",
+  metricHelpAssiduityLateTotalBody:
+    "Somme des retards (minutes) session par session dans la plage, en ne comptant que la partie tardive (les démarrages à l’heure ou avant comptent 0).",
+  metricHelpAssiduityAvgLateAria: "Aide : retard moyen (lorsqu’en retard)",
+  metricHelpAssiduityAvgLateBody:
+    "Retard cumulé divisé par le nombre de sessions en retard ; indiqué en « — » s’il n’y en a pas. Pertinent lorsqu’une heure de début a été enregistrée côté hôte.",
+};

package/lib/reportingNonFinalIndicators.test.ts

@@ -0,0 +1,157 @@
+import { describe, expect, it } from "vitest";
+
+import { computeReportingNonFinalFlags } from "./reportingNonFinalIndicators";
+import type { KronosysUpdatePayload } from "./kronosysApi";
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function makePayload(overrides: Partial<KronosysUpdatePayload> = {}): KronosysUpdatePayload {
+  return {
+    viewType: "dashboard",
+    cfg: {},
+    history: [],
+    historyArchived: [],
+    inspectingSessionId: null,
+    knownTags: [],
+    knownProjects: [],
+    userKnownTags: [],
+    excludedSuggestionTags: [],
+    tagDescriptions: {},
+    projectDescriptions: {},
+    gitIdentity: {},
+    dashboardDataOrigin: "local_next",
+    ...overrides,
+  } as KronosysUpdatePayload;
+}
+
+const ALL_TAGS = new Set<string>();
+const DATE_FROM = "";
+const DATE_TO = "";
+
+// ---------------------------------------------------------------------------
+describe("computeReportingNonFinalFlags", () => {
+  it("retourne tout false si payload est null", () => {
+    const flags = computeReportingNonFinalFlags(null, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags).toEqual({
+      sessionsNonFinal: false,
+      projectsNonFinal: false,
+      tagsNonFinal: false,
+    });
+  });
+
+  it("sessionsNonFinal=true si session live ouverte (sessionId non vide, non archivée)", () => {
+    const p = makePayload({ current: { sessionId: "ses-live" } } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(p, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags.sessionsNonFinal).toBe(true);
+  });
+
+  it("sessionsNonFinal=false si session live est archivée", () => {
+    const p = makePayload({ current: { sessionId: "ses-archived", archived: true } } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(p, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags.sessionsNonFinal).toBe(false);
+  });
+
+  it("sessionsNonFinal=true si tasksByDayActive contient des valeurs > 0", () => {
+    const p = makePayload();
+    const flags = computeReportingNonFinalFlags(
+      p, ALL_TAGS, DATE_FROM, DATE_TO, { "2026-04-29": 2 }, "America/Toronto"
+    );
+    expect(flags.sessionsNonFinal).toBe(true);
+  });
+
+  it("sessionsNonFinal=false si tasksByDayActive est vide", () => {
+    const p = makePayload();
+    const flags = computeReportingNonFinalFlags(
+      p, ALL_TAGS, DATE_FROM, DATE_TO, { "2026-04-29": 0 }, "America/Toronto"
+    );
+    expect(flags.sessionsNonFinal).toBe(false);
+  });
+
+  it("projectsNonFinal=true si tâche non terminée avec @projet dans l'historique", () => {
+    const p = makePayload({
+      history: [
+        {
+          sessionId: "ses-1",
+          tasks: [
+            {
+              id: "t1",
+              isDone: false,
+              project: "acme",
+              tags: [],
+              startTime: "2026-04-29T10:00:00Z",
+            },
+          ],
+        },
+      ],
+    } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(p, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags.projectsNonFinal).toBe(true);
+  });
+
+  it("tagsNonFinal=true si tâche non terminée avec #tag dans l'historique", () => {
+    const p = makePayload({
+      history: [
+        {
+          sessionId: "ses-1",
+          tasks: [
+            {
+              id: "t1",
+              isDone: false,
+              project: "",
+              tags: ["dev"],
+              startTime: "2026-04-29T10:00:00Z",
+            },
+          ],
+        },
+      ],
+    } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(p, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags.tagsNonFinal).toBe(true);
+  });
+
+  it("projectsNonFinal=false si toutes les tâches sont terminées", () => {
+    const p = makePayload({
+      history: [
+        {
+          sessionId: "ses-1",
+          tasks: [
+            {
+              id: "t1",
+              isDone: true,
+              project: "acme",
+              tags: ["dev"],
+              startTime: "2026-04-29T10:00:00Z",
+            },
+          ],
+        },
+      ],
+    } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(p, ALL_TAGS, DATE_FROM, DATE_TO, undefined, "America/Toronto");
+    expect(flags.projectsNonFinal).toBe(false);
+    expect(flags.tagsNonFinal).toBe(false);
+  });
+
+  it("hors de la plage de dates → non compté", () => {
+    const p = makePayload({
+      history: [
+        {
+          sessionId: "ses-1",
+          tasks: [
+            {
+              id: "t1",
+              isDone: false,
+              project: "acme",
+              tags: ["dev"],
+              startTime: "2025-01-01T10:00:00Z",
+            },
+          ],
+        },
+      ],
+    } as Partial<KronosysUpdatePayload>);
+    const flags = computeReportingNonFinalFlags(
+      p, ALL_TAGS, "2026-04-01", "2026-04-30", undefined, "America/Toronto"
+    );
+    expect(flags.projectsNonFinal).toBe(false);
+  });
+});