dsh-knowhub 0.9.0 → 0.10.0

package/skills/archify/renderers/shared/validator.mjs

@@ -0,0 +1,83 @@
+import * as validators from './generated-validators.mjs';
+import { throwDiagnosticError } from './diagnostics.mjs';
+
+// "/nodes/3/label" reads much better as "/nodes/3 (id: "router") /label" for the
+// LLM fixing the JSON; resolve the nearest enclosing element's id or label.
+function annotatedPath(instancePath, data) {
+  if (!instancePath) return { path: '/', identity: null };
+  let node = data;
+  let hint = null;
+  for (const seg of instancePath.split('/').slice(1)) {
+    if (node == null || typeof node !== 'object') break;
+    node = node[/^\d+$/.test(seg) ? Number(seg) : seg];
+    if (node && typeof node === 'object' && !Array.isArray(node)) {
+      const tag = node.id ?? node.label;
+      if (tag != null) hint = String(tag);
+    }
+  }
+  return { path: instancePath, identity: hint };
+}
+
+function annotatePath(instancePath, data) {
+  const annotated = annotatedPath(instancePath, data);
+  return annotated.identity != null
+    ? `${annotated.path} (id/label: ${JSON.stringify(annotated.identity)})`
+    : annotated.path;
+}
+
+function formatErrors(errors, data) {
+  return errors.map((e) => {
+    const where = annotatePath(e.instancePath, data);
+    const detail = e.params && Object.keys(e.params).length
+      ? ' ' + JSON.stringify(e.params)
+      : '';
+    return `  ${where} ${e.message}${detail}`;
+  }).join('\n');
+}
+
+export function validateSchema(diagramType, data) {
+  const validate = validators[diagramType];
+  if (!validate) {
+    throw new Error(`validateSchema: unknown diagram type "${diagramType}"`);
+  }
+  if (!validate(data)) {
+    const diagnostics = validate.errors.map((error) => {
+      const annotated = annotatedPath(error.instancePath, data);
+      const subject = {
+        diagramType,
+        path: annotated.path,
+        ...(annotated.identity != null ? { identity: String(annotated.identity) } : {}),
+      };
+      const evidence = {
+        keyword: error.keyword,
+        expected: error.schema,
+        ...error.params,
+      };
+      const supportedFixes = {
+        additionalProperties: [`remove unsupported property ${JSON.stringify(error.params?.additionalProperty)}`],
+        required: [`add required property ${JSON.stringify(error.params?.missingProperty)}`],
+        type: [`use ${JSON.stringify(error.params?.type)} at ${annotated.path}`],
+        enum: [`choose one of the allowed values`],
+        pattern: [`match the required pattern ${JSON.stringify(error.params?.pattern)}`],
+        minimum: [`use a value ${error.params?.comparison || '>='} ${error.params?.limit}`],
+        maximum: [`use a value ${error.params?.comparison || '<='} ${error.params?.limit}`],
+        minItems: [`provide at least ${error.params?.limit} item(s)`],
+        maxItems: [`provide at most ${error.params?.limit} item(s)`],
+        minLength: [`provide at least ${error.params?.limit} character(s)`],
+        maxLength: [`provide at most ${error.params?.limit} character(s)`],
+      }[error.keyword] || [];
+      return {
+        code: `schema/${error.keyword}`,
+        severity: 'error',
+        message: `${annotatePath(error.instancePath, data)} ${error.message}`,
+        subject,
+        evidence,
+        supportedFixes,
+      };
+    });
+    throwDiagnosticError(
+      `${diagramType} schema validation failed:\n${formatErrors(validate.errors, data)}`,
+      diagnostics,
+    );
+  }
+}

package/skills/archify/renderers/timeline/README.md

@@ -0,0 +1,76 @@
+# Event Timeline Renderer
+
+Render `diagram_type: "timeline"` JSON files into the standard Archify HTML template.
+
+```bash
+node archify/renderers/timeline/render-timeline.mjs input.timeline.json output.html
+```
+
+`--layout-json` prints the axis segments, breaks, ticks, lanes, and placed
+events (with their millisecond timestamps and x positions) instead of HTML.
+
+## Input
+
+```json
+{
+  "schema_version": 1,
+  "diagram_type": "timeline",
+  "meta": { "title": "Payment failure incident", "evidence": "illustrative", "timezone": "Asia/Shanghai" },
+  "lanes": [{ "id": "release", "label": "Release" }],
+  "events": [{ "id": "deploy", "at": "2026-10-01T10:00:00+08:00", "title": "Deploy v2.4", "lane": "release" }]
+}
+```
+
+- `at` is ISO 8601 with an explicit `Z` or `±HH:MM` offset (schema). An
+  impossible date fails `timeline/invalid-timestamp`.
+- `meta.timezone` is an IANA zone (default `UTC`) used for every tick and label;
+  ticks fall on that zone's wall clock, so a `+05:30` zone ticks on its own
+  hours. An unknown zone fails `timeline/invalid-timezone`.
+- Across timezone-offset changes, daily ticks stay at local midnight and hourly
+  ticks use real local instants. Both occurrences of a repeated hour remain;
+  skipped hours or dates do not invent ticks. Event timestamps and proportional
+  elapsed-time spacing are unchanged, so consecutive daily ticks can be 23 or 25
+  hours apart. The existing label filter still hides text that does not fit.
+- 夏令时和时区调整不会把刻度固定在时间段起点的 UTC 偏移上：日刻度保持当地
+  午夜，小时刻度仅对应真实存在的当地时刻。回拨产生的两个相同墙钟时刻都保留；
+  跳过的小时或整天不补造刻度。事件时间与轴上的实际时间距离不变，因此相邻
+  日刻度之间可以是 23 或 25 小时；空间不足的刻度文字仍按原有规则隐藏。
+- `meta.evidence` (`observed` or `illustrative`) is required and drawn as a
+  badge at the top-left of the canvas.
+- With `lanes`, every event names a declared lane (`timeline/unknown-lane`).
+  `detail` appears in the Semantic Passport; `kind` (`change`, `alert`,
+  `action`, `recovery`) colours the card and adds a legend entry.
+
+## Axis
+
+Events are sorted by time (ties keep authored order). x is linear in time with
+one scale for the whole diagram; every lane shares the same axis, so one
+instant has one x in every lane, whatever offset each timestamp was written in.
+
+`layout.breaks: "auto"` (default) compresses a quiet period longer than 8× the
+median gap between distinct timestamps and 10% of the span (at most the eight
+longest that fit while preserving room for proportional time). A break is a
+fixed-width hatched band with a zig-zag on the axis and
+the omitted duration (`≈ 1 d 11 h`); the axis caption states how many periods
+were compressed, and each break carries `data-break-ms` and an accessible label.
+Inside each segment the scale is the same constant, so distances there remain
+exact. `layout.breaks: "none"` draws one proportional axis. `layout.width`
+(default 960) is the axis width.
+
+## Cards
+
+Each event is a dot on its lane line plus a card with its exact time and title.
+Cards are centred on their instant and sit on either side of the lane line,
+packed into rows outward from it: each takes whichever side lets it sit closest
+to the line without touching an earlier card (ties go below), so simultaneous
+and close events stack instead of overprinting and a burst spreads both ways.
+Stems are drawn behind every card, and every dot sits on one shared halo layer, so events seconds apart merge into one outlined capsule. A card is a quiet surface with a tone accent
+for its kind. Titles wrap between words. On a multi-day axis a tick names its
+date only when the date changes.
+
+## Tested size
+
+`examples/archify-dev-activity.timeline.json` is observed data (20 tag and
+merge timestamps from this repository's `origin/dev`, including events 19 s
+apart, a `+05:30` committer offset, and five compressed quiet periods). It
+renders in about 0.3s and passes the showcase gates.