@jarenjs/mermaid 0.46.4 → 0.49.2

package/schemas/jaren-mermaid-ast.schema.json

@@ -4,74 +4,416 @@
   "title": "Jaren Mermaid diagram document",
   "description": "The DiagramDocument envelope and per-type AST vocabulary of @jarenjs/mermaid (normative prose in docs/MERMAID-FORMAT.md). Draft-neutral: no $ref siblings, no unevaluated*, no $dynamic*. The AST is geometry-free — layout is a separate pass.",
   "type": "object",
-  "required": ["$mermaid", "diagram", "config", "ast", "meta"],
+  "required": [
+    "$mermaid",
+    "diagram",
+    "config",
+    "ast",
+    "meta"
+  ],
   "properties": {
-    "$mermaid": { "const": "0.1" },
-    "diagram": { "type": "string" },
-    "config": { "type": "object" },
-    "ast": { "type": "object" },
+    "$mermaid": {
+      "const": "0.1"
+    },
+    "diagram": {
+      "type": "string"
+    },
+    "config": {
+      "type": "object"
+    },
+    "ast": {
+      "type": "object"
+    },
     "meta": {
       "type": "object",
-      "required": ["hash", "direction", "title"],
+      "required": [
+        "hash",
+        "direction",
+        "title"
+      ],
       "properties": {
-        "hash": { "type": "string" },
-        "direction": { "type": ["string", "null"] },
-        "title": { "type": ["string", "null"] }
+        "hash": {
+          "type": "string"
+        },
+        "direction": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "title": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       }
     }
   },
   "$defs": {
     "flowNode": {
       "type": "object",
-      "required": ["id", "label", "shape"],
+      "required": [
+        "id",
+        "label",
+        "shape"
+      ],
       "properties": {
-        "id": { "type": "string" },
-        "label": { "type": "string" },
-        "shape": { "type": "string" }
+        "id": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "shape": {
+          "type": "string"
+        }
       }
     },
     "flowEdge": {
       "type": "object",
-      "required": ["from", "to", "stroke", "head", "tail", "length", "label"],
+      "required": [
+        "from",
+        "to",
+        "stroke",
+        "head",
+        "tail",
+        "length",
+        "label"
+      ],
       "properties": {
-        "from": { "type": "string" },
-        "to": { "type": "string" },
-        "stroke": { "enum": ["solid", "thick", "dotted"] },
-        "head": { "enum": ["none", "arrow", "circle", "cross"] },
-        "tail": { "enum": ["none", "arrow", "circle", "cross"] },
-        "length": { "type": "integer" },
-        "label": { "type": ["string", "null"] }
+        "from": {
+          "type": "string"
+        },
+        "to": {
+          "type": "string"
+        },
+        "stroke": {
+          "enum": [
+            "solid",
+            "thick",
+            "dotted"
+          ]
+        },
+        "head": {
+          "enum": [
+            "none",
+            "arrow",
+            "circle",
+            "cross"
+          ]
+        },
+        "tail": {
+          "enum": [
+            "none",
+            "arrow",
+            "circle",
+            "cross"
+          ]
+        },
+        "length": {
+          "type": "integer"
+        },
+        "label": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
       }
     },
     "flowchartAst": {
       "type": "object",
-      "required": ["direction", "nodes", "edges", "subgraphs", "classDefs", "classes", "styles"],
+      "required": [
+        "direction",
+        "nodes",
+        "edges",
+        "subgraphs",
+        "classDefs",
+        "classes",
+        "styles"
+      ],
       "properties": {
-        "direction": { "type": "string" },
-        "nodes": { "type": "array", "items": { "$ref": "#/$defs/flowNode" } },
-        "edges": { "type": "array", "items": { "$ref": "#/$defs/flowEdge" } },
-        "subgraphs": { "type": "array" },
-        "classDefs": { "type": "array" },
-        "classes": { "type": "array" },
-        "styles": { "type": "array" }
+        "direction": {
+          "type": "string"
+        },
+        "nodes": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/flowNode"
+          }
+        },
+        "edges": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/flowEdge"
+          }
+        },
+        "subgraphs": {
+          "type": "array"
+        },
+        "classDefs": {
+          "type": "array"
+        },
+        "classes": {
+          "type": "array"
+        },
+        "styles": {
+          "type": "array"
+        }
       }
     },
     "seqParticipant": {
       "type": "object",
-      "required": ["id", "label", "kind"],
+      "required": [
+        "id",
+        "label",
+        "kind"
+      ],
       "properties": {
-        "id": { "type": "string" },
-        "label": { "type": "string" },
-        "kind": { "enum": ["participant", "actor"] }
+        "id": {
+          "type": "string"
+        },
+        "label": {
+          "type": "string"
+        },
+        "kind": {
+          "enum": [
+            "participant",
+            "actor"
+          ]
+        }
       }
     },
     "sequenceAst": {
       "type": "object",
-      "required": ["participants", "statements", "autonumber"],
+      "required": [
+        "participants",
+        "statements",
+        "autonumber"
+      ],
+      "properties": {
+        "participants": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/seqParticipant"
+          }
+        },
+        "statements": {
+          "type": "array"
+        },
+        "autonumber": {
+          "type": "boolean"
+        }
+      }
+    },
+    "ganttTask": {
+      "description": "A resolved task row. `info` is the raw metadata string the printer round-trips; the rest is the schedule the layout draws. `start`/`end` are epoch milliseconds and the interval is half-open, so `end` is the first instant the task no longer occupies — except for a milestone, which is the instant `start === end`.",
+      "type": "object",
+      "required": [
+        "name",
+        "info",
+        "id",
+        "flags",
+        "start",
+        "end",
+        "duration",
+        "after",
+        "line"
+      ],
+      "properties": {
+        "name": {
+          "type": "string"
+        },
+        "info": {
+          "type": "string"
+        },
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "flags": {
+          "type": "array",
+          "items": {
+            "enum": [
+              "done",
+              "active",
+              "crit",
+              "milestone"
+            ]
+          }
+        },
+        "start": {
+          "type": "number"
+        },
+        "end": {
+          "type": "number"
+        },
+        "duration": {
+          "type": "number",
+          "minimum": 0
+        },
+        "after": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "line": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "ganttRules": {
+      "description": "The header directives, interpreted. `dateFormat` and `axisFormat` keep their Mermaid spelling (dayjs and strftime respectively, not LDML); `tick` is the parsed `tickInterval`; `weekStart` and `weekendStart` are ISO weekdays, 1 is Monday.",
+      "type": "object",
+      "required": [
+        "dateFormat",
+        "axisFormat",
+        "tick",
+        "weekStart",
+        "weekendStart",
+        "excludes",
+        "todayMarker"
+      ],
+      "properties": {
+        "dateFormat": {
+          "type": "string"
+        },
+        "axisFormat": {
+          "type": "string"
+        },
+        "tick": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "required": [
+            "amount",
+            "unit"
+          ],
+          "properties": {
+            "amount": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "unit": {
+              "enum": [
+                "millisecond",
+                "second",
+                "minute",
+                "hour",
+                "day",
+                "week",
+                "month"
+              ]
+            }
+          }
+        },
+        "weekStart": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 7
+        },
+        "weekendStart": {
+          "type": "integer",
+          "minimum": 1,
+          "maximum": 7
+        },
+        "excludes": {
+          "type": "object",
+          "required": [
+            "weekends",
+            "weekdays",
+            "days"
+          ],
+          "properties": {
+            "weekends": {
+              "type": "boolean"
+            },
+            "weekdays": {
+              "type": "array",
+              "items": {
+                "type": "integer",
+                "minimum": 1,
+                "maximum": 7
+              }
+            },
+            "days": {
+              "type": "array",
+              "items": {
+                "type": "integer"
+              }
+            }
+          }
+        },
+        "todayMarker": {
+          "type": [
+            "string",
+            "null"
+          ]
+        }
+      }
+    },
+    "ganttAst": {
+      "description": "gantt — a resolved schedule. `meta` holds the header lines verbatim so the printer stays a fixed point; `rules` holds the same directives interpreted, and `domain` is the half-open span every task falls inside.",
+      "type": "object",
+      "required": [
+        "meta",
+        "rules",
+        "sections",
+        "domain"
+      ],
       "properties": {
-        "participants": { "type": "array", "items": { "$ref": "#/$defs/seqParticipant" } },
-        "statements": { "type": "array" },
-        "autonumber": { "type": "boolean" }
+        "meta": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "rules": {
+          "$ref": "#/$defs/ganttRules"
+        },
+        "sections": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": [
+              "name",
+              "tasks"
+            ],
+            "properties": {
+              "name": {
+                "type": [
+                  "string",
+                  "null"
+                ]
+              },
+              "tasks": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/ganttTask"
+                }
+              }
+            }
+          }
+        },
+        "domain": {
+          "type": "object",
+          "required": [
+            "start",
+            "end"
+          ],
+          "properties": {
+            "start": {
+              "type": "number"
+            },
+            "end": {
+              "type": "number"
+            }
+          }
+        }
       }
     }
   }

package/src/gantt-calendar.js

@@ -0,0 +1,152 @@
+//@ts-check
+/**
+ * @file The working calendar behind `excludes`: which whole days a
+ * schedule skips, and what a duration therefore means.
+ *
+ * Two implementations of one answer live here on purpose. The exported
+ * one expresses an excluded stretch as half-open day intervals and
+ * measures it with `@jarenjs/core/series` (`mergeIntervals`,
+ * `coverageOf`) — the suite's one interval algebra, so a weekend here
+ * and an unavailability there are the same kind of thing. The other,
+ * {@link pushEndDayByDay}, is the naive day-stepping loop the shipped
+ * Mermaid renderer runs; it exists so the fast answer has an
+ * independent oracle to be differential-tested against, and it is the
+ * definition when the two disagree.
+ *
+ * The rule is Mermaid's, not an invention: an excluded day pushes a
+ * task's END out by a whole day, the task's own START is left where the
+ * document put it, and an end that was written as an explicit DATE is
+ * never pushed at all — only one derived from a duration is. Days are
+ * UTC days, because this engine has no local zone and no clock.
+ *
+ * This is not a holiday service. A schedule skips exactly the weekends,
+ * weekday names and dates its own `excludes` line lists.
+ */
+
+import { mergeIntervals, coverageOf } from '@jarenjs/core/series';
+import { isoWeekdayFromDays } from '@jarenjs/core/dates';
+
+/** Milliseconds in a UTC day. */
+export const DAY_MS = 86400000;
+
+/**
+ * Mermaid's own guard: a schedule whose exclusions swallow every day
+ * would push an end forever, so the walk stops and the caller reports a
+ * `JM` error instead of hanging.
+ */
+export const MAX_PUSH_DAYS = 10000;
+
+/**
+ * The index of the UTC day holding `ms`, counting from 1970-01-01.
+ * @param {number} ms
+ * @returns {number}
+ */
+export function dayIndexOf(ms) {
+  return Math.floor(ms / DAY_MS);
+}
+
+/**
+ * @typedef {object} Excluder
+ * @property {boolean} any whether the document excludes anything at all
+ * @property {(dayIndex: number) => boolean} isExcludedDay
+ * @property {(fromDay: number, toDay: number) => { start: number, end: number }[]}
+ *   intervalsIn merged half-open day spans over `[fromDay, toDay)`
+ */
+
+/**
+ * Build the working calendar a document's `excludes`, `weekend` and
+ * `dateFormat` describe.
+ *
+ * @param {{ weekends: boolean, weekdays: number[], days: number[] }} rules -
+ *   `weekdays` are ISO weekday numbers, `days` are day indexes
+ * @param {number} weekendStart - ISO weekday the weekend starts on
+ * @returns {Excluder}
+ */
+export function createExcluder(rules, weekendStart) {
+  const weekdays = new Set(rules.weekdays);
+  if (rules.weekends) {
+    weekdays.add(weekendStart);
+    // the weekend is two days: friday+saturday, or saturday+sunday
+    weekdays.add(weekendStart === 7 ? 1 : weekendStart + 1);
+  }
+  const days = new Set(rules.days);
+  const any = weekdays.size > 0 || days.size > 0;
+
+  /** @param {number} dayIndex @returns {boolean} */
+  const isExcludedDay = (dayIndex) => days.has(dayIndex)
+    || weekdays.has(isoWeekdayFromDays(dayIndex));
+
+  /** @param {number} fromDay @param {number} toDay */
+  const intervalsIn = (fromDay, toDay) => {
+    if (!any || toDay <= fromDay) return [];
+    const spans = [];
+    for (let d = fromDay; d < toDay; d++) {
+      if (isExcludedDay(d))
+        spans.push({ start: d * DAY_MS, end: (d + 1) * DAY_MS });
+    }
+    // touching days merge by default (core/series D4), so a weekend is
+    // one two-day span rather than two abutting ones
+    return spans.length === 0 ? [] : mergeIntervals(spans);
+  };
+
+  return { any, isExcludedDay, intervalsIn };
+}
+
+/**
+ * Push a task's end past the excluded days its span crosses.
+ *
+ * The probes are the instants `start + k days` for `k` from 1, which is
+ * what makes this a *day* rule rather than a millisecond one: a task
+ * that starts at noon on Friday and lasts a day ends at noon on Monday
+ * when the weekend is excluded, not at midnight.
+ *
+ * @param {number} start - epoch milliseconds
+ * @param {number} end - epoch milliseconds, at or after `start`
+ * @param {Excluder} excluder
+ * @returns {number} the pushed end, or `NaN` when the exclusions never
+ *   let the task finish
+ */
+export function pushEndPastExclusions(start, end, excluder) {
+  if (!excluder.any || end <= start) return end;
+  const firstDay = dayIndexOf(start) + 1;
+  let out = end;
+  // the iteration is monotone (each round can only find more excluded
+  // days), so it reaches the least fixed point from below
+  for (let round = 0; round < MAX_PUSH_DAYS; round++) {
+    const spanDays = Math.floor((out - start) / DAY_MS);
+    if (spanDays < 1) return out;
+    if (spanDays > MAX_PUSH_DAYS) return NaN;
+    const window = { start: firstDay * DAY_MS, end: (firstDay + spanDays) * DAY_MS };
+    const excluded = coverageOf(excluder.intervalsIn(firstDay, firstDay + spanDays), window);
+    const next = end + (excluded / DAY_MS) * DAY_MS;
+    if (next === out) return out;
+    out = next;
+  }
+  return NaN;
+}
+
+/**
+ * The oracle: Mermaid's own day-stepping loop, written plainly. Kept as
+ * a test double rather than as the implementation because it walks
+ * every day of a span one at a time, but it is the definition of the
+ * answer {@link pushEndPastExclusions} computes.
+ *
+ * @param {number} start - epoch milliseconds
+ * @param {number} end - epoch milliseconds
+ * @param {Excluder} excluder
+ * @returns {number} the pushed end, or `NaN` when it never finishes
+ */
+export function pushEndDayByDay(start, end, excluder) {
+  if (!excluder.any || end <= start) return end;
+  let out = end;
+  let probe = start + DAY_MS;
+  let steps = 0;
+  while (probe <= out) {
+    if (excluder.isExcludedDay(dayIndexOf(probe))) {
+      out += DAY_MS;
+      if (++steps > MAX_PUSH_DAYS) return NaN;
+    }
+    probe += DAY_MS;
+  }
+  return out;
+}

package/src/index.js

@@ -39,7 +39,11 @@ export {
 /**
  * Convenience: parse → layout → render, error-safe, in one call.
  * @param {string} source
- * @param {{ theme?: any }} [options]
+ * @param {{ theme?: any, dateNames?: import('@jarenjs/core/dates').DateNames,
+ *   parseFrontmatter?: (text: string) => any }} [options] - `dateNames`
+ *   is the locale-name record a Gantt's `dateFormat`/`axisFormat` needs
+ *   for a month or weekday token (`compileDateLocale(pack).names`);
+ *   this engine ships none of its own
  * @returns {any} an SVG vnode
  */
 export function renderMermaid(source, options = {}) {