tasknotes-spec 0.2.0

package/conformance/scripts/package-fixtures.mjs

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+/**
+ * package-fixtures.mjs
+ *
+ * Generates fixtures then produces a distributable tarball:
+ *   tasknotes-conformance-{version}.tar.gz
+ *
+ * Contents:
+ *   fixtures/*.json
+ *   docs/FIXTURE_FORMAT.md
+ *   docs/ADAPTER_CONTRACT.md
+ *   docs/RUNNER_GUIDE.md
+ *   lib/matchers.mjs
+ *   tests/runner.test.mjs
+ *   manifest.json
+ *   README.md
+ */
+
+import { execSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { resolve, join } from "node:path";
+
+const root = resolve(import.meta.dirname, "../..");
+const conformanceDir = join(root, "conformance");
+
+// Read version from package.json
+const pkg = JSON.parse(readFileSync(join(root, "package.json"), "utf8"));
+const version = pkg.version;
+if (!version) {
+  console.error("Error: package.json must have a 'version' field");
+  process.exit(1);
+}
+
+const tarballName = `tasknotes-conformance-${version}.tar.gz`;
+const tarballPath = join(root, tarballName);
+
+console.log(`Building conformance package v${version}...`);
+
+// Step 1: Generate fixtures
+console.log("Generating fixtures...");
+execSync("node conformance/scripts/generate-fixtures.mjs", {
+  cwd: root,
+  stdio: "inherit",
+});
+
+// Step 2: Verify expected files exist
+const required = [
+  "conformance/fixtures",
+  "conformance/docs/FIXTURE_FORMAT.md",
+  "conformance/docs/ADAPTER_CONTRACT.md",
+  "conformance/docs/RUNNER_GUIDE.md",
+  "conformance/lib/matchers.mjs",
+  "conformance/tests/runner.test.mjs",
+  "conformance/manifest.json",
+  "conformance/README.md",
+];
+
+for (const rel of required) {
+  if (!existsSync(join(root, rel))) {
+    console.error(`Error: required file/directory not found: ${rel}`);
+    process.exit(1);
+  }
+}
+
+// Step 3: Build the tarball
+// We tar from the conformance/ directory so paths inside are relative to it
+// (fixtures/date.json, docs/FIXTURE_FORMAT.md, etc.)
+console.log(`Creating ${tarballName}...`);
+
+// Read manifest to get the list of fixture files
+const manifest = JSON.parse(
+  readFileSync(join(conformanceDir, "manifest.json"), "utf8")
+);
+const fixtureFiles = manifest.files.map((f) => `fixtures/${f.file}`);
+
+const filesToInclude = [
+  ...fixtureFiles,
+  "docs/FIXTURE_FORMAT.md",
+  "docs/ADAPTER_CONTRACT.md",
+  "docs/RUNNER_GUIDE.md",
+  "lib/matchers.mjs",
+  "tests/runner.test.mjs",
+  "manifest.json",
+  "README.md",
+];
+
+const tarArgs = [
+  "tar",
+  "-czf",
+  tarballPath,
+  "-C",
+  conformanceDir,
+  ...filesToInclude,
+].join(" ");
+
+execSync(tarArgs, { cwd: root, stdio: "inherit" });
+
+console.log(`\nPackage created: ${tarballName}`);
+console.log(`  Version: ${version}`);
+console.log(`  Fixtures: ${manifest.totalCases} cases across ${manifest.files.length} files`);
+console.log(`  Path: ${tarballPath}`);

package/conformance/tests/coverage.test.mjs

@@ -0,0 +1,213 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+const manifest = JSON.parse(
+  readFileSync(resolve(process.cwd(), "conformance", "manifest.json"), "utf8"),
+);
+const templatingFixtures = JSON.parse(
+  readFileSync(resolve(process.cwd(), "conformance", "fixtures", "templating.json"), "utf8"),
+);
+
+const requiredSections = [
+  "§2",
+  "§3",
+  "§4",
+  "§5.2",
+  "§5.2.1",
+  "§5.3",
+  "§5.3.5",
+  "§5.4",
+  "§5.5",
+  "§5.6",
+  "§5.7",
+  "§5.8",
+  "§5.9",
+  "§5.10.1",
+  "§5.10.2",
+  "§5.10.3",
+  "§5.11.1",
+  "§5.11.2",
+  "§5.11.3",
+  "§5.12",
+  "§5.13",
+  "§5.14",
+  "§5.15",
+  "§5.16",
+  "§5.17",
+  "§5.18",
+  "§5.19.1",
+  "§5.19.2",
+  "§5.19.3",
+  "§5.19.4",
+  "§5.19.5",
+  "§5.19.6",
+  "§5.21",
+  "§6",
+  "§7.10",
+  "§7.11",
+  "§8.2",
+  "§8.3",
+  "§8.4",
+  "§8.5",
+  "§8.6",
+  "§8.7",
+  "§8.8",
+  "§8.9",
+  "§8.10",
+  "§8.11",
+  "§8.12",
+  "§8.13",
+  "§8.14",
+  "§9",
+  "§9.7.1",
+  "§9.2.3",
+  "§9.2.4",
+  "§9.19",
+  "§9.20",
+  "§10",
+  "§11",
+  "§11.5",
+  "§11.7",
+];
+
+const sectionMinimums = {
+  "§2": 100,
+  "§3": 1200,
+  "§4": 800,
+  "§5.3": 250,
+  "§6": 50,
+  "§9": 500,
+  "§9.7.1": 10,
+  "§10": 800,
+  "§11": 10,
+  "§11.3": 20,
+  "§11.6": 2,
+};
+
+const operationMinimums = {
+  "date.parse_utc": 300,
+  "date.parse_local": 300,
+  "date.validate": 300,
+  "recurrence.complete": 500,
+  "recurrence.recalculate": 150,
+  "config.resolve_collection_path": 500,
+  "config.detect_task_file": 10,
+  "validation.core_evaluate": 40,
+  "dependency.validate_entry": 300,
+  "reminder.validate_entry": 500,
+  "link.parse": 20,
+  "link.resolve": 10,
+  "link.update_references_on_rename": 2,
+  "templating.expand_variables": 5,
+};
+
+const fixtureFileMinimums = {
+  "date.json": 1000,
+  "recurrence.json": 500,
+  "config.json": 300,
+  "operations.json": 80,
+  "dependencies.json": 200,
+  "reminders.json": 300,
+  "links.json": 30,
+};
+
+test("conformance coverage: required sections represented", () => {
+  for (const section of requiredSections) {
+    const count = manifest.bySection?.[section] || 0;
+    assert.ok(count > 0, `Expected at least one fixture for ${section}`);
+  }
+});
+
+test("conformance coverage: key section depth thresholds", () => {
+  for (const [section, minimum] of Object.entries(sectionMinimums)) {
+    const count = manifest.bySection?.[section] || 0;
+    assert.ok(
+      count >= minimum,
+      `Expected at least ${minimum} fixtures for ${section}, got ${count}`,
+    );
+  }
+});
+
+test("conformance coverage: operation surface is broad", () => {
+  const operations = Object.keys(manifest.byOperation || {});
+  assert.ok(operations.length >= 70, `Expected at least 70 operations, got ${operations.length}`);
+});
+
+test("conformance coverage: key operation depth thresholds", () => {
+  for (const [operation, minimum] of Object.entries(operationMinimums)) {
+    const count = manifest.byOperation?.[operation] || 0;
+    assert.ok(
+      count >= minimum,
+      `Expected at least ${minimum} fixtures for operation ${operation}, got ${count}`,
+    );
+  }
+});
+
+test("conformance coverage: key fixture file depth thresholds", () => {
+  const fileCounts = new Map((manifest.files || []).map((entry) => [entry.file, entry.cases]));
+  for (const [file, minimum] of Object.entries(fixtureFileMinimums)) {
+    const count = fileCounts.get(file) || 0;
+    assert.ok(
+      count >= minimum,
+      `Expected at least ${minimum} fixtures in ${file}, got ${count}`,
+    );
+  }
+});
+
+test("conformance coverage: meta and operation-interface ops represented", () => {
+  const requiredOperations = [
+    "meta.claim",
+    "meta.has_capability",
+    "meta.has_profile",
+    "op.mutate_with_validation",
+    "op.atomic_write",
+    "op.idempotency_check",
+    "op.update_patch",
+    "op.complete_nonrecurring",
+    "op.uncomplete_nonrecurring",
+    "op.error_shape",
+  ];
+
+  for (const operation of requiredOperations) {
+    const count = manifest.byOperation?.[operation] || 0;
+    assert.ok(count > 0, `Expected at least one fixture for operation ${operation}`);
+  }
+});
+
+test("conformance coverage: required templating variables represented", () => {
+  const requiredVariables = [
+    "title",
+    "status",
+    "priority",
+    "dueDate",
+    "scheduledDate",
+    "details",
+    "contexts",
+    "tags",
+    "hashtags",
+    "timeEstimate",
+    "parentNote",
+    "date",
+    "time",
+    "year",
+    "month",
+    "day",
+  ];
+  const covered = new Set();
+
+  for (const fixture of templatingFixtures) {
+    if (fixture.operation !== "templating.expand_variables") continue;
+    const template = String(fixture.input?.template || "");
+    for (const variable of requiredVariables) {
+      if (template.includes(`{{${variable}}}`)) {
+        covered.add(variable);
+      }
+    }
+  }
+
+  for (const variable of requiredVariables) {
+    assert.ok(covered.has(variable), `Expected templating coverage for variable {{${variable}}}`);
+  }
+});

package/conformance/tests/runner.test.mjs

@@ -0,0 +1,102 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { loadFixtures } from "../lib/load-fixtures.mjs";
+import { loadAdapter } from "../lib/adapter-loader.mjs";
+import { applyAssertion } from "../lib/matchers.mjs";
+
+const fixturesDir = resolve(process.cwd(), "conformance", "fixtures");
+const fixtures = loadFixtures(fixturesDir);
+const adapterPath = process.env.TASKNOTES_ADAPTER;
+const requireFullCoverage = process.env.CONFORMANCE_REQUIRE_FULL_COVERAGE === "1";
+let adapterPromise;
+
+function expandProfiles(claimedProfiles) {
+  const expanded = new Set(Array.isArray(claimedProfiles) ? claimedProfiles : []);
+  if (expanded.has("extended")) {
+    expanded.add("recurrence");
+    expanded.add("core-lite");
+  }
+  if (expanded.has("recurrence")) {
+    expanded.add("core-lite");
+  }
+  return expanded;
+}
+
+async function getAdapter(t) {
+  if (!adapterPath) {
+    t.skip("Set TASKNOTES_ADAPTER to run adapter-backed conformance fixtures.");
+    return null;
+  }
+  if (!adapterPromise) {
+    adapterPromise = loadAdapter();
+  }
+  return adapterPromise;
+}
+
+test("conformance: adapter metadata", async (t) => {
+  const adapter = await getAdapter(t);
+  if (!adapter) return;
+  const { metadata } = adapter;
+  assert.equal(typeof metadata.implementation, "string");
+  assert.equal(typeof metadata.version, "string");
+  assert.equal(Array.isArray(metadata.profiles), true);
+  assert.equal(Array.isArray(metadata.capabilities), true);
+});
+
+test(`conformance: run ${fixtures.length} fixture cases`, async (t) => {
+  const adapter = await getAdapter(t);
+  if (!adapter) return;
+  const { metadata, execute } = adapter;
+  const effectiveProfiles = expandProfiles(metadata.profiles);
+  let executedCount = 0;
+
+  for (const fixture of fixtures) {
+    await t.test(`${fixture.id} ${fixture.operation}`, async () => {
+      if (!effectiveProfiles.has(fixture.profile)) {
+        if (requireFullCoverage) {
+          assert.fail(
+            `adapter ${metadata.implementation} missing profile for fixture ${fixture.id}: ${fixture.profile}`,
+          );
+        }
+        t.skip(
+          `adapter ${metadata.implementation} missing profile for fixture: ${fixture.profile}`,
+        );
+        return;
+      }
+
+      const hasCapability = !fixture.requires
+        || fixture.requires.every((cap) => metadata.capabilities.includes(cap));
+
+      if (!hasCapability) {
+        if (requireFullCoverage) {
+          assert.fail(
+            `adapter ${metadata.implementation} missing capability for fixture ${fixture.id}: ${fixture.requires.join(", ")}`,
+          );
+        }
+        t.skip(`adapter ${metadata.implementation} missing capability: ${fixture.requires.join(", ")}`);
+        return;
+      }
+
+      const envelope = await execute(fixture.operation, fixture.input);
+      executedCount += 1;
+      applyAssertion(fixture, envelope);
+    });
+  }
+
+  if (requireFullCoverage) {
+    assert.equal(
+      executedCount,
+      fixtures.length,
+      `Expected all fixtures to execute when CONFORMANCE_REQUIRE_FULL_COVERAGE=1; executed ${executedCount}/${fixtures.length}`,
+    );
+  }
+});
+
+test("conformance: adapter path is resolvable", async (t) => {
+  const adapter = await getAdapter(t);
+  if (!adapter) return;
+  const { absPath } = adapter;
+  assert.equal(typeof absPath, "string");
+  assert.equal(absPath.length > 0, true);
+});

package/conformance/tests/tasknotes-runtime-routing.test.mjs

@@ -0,0 +1,64 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import { resolve } from "node:path";
+import { loadAdapter } from "../lib/adapter-loader.mjs";
+import { loadFixtures } from "../lib/load-fixtures.mjs";
+
+const runtimeOperations = [
+  "archive.apply",
+  "create_compat.create",
+  "dependency.validate_entry",
+  "dependency.validate_set",
+  "dependency.add",
+  "dependency.remove",
+  "dependency.replace",
+  "dependency.missing_target_behavior",
+  "op.complete_nonrecurring",
+  "op.uncomplete_nonrecurring",
+  "recurrence.complete",
+  "recurrence.recalculate",
+  "recurrence.uncomplete_instance",
+  "recurrence.skip_instance",
+  "recurrence.unskip_instance",
+  "recurrence.effective_state",
+  "rename.title_storage_interaction",
+  "reminder.validate_entry",
+  "reminder.validate_set",
+  "reminder.add",
+  "reminder.update",
+  "reminder.remove",
+  "time.start",
+  "time.stop",
+  "time.remove_entry",
+];
+
+test("tasknotes: runtime-routed operation coverage", async (t) => {
+  if (!process.env.TASKNOTES_ADAPTER) {
+    t.skip("Set TASKNOTES_ADAPTER to validate adapter-specific runtime routing.");
+    return;
+  }
+
+  const adapter = await loadAdapter();
+  if (adapter.metadata?.implementation !== "tasknotes") {
+    t.skip("Runtime routing guard is only enforced for the tasknotes adapter.");
+    return;
+  }
+
+  for (const operation of runtimeOperations) {
+    const envelope = await adapter.execute("meta.route_probe", { operation });
+    assert.equal(envelope.ok, true, `route probe failed for operation: ${operation}`);
+    assert.equal(
+      envelope.result?.runtime,
+      true,
+      `operation is no longer runtime-routed: ${operation}`,
+    );
+  }
+
+  const fixtures = loadFixtures(resolve(process.cwd(), "conformance", "fixtures"));
+  const runtimeFixtureCount = fixtures.filter((fixture) => runtimeOperations.includes(fixture.operation)).length;
+  assert.equal(
+    runtimeFixtureCount >= 2300,
+    true,
+    `Expected at least 2300 runtime-routed fixtures, got ${runtimeFixtureCount}`,
+  );
+});

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "tasknotes-spec",
+  "version": "0.2.0",
+  "description": "Specification and conformance fixtures for TaskNotes-compatible markdown task files.",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/callumalpass/tasknotes-spec.git"
+  },
+  "bugs": {
+    "url": "https://github.com/callumalpass/tasknotes-spec/issues"
+  },
+  "homepage": "https://github.com/callumalpass/tasknotes-spec#readme",
+  "files": [
+    "00-overview.md",
+    "01-terminology.md",
+    "02-model-and-mapping.md",
+    "03-temporal-semantics.md",
+    "04-recurrence.md",
+    "05-operations.md",
+    "06-validation.md",
+    "07-conformance.md",
+    "08-compatibility-and-migrations.md",
+    "09-configuration.md",
+    "10-dependencies-and-reminders.md",
+    "11-links.md",
+    "CHANGELOG.md",
+    "conformance/README.md",
+    "conformance/manifest.json",
+    "conformance/adapters/*.mjs",
+    "conformance/adapters/*.ts",
+    "conformance/adapters/tasknotes-core",
+    "conformance/docs",
+    "conformance/fixtures",
+    "conformance/lib",
+    "conformance/scripts",
+    "conformance/tests"
+  ],
+  "scripts": {
+    "conformance:generate": "node conformance/scripts/generate-fixtures.mjs",
+    "conformance:test": "node --test conformance/tests/**/*.test.mjs",
+    "conformance:build:tasknotes-bridge": "mkdir -p conformance/adapters/.generated && npm --prefix ../tasknotes exec -- esbuild conformance/adapters/tasknotes-core/conformance.ts --bundle --platform=node --format=esm --outfile=conformance/adapters/.generated/tasknotes-conformance-core.mjs && npm --prefix ../tasknotes exec -- esbuild conformance/adapters/tasknotes-date-bridge.ts --bundle --platform=node --format=esm --outfile=conformance/adapters/.generated/tasknotes-date-bridge.mjs && npm --prefix ../tasknotes exec -- esbuild conformance/adapters/tasknotes-templating-bridge.ts --bundle --platform=node --format=cjs --outfile=conformance/adapters/.generated/tasknotes-templating-bridge.cjs && npm --prefix ../tasknotes exec -- esbuild conformance/adapters/tasknotes-runtime-bridge.ts --bundle --platform=node --format=cjs --alias:obsidian=./conformance/adapters/tasknotes-runtime-obsidian-shim.ts --outfile=conformance/adapters/.generated/tasknotes-runtime-bridge.cjs",
+    "conformance:test:tasknotes": "npm run conformance:generate && npm run conformance:build:tasknotes-bridge && CONFORMANCE_REQUIRE_FULL_COVERAGE=1 TASKNOTES_ADAPTER=./conformance/adapters/tasknotes.adapter.mjs npm run conformance:test",
+    "conformance:test:mdbase-tasknotes": "npm run conformance:generate && (cd ../mdbase-tasknotes && npm run build) && TASKNOTES_ADAPTER=./conformance/adapters/mdbase-tasknotes.adapter.mjs npm run conformance:test",
+    "conformance:count": "node -e \"const fs=require('fs');const m=JSON.parse(fs.readFileSync('conformance/manifest.json','utf8'));console.log(m.totalCases)\"",
+    "conformance:package": "node conformance/scripts/package-fixtures.mjs"
+  }
+}