tasknotes-spec 0.2.0

package/README.md

@@ -0,0 +1,80 @@
+# tasknotes-spec
+
+A standalone specification for representing and operating on task data stored in markdown files with YAML frontmatter.
+
+**Version:** 0.2.0-draft
+**Status:** Draft
+**Canonical Source of Truth:** This specification
+
+## Purpose
+
+`tasknotes-spec` defines behavior for tools that read and write task notes in a shared vault.
+The goal is interoperable behavior across implementations, including full-featured applications and lighter clients.
+
+The specification focuses on:
+
+- Task data model and field semantics
+- Date, datetime, and timezone rules
+- Time tracking entry and session-management semantics
+- Recurrence, per-instance completion semantics, and optional materialized occurrence notes
+- Link parsing and resolution semantics
+- Dependencies and reminders semantics
+- Optional create-time templating semantics
+- Operation semantics and write side-effects
+- Validation and conformance expectations
+
+The specification does not define UI design or plugin-internal architecture.
+
+## Why this spec exists
+
+Task data in markdown files is useful because it remains readable and editable with standard tools.
+However, multiple tools operating on the same files can diverge in behavior unless they share explicit rules.
+Divergence is most costly in recurring tasks, timezone handling, and completion state transitions.
+
+This specification provides a precise contract so independent tools can make compatible reads and writes.
+
+## Document structure
+
+| Section | File | Content |
+|---|---|---|
+| §0 | `00-overview.md` | Motivation, scope, governance, and principles |
+| §1 | `01-terminology.md` | Normative definitions |
+| §2 | `02-model-and-mapping.md` | Task model, canonical semantic roles, field mapping |
+| §3 | `03-temporal-semantics.md` | Date/datetime/timezone semantics and serialization |
+| §4 | `04-recurrence.md` | RRULE semantics, per-instance state, and optional occurrence materialization |
+| §5 | `05-operations.md` | Create/update/complete/skip/delete/rename behaviors |
+| §6 | `06-validation.md` | Validation rules and issue model |
+| §7 | `07-conformance.md` | Conformance profiles and claims |
+| §8 | `08-compatibility-and-migrations.md` | Migration and compatibility policy |
+| §9 | `09-configuration.md` | effective configuration schema and provider model (`tasknotes.yaml`, TaskNotes `data.json`, etc.) |
+| §10 | `10-dependencies-and-reminders.md` | Dependency and reminder semantics |
+| §11 | `11-links.md` | Link syntax, parsing, resolution, and rename update behavior |
+| Changelog | `CHANGELOG.md` | Spec release history |
+
+## Conformance model
+
+Implementations claim conformance to one or more profiles defined in §7. A conformance claim MUST include:
+
+- specification version
+- profile name(s)
+- known deviations
+
+## Executable conformance
+
+This repository ships a reusable fixture-based conformance suite in `conformance/`.
+
+- generate fixtures: `npm run conformance:generate`
+- run suite: `TASKNOTES_ADAPTER=<adapter-path> npm run conformance:test`
+- run against `../mdbase-tasknotes`: `npm run conformance:test:mdbase-tasknotes`
+
+## Versioning
+
+The specification uses semantic versioning.
+
+- Patch: clarifications and non-breaking fixes
+- Minor: additive behavior and optional features
+- Major: breaking semantic changes
+
+## License
+
+MIT

package/conformance/README.md

@@ -0,0 +1,31 @@
+# Conformance Suite
+
+This directory contains the reusable `tasknotes-spec` conformance suite.
+
+## Design
+
+- Fixtures are language-neutral JSON in `conformance/fixtures`.
+- Assertions are shared in `conformance/lib/matchers.mjs`.
+- Implementations provide adapters per `conformance/docs/ADAPTER_CONTRACT.md`.
+- `conformance/manifest.json` tracks total case count and section/profile coverage.
+- `conformance/tests/coverage.test.mjs` enforces both section representation and minimum-depth thresholds for key sections/operations.
+
+## Run
+
+Generate fixtures:
+
+```bash
+npm run conformance:generate
+```
+
+Run against a specific adapter:
+
+```bash
+TASKNOTES_ADAPTER=./conformance/adapters/mdbase-tasknotes.adapter.mjs npm run conformance:test
+```
+
+Convenience command for `../mdbase-tasknotes`:
+
+```bash
+npm run conformance:test:mdbase-tasknotes
+```

package/conformance/adapters/mdbase-tasknotes.adapter.mjs

@@ -0,0 +1,141 @@
+import {
+  conformanceMetadata,
+  executeConformanceOperation,
+} from "../../../mdbase-tasknotes/dist/conformance.js";
+export const metadata = conformanceMetadata;
+
+function normalizeHashtagValue(value) {
+  const trimmed = String(value || "").trim();
+  const withoutHash = trimmed.startsWith("#") ? trimmed.slice(1) : trimmed;
+  return withoutHash.toLowerCase();
+}
+
+function stripCodeFencesAndInlineCode(markdown) {
+  const withoutFences = String(markdown || "").replace(/```[\s\S]*?```/g, " ");
+  return withoutFences.replace(/`[^`]*`/g, " ");
+}
+
+function bodyHasTag(body, normalizedTag) {
+  const searchable = stripCodeFencesAndInlineCode(body);
+  const hashtagRegex = /(^|[^\w])#([A-Za-z0-9][A-Za-z0-9/_-]*)/g;
+  let match;
+  while ((match = hashtagRegex.exec(searchable)) != null) {
+    if (match[2].toLowerCase() === normalizedTag) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function frontmatterHasTag(frontmatter, normalizedTag) {
+  const tagsValue = frontmatter?.tags;
+  const entries = Array.isArray(tagsValue)
+    ? tagsValue
+    : (typeof tagsValue === "string" ? [tagsValue] : []);
+  return entries.some((entry) => typeof entry === "string" && normalizeHashtagValue(entry) === normalizedTag);
+}
+
+function normalizeExcludedFolders(value) {
+  const normalizePath = (entry) =>
+    String(entry || "")
+      .replace(/\\/g, "/")
+      .replace(/^\/+/, "")
+      .replace(/\/+$/, "")
+      .trim();
+  if (Array.isArray(value)) {
+    return value.map(normalizePath).filter(Boolean);
+  }
+  if (typeof value === "string") {
+    return value.split(",").map(normalizePath).filter(Boolean);
+  }
+  return [];
+}
+
+function pathExcluded(filePath, excludedFolders) {
+  const normalizedPath = String(filePath || "").replace(/\\/g, "/").replace(/^\/+/, "");
+  return excludedFolders.some((folder) =>
+    normalizedPath === folder || normalizedPath.startsWith(`${folder}/`));
+}
+
+function detectTaskFile(input) {
+  const payload = input && typeof input === "object" ? input : {};
+  const detection = payload.taskDetection && typeof payload.taskDetection === "object"
+    ? payload.taskDetection
+    : {};
+  const frontmatter = payload.frontmatter && typeof payload.frontmatter === "object"
+    ? payload.frontmatter
+    : {};
+  const body = typeof payload.body === "string" ? payload.body : "";
+  const filePath = typeof payload.filePath === "string" ? payload.filePath : "";
+
+  const excludedFolders = normalizeExcludedFolders(detection.excluded_folders);
+  if (filePath && pathExcluded(filePath, excludedFolders)) {
+    return false;
+  }
+
+  const methods = Array.isArray(detection.methods)
+    ? detection.methods.filter((entry) => typeof entry === "string")
+    : (typeof detection.method === "string" ? [detection.method] : []);
+  const normalizedMethods = methods.map((method) => method.trim().toLowerCase()).filter(Boolean);
+  const effectiveMethods = normalizedMethods.length > 0
+    ? normalizedMethods
+    : (typeof detection.tag === "string" ? ["tag"] : []);
+
+  const evaluations = [];
+  for (const method of effectiveMethods) {
+    if (method === "tag") {
+      const configuredTag = typeof detection.tag === "string" ? detection.tag : "task";
+      const normalizedTag = normalizeHashtagValue(configuredTag);
+      evaluations.push(
+        normalizedTag.length > 0
+          && (frontmatterHasTag(frontmatter, normalizedTag) || bodyHasTag(body, normalizedTag)),
+      );
+      continue;
+    }
+
+    if (method === "property") {
+      const propertyName = typeof detection.property_name === "string"
+        ? detection.property_name.trim()
+        : "";
+      const propertyValue = typeof detection.property_value === "string"
+        ? detection.property_value
+        : "";
+      if (!propertyName || !Object.prototype.hasOwnProperty.call(frontmatter, propertyName)) {
+        evaluations.push(false);
+        continue;
+      }
+      evaluations.push(propertyValue.length === 0 || String(frontmatter[propertyName]) === propertyValue);
+    }
+  }
+
+  if (evaluations.length === 0) return false;
+  const combine = detection.combine === "and" ? "and" : "or";
+  return combine === "and" ? evaluations.every(Boolean) : evaluations.some(Boolean);
+}
+
+export async function execute(operation, input) {
+  if (operation === "config.detect_task_file") {
+    return { ok: true, result: { value: detectTaskFile(input) } };
+  }
+
+  if (operation === "dependency.missing_target_behavior") {
+    const payload = input && typeof input === "object" ? input : {};
+    const severity = payload.unresolvedTargetSeverity === "error" ? "error" : "warning";
+    const requireResolvedUidOnWrite = payload.requireResolvedUidOnWrite === true;
+    const treatMissingTargetAsBlocked = payload.treatMissingTargetAsBlocked !== false;
+    const onWrite = payload.onWrite === true;
+    if (requireResolvedUidOnWrite && onWrite) {
+      return { ok: false, error: "unresolved_dependency_target require_resolved_uid_on_write" };
+    }
+    return {
+      ok: true,
+      result: {
+        blocked: treatMissingTargetAsBlocked,
+        issue: "unresolved_dependency_target",
+        severity,
+      },
+    };
+  }
+
+  return executeConformanceOperation(operation, input);
+}