tasknotes-spec 0.2.0

package/conformance/lib/adapter-loader.mjs

@@ -0,0 +1,23 @@
+import { pathToFileURL } from "node:url";
+import { resolve } from "node:path";
+
+export async function loadAdapter() {
+  const adapterPath = process.env.TASKNOTES_ADAPTER;
+  if (!adapterPath) {
+    throw new Error("TASKNOTES_ADAPTER is required (path to adapter module)");
+  }
+
+  const absPath = resolve(adapterPath);
+  const mod = await import(pathToFileURL(absPath).href);
+  const metadata = mod.metadata;
+  const execute = mod.execute;
+
+  if (!metadata || typeof metadata !== "object") {
+    throw new Error(`Adapter at ${absPath} must export 'metadata' object`);
+  }
+  if (typeof execute !== "function") {
+    throw new Error(`Adapter at ${absPath} must export 'execute(operation, input)' function`);
+  }
+
+  return { metadata, execute, absPath };
+}

package/conformance/lib/load-fixtures.mjs

@@ -0,0 +1,43 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function loadFixtures(fixturesDir) {
+  const validProfiles = new Set([
+    "core-lite",
+    "recurrence",
+    "extended",
+    "templating",
+    "materialized-occurrences",
+  ]);
+  const files = readdirSync(fixturesDir)
+    .filter((name) => name.endsWith(".json"))
+    .sort();
+
+  const all = [];
+  for (const name of files) {
+    const fullPath = join(fixturesDir, name);
+    const parsed = JSON.parse(readFileSync(fullPath, "utf8"));
+    if (!Array.isArray(parsed)) {
+      throw new Error(`Fixture file must contain an array: ${fullPath}`);
+    }
+    for (const entry of parsed) {
+      all.push(entry);
+    }
+  }
+
+  const ids = new Set();
+  for (const fixture of all) {
+    if (!fixture.id || typeof fixture.id !== "string") {
+      throw new Error(`Fixture missing string id: ${JSON.stringify(fixture)}`);
+    }
+    if (ids.has(fixture.id)) {
+      throw new Error(`Duplicate fixture id: ${fixture.id}`);
+    }
+    if (!fixture.profile || typeof fixture.profile !== "string" || !validProfiles.has(fixture.profile)) {
+      throw new Error(`Fixture ${fixture.id} has invalid profile: ${JSON.stringify(fixture.profile)}`);
+    }
+    ids.add(fixture.id);
+  }
+
+  return all;
+}

package/conformance/lib/matchers.mjs

@@ -0,0 +1,200 @@
+import assert from "node:assert/strict";
+
+function isPlainObject(value) {
+  return value != null && typeof value === "object" && !Array.isArray(value);
+}
+
+function resolveInputRef(context, ref) {
+  if (typeof ref !== "string" || !ref.startsWith("input.")) {
+    return ref;
+  }
+  const path = ref.slice("input.".length).split(".").filter(Boolean);
+  let current = context.input;
+  for (const part of path) {
+    if (current == null || typeof current !== "object") return undefined;
+    current = current[part];
+  }
+  return current;
+}
+
+function deepMatch(actual, expected, context) {
+  if (isPlainObject(expected)) {
+    if (Object.prototype.hasOwnProperty.call(expected, "$regex")) {
+      assert.equal(typeof actual, "string", `Expected string for regex match, got ${typeof actual}`);
+      const pattern = new RegExp(String(expected.$regex));
+      assert.match(actual, pattern);
+      return;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(expected, "$oneOf")) {
+      const options = expected.$oneOf;
+      assert.equal(Array.isArray(options), true, "$oneOf must be an array");
+      let matched = false;
+      for (const option of options) {
+        try {
+          deepMatch(actual, option, context);
+          matched = true;
+          break;
+        } catch {
+          // try next
+        }
+      }
+      assert.equal(matched, true, `Expected value to match oneOf options`);
+      return;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(expected, "$contains")) {
+      const subset = expected.$contains;
+      if (Array.isArray(actual)) {
+        assert.equal(Array.isArray(subset), true, "$contains subset for arrays must be array");
+        for (const expectedItem of subset) {
+          const found = actual.some((item) => {
+            try {
+              deepMatch(item, expectedItem, context);
+              return true;
+            } catch {
+              return false;
+            }
+          });
+          assert.equal(found, true, `Expected array to contain item ${JSON.stringify(expectedItem)}`);
+        }
+        return;
+      }
+
+      assert.equal(isPlainObject(actual), true, "$contains for objects requires object actual");
+      assert.equal(isPlainObject(subset), true, "$contains for objects requires object subset");
+      for (const [key, value] of Object.entries(subset)) {
+        deepMatch(actual[key], value, context);
+      }
+      return;
+    }
+
+    if (Object.prototype.hasOwnProperty.call(expected, "$ref")) {
+      const resolved = resolveInputRef(context, expected.$ref);
+      deepMatch(actual, resolved, context);
+      return;
+    }
+
+    assert.equal(isPlainObject(actual), true, `Expected object, got ${typeof actual}`);
+    for (const [key, value] of Object.entries(expected)) {
+      deepMatch(actual[key], value, context);
+    }
+    return;
+  }
+
+  if (Array.isArray(expected)) {
+    assert.equal(Array.isArray(actual), true, `Expected array, got ${typeof actual}`);
+    assert.equal(actual.length, expected.length, "Array length mismatch");
+    for (let i = 0; i < expected.length; i += 1) {
+      deepMatch(actual[i], expected[i], context);
+    }
+    return;
+  }
+
+  assert.deepEqual(actual, expected);
+}
+
+function assertDateOffset(scheduled, due, expectedOffsetDays) {
+  const start = Date.parse(`${scheduled}T00:00:00Z`);
+  const end = Date.parse(`${due}T00:00:00Z`);
+  const diff = Math.round((end - start) / (24 * 60 * 60 * 1000));
+  assert.equal(diff, expectedOffsetDays);
+}
+
+export function applyAssertion(caseDef, envelope) {
+  const context = { input: caseDef.input };
+
+  if (caseDef.assertion === "envelope_equals") {
+    deepMatch(envelope, caseDef.expect, context);
+    return;
+  }
+
+  if (caseDef.assertion === "envelope_error") {
+    assert.equal(envelope.ok, false, "Expected operation to fail");
+    if (caseDef.expect?.error) {
+      deepMatch(envelope.error, caseDef.expect.error, context);
+    }
+    return;
+  }
+
+  if (caseDef.assertion === "recurrence_complete_invariants") {
+    assert.equal(envelope.ok, true, envelope.error || "Expected success");
+    const result = envelope.result;
+    const completionDate = caseDef.input.completionDate;
+    assert.equal(Array.isArray(result.completeInstances), true);
+    assert.equal(Array.isArray(result.skippedInstances), true);
+    assert.equal(result.completeInstances.includes(completionDate), true);
+    assert.equal(result.skippedInstances.includes(completionDate), false);
+    assert.match(result.updatedRecurrence, /FREQ=/);
+    assert.match(result.updatedRecurrence, /DTSTART:/);
+
+    if (caseDef.input.recurrenceAnchor === "completion") {
+      const dtstartDay = completionDate.replace(/-/g, "");
+      assert.match(result.updatedRecurrence, new RegExp(`DTSTART:${dtstartDay}(?:;|$)`));
+    }
+
+    if (caseDef.input.recurrenceAnchor === "scheduled") {
+      const scheduled = caseDef.input.scheduled;
+      if (typeof scheduled === "string") {
+        const dtstartDay = scheduled.slice(0, 10).replace(/-/g, "");
+        assert.match(result.updatedRecurrence, new RegExp(`DTSTART:${dtstartDay}(?:;|$)`));
+      }
+    }
+
+    if (result.nextScheduled) {
+      assert.match(result.nextScheduled, /^\d{4}-\d{2}-\d{2}/);
+      assert.equal(result.nextScheduled.slice(0, 10) >= completionDate, true);
+    }
+
+    const scheduled = caseDef.input.scheduled;
+    const due = caseDef.input.due;
+    if (result.nextScheduled && result.nextDue && typeof scheduled === "string" && typeof due === "string") {
+      const originalOffset = Math.round((Date.parse(`${due.slice(0, 10)}T00:00:00Z`) - Date.parse(`${scheduled.slice(0, 10)}T00:00:00Z`)) / (24 * 60 * 60 * 1000));
+      assertDateOffset(result.nextScheduled.slice(0, 10), result.nextDue.slice(0, 10), originalOffset);
+    }
+    return;
+  }
+
+  if (caseDef.assertion === "recurrence_recalculate_invariants") {
+    assert.equal(envelope.ok, true, envelope.error || "Expected success");
+    const result = envelope.result;
+    const referenceDate = caseDef.input.referenceDate;
+
+    assert.match(result.updatedRecurrence, /FREQ=/);
+    if (caseDef.input.recurrenceAnchor === "scheduled") {
+      assert.match(result.updatedRecurrence, /DTSTART:/);
+    }
+
+    if (result.nextScheduled) {
+      const nextDay = result.nextScheduled.slice(0, 10);
+      assert.equal(nextDay >= referenceDate, true);
+
+      const complete = Array.isArray(caseDef.input.completeInstances) ? caseDef.input.completeInstances : [];
+      const skipped = Array.isArray(caseDef.input.skippedInstances) ? caseDef.input.skippedInstances : [];
+      if (caseDef.input.recurrenceAnchor !== "completion") {
+        assert.equal(complete.includes(nextDay), false);
+      }
+      assert.equal(skipped.includes(nextDay), false);
+    }
+
+    const scheduled = caseDef.input.scheduled;
+    const due = caseDef.input.due;
+    if (result.nextScheduled && result.nextDue && typeof scheduled === "string" && typeof due === "string") {
+      const originalOffset = Math.round((Date.parse(`${due.slice(0, 10)}T00:00:00Z`) - Date.parse(`${scheduled.slice(0, 10)}T00:00:00Z`)) / (24 * 60 * 60 * 1000));
+      assertDateOffset(result.nextScheduled.slice(0, 10), result.nextDue.slice(0, 10), originalOffset);
+    }
+    return;
+  }
+
+  if (caseDef.assertion === "create_compat_invariants") {
+    deepMatch(envelope, caseDef.expect, context);
+    if (envelope.ok && envelope.result?.path) {
+      assert.match(envelope.result.path, /\.md$/);
+      assert.equal(envelope.result.path.includes("{"), false);
+      assert.equal(envelope.result.path.includes("}"), false);
+    }
+    return;
+  }
+
+  throw new Error(`Unknown assertion kind: ${caseDef.assertion}`);
+}

package/conformance/manifest.json

@@ -0,0 +1,232 @@
+{
+  "generatedAt": "2026-05-31T10:35:30.270Z",
+  "totalCases": 4972,
+  "files": [
+    {
+      "file": "date.json",
+      "cases": 1601
+    },
+    {
+      "file": "field-mapping.json",
+      "cases": 131
+    },
+    {
+      "file": "recurrence.json",
+      "cases": 996
+    },
+    {
+      "file": "create-compat.json",
+      "cases": 322
+    },
+    {
+      "file": "conformance.json",
+      "cases": 20
+    },
+    {
+      "file": "config.json",
+      "cases": 682
+    },
+    {
+      "file": "config-schema.json",
+      "cases": 27
+    },
+    {
+      "file": "validation.json",
+      "cases": 60
+    },
+    {
+      "file": "operations.json",
+      "cases": 100
+    },
+    {
+      "file": "templating.json",
+      "cases": 17
+    },
+    {
+      "file": "migrations.json",
+      "cases": 23
+    },
+    {
+      "file": "dependencies.json",
+      "cases": 386
+    },
+    {
+      "file": "reminders.json",
+      "cases": 564
+    },
+    {
+      "file": "links.json",
+      "cases": 43
+    }
+  ],
+  "byProfile": {
+    "core-lite": 2874,
+    "recurrence": 1020,
+    "extended": 1059,
+    "templating": 18,
+    "materialized-occurrences": 1
+  },
+  "bySection": {
+    "§3": 1595,
+    "§3.6": 6,
+    "§2": 131,
+    "§4": 996,
+    "§5.3": 322,
+    "§7.10": 6,
+    "§7.11": 11,
+    "§7.3.5": 1,
+    "§7.3.3": 2,
+    "§7.3.4": 1,
+    "§9": 667,
+    "§9.2.4": 8,
+    "§11.7": 1,
+    "§9.20": 1,
+    "§9.7.1": 14,
+    "§9.2.3": 3,
+    "§9.19": 15,
+    "§6": 60,
+    "§5.2": 7,
+    "§5.21": 1,
+    "§5.2.1": 3,
+    "§5.4": 4,
+    "§5.5": 4,
+    "§5.6": 3,
+    "§5.7": 4,
+    "§5.8": 5,
+    "§5.9": 8,
+    "§4.11": 4,
+    "§5.10.1": 3,
+    "§5.10.2": 2,
+    "§5.10.3": 3,
+    "§5.11.1": 2,
+    "§5.11.2": 3,
+    "§5.11.3": 2,
+    "§5.12": 1,
+    "§5.13": 2,
+    "§5.14": 4,
+    "§5.4.4": 2,
+    "§5.15": 4,
+    "§5.16": 3,
+    "§5.17": 2,
+    "§5.18": 3,
+    "§5.19.1": 3,
+    "§5.19.2": 3,
+    "§5.19.3": 3,
+    "§5.19.4": 3,
+    "§5.19.5": 4,
+    "§5.19.6": 5,
+    "§5.3.5": 15,
+    "§9.14": 1,
+    "§8.2": 2,
+    "§8.3": 1,
+    "§8.4": 2,
+    "§8.5": 3,
+    "§8.6": 3,
+    "§8.7": 3,
+    "§8.8": 2,
+    "§8.9": 2,
+    "§8.13": 1,
+    "§8.10": 1,
+    "§8.11": 1,
+    "§8.12": 1,
+    "§8.14": 1,
+    "§10": 946,
+    "§10.2.6": 4,
+    "§11.3": 25,
+    "§11": 10,
+    "§11.5": 4,
+    "§11.6": 4
+  },
+  "byOperation": {
+    "date.parse_utc": 509,
+    "date.parse_local": 509,
+    "date.validate": 485,
+    "date.get_part": 16,
+    "date.has_time": 20,
+    "date.is_same": 20,
+    "date.is_before": 20,
+    "date.resolve_operation_target": 19,
+    "date.day_in_timezone": 6,
+    "field.default_mapping": 17,
+    "field.build_mapping": 48,
+    "field.is_completed_status": 9,
+    "field.default_completed_status": 3,
+    "field.normalize": 23,
+    "field.denormalize": 23,
+    "field.resolve_display_title": 8,
+    "recurrence.complete": 760,
+    "recurrence.recalculate": 240,
+    "create_compat.create": 322,
+    "meta.claim": 4,
+    "meta.has_capability": 11,
+    "meta.has_profile": 5,
+    "config.resolve_collection_path": 648,
+    "config.merge_top_level": 4,
+    "config.spec_version_effective": 6,
+    "config.map_tasknotes_plugin": 10,
+    "config.detect_task_file": 14,
+    "config.provider_behavior": 3,
+    "config.validate_schema": 24,
+    "validation.core_evaluate": 56,
+    "validation.time_entries": 4,
+    "op.mutate_with_validation": 4,
+    "op.atomic_write": 2,
+    "op.idempotency_check": 2,
+    "op.update_patch": 4,
+    "op.complete_nonrecurring": 4,
+    "op.uncomplete_nonrecurring": 3,
+    "recurrence.uncomplete_instance": 5,
+    "recurrence.skip_instance": 4,
+    "recurrence.unskip_instance": 4,
+    "recurrence.effective_state": 4,
+    "dependency.add": 3,
+    "dependency.remove": 2,
+    "dependency.replace": 3,
+    "reminder.add": 2,
+    "reminder.update": 3,
+    "reminder.remove": 2,
+    "archive.apply": 1,
+    "delete.remove": 2,
+    "rename.apply": 4,
+    "rename.title_storage_interaction": 2,
+    "batch.apply": 4,
+    "op.detect_conflict": 3,
+    "op.dry_run": 2,
+    "op.error_shape": 3,
+    "time.start": 3,
+    "time.stop": 3,
+    "time.replace_entries": 3,
+    "time.remove_entry": 3,
+    "time.auto_stop_on_complete": 4,
+    "time.report_totals": 5,
+    "templating.parse_sections": 2,
+    "templating.expand_variables": 5,
+    "templating.tokenize": 2,
+    "templating.merge_frontmatter": 2,
+    "templating.create_pipeline": 2,
+    "templating.handle_failure": 2,
+    "templating.config_defaults": 1,
+    "templating.profile_claim_requirements": 1,
+    "migration.compat_mode": 2,
+    "migration.plan": 1,
+    "migration.normalize_aliases": 2,
+    "migration.normalize_temporal": 3,
+    "migration.resolve_instance_overlap": 3,
+    "migration.normalize_dependencies": 3,
+    "migration.normalize_reminders": 2,
+    "migration.normalize_links": 2,
+    "migration.report_summary": 1,
+    "migration.divergence_register": 1,
+    "migration.deprecation_policy": 1,
+    "migration.safety_guards": 1,
+    "migration.compat_statement": 1,
+    "dependency.validate_entry": 378,
+    "dependency.validate_set": 4,
+    "dependency.missing_target_behavior": 4,
+    "reminder.validate_entry": 560,
+    "reminder.validate_set": 4,
+    "link.parse": 25,
+    "link.resolve": 14,
+    "link.update_references_on_rename": 4
+  }
+}