@gitdocket/core 0.0.0 → 0.1.0

package/package.json

@@ -1,18 +1,39 @@
 {
   "name": "@gitdocket/core",
-  "version": "0.0.0",
-  "description": "Bootstrap reservation for GitDocket core; stable releases begin at 0.1.0.",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "The typed file-and-graph engine behind GitDocket.",
   "license": "Apache-2.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/GitDocket/gitdocket.git",
     "directory": "packages/core"
   },
-  "homepage": "https://github.com/GitDocket/gitdocket#readme",
-  "files": ["README.md"],
+  "homepage": "https://gitdocket.com",
+  "engines": {
+    "bun": ">=1.3.14"
+  },
+  "exports": {
+    ".": "./src/index.ts",
+    "./cache": "./src/cache.ts",
+    "./orientation": "./src/orientation.ts",
+    "./overview": "./src/overview.ts"
+  },
+  "files": [
+    "src/**/*.ts",
+    "src/**/*.json",
+    "!src/**/*.test.ts"
+  ],
   "publishConfig": {
     "access": "public",
-    "registry": "https://registry.npmjs.org/",
-    "tag": "bootstrap"
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "remark-frontmatter": "^5.0.0",
+    "remark-parse": "^11.0.0",
+    "unified": "^11.0.5",
+    "unist-util-visit": "^5.1.0",
+    "yaml": "^2.9.0",
+    "zod": "^4.5.4"
   }
 }

package/src/bundle.ts

@@ -0,0 +1,127 @@
+// Bundle loading: FileStore → parsed concept graph with ID resolution
+// (aliases included), duplicate detection, and derived readiness.
+
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { CONFIG_FILENAME, type DocketConfig, parseConfig } from "./config";
+import { type FileStore, LocalFileStore } from "./filestore";
+import {
+  type Concept,
+  type Decision,
+  type Diagnostic,
+  parseConcept,
+  type WorkItem,
+} from "./parse";
+import { buildSchemas } from "./schema";
+import { byManualOrder, isReady, isStatus, type Status } from "./states";
+
+export interface Bundle {
+  config: DocketConfig;
+  concepts: Concept[];
+  workItems: WorkItem[];
+  decisions: Decision[];
+  diagnostics: Diagnostic[];
+  /** Resolve a work item or decision by id — aliases included. */
+  byId(id: string): WorkItem | Decision | undefined;
+  statusById: ReadonlyMap<string, Status>;
+  /** Tasks that are `todo` with every dependency `done`. Derived, never stored. */
+  readyIds(): string[];
+}
+
+/**
+ * The canonical ready queue used by every surface, including bare
+ * `docket task start`. Readiness comes from the bundle; manual rank and
+ * priority supply the user-controlled order, with task ID as the stable
+ * fallback.
+ */
+export function readyWorkItems(bundle: Bundle): WorkItem[] {
+  return bundle
+    .readyIds()
+    .map((id) => bundle.byId(id))
+    .filter((item): item is WorkItem => item?.kind === "work")
+    .sort((a, z) => byManualOrder(a.fm, z.fm));
+}
+
+export async function loadBundle(
+  store: FileStore,
+  config: DocketConfig,
+): Promise<Bundle> {
+  const schemas = buildSchemas(config);
+  const concepts: Concept[] = [];
+  const diagnostics: Diagnostic[] = [];
+
+  for (const path of await store.list()) {
+    const parsed = parseConcept(path, await store.read(path), schemas);
+    diagnostics.push(...parsed.diagnostics);
+    if (parsed.concept) concepts.push(parsed.concept);
+  }
+
+  const workItems = concepts.filter((c): c is WorkItem => c.kind === "work");
+  const decisions = concepts.filter(
+    (c): c is Decision => c.kind === "decision",
+  );
+
+  const index = new Map<string, WorkItem | Decision>();
+  for (const item of [...workItems, ...decisions]) {
+    for (const id of [item.fm.id, ...item.fm.aliases]) {
+      const existing = index.get(id);
+      if (existing) {
+        diagnostics.push({
+          path: item.path,
+          message: `duplicate id ${id} (also in ${existing.path})`,
+          severity: "error",
+        });
+      } else {
+        index.set(id, item);
+      }
+    }
+  }
+
+  const statusById = new Map<string, Status>();
+  for (const item of workItems) {
+    if (isStatus(item.fm.status)) {
+      for (const id of [item.fm.id, ...item.fm.aliases])
+        statusById.set(id, item.fm.status);
+    }
+  }
+
+  return {
+    config,
+    concepts,
+    workItems,
+    decisions,
+    diagnostics,
+    byId: (id) => index.get(id),
+    statusById,
+    readyIds: () =>
+      workItems
+        .filter((w) => w.fm.type === "Task")
+        .filter((w) => isReady(w.fm.status, w.fm.depends_on, statusById))
+        .map((w) => w.fm.id),
+  };
+}
+
+/** Walk upward from `start` to the nearest directory containing docket.yaml. */
+export async function findRepoRoot(start: string): Promise<string | undefined> {
+  let dir = start;
+  for (;;) {
+    const found = await readFile(join(dir, CONFIG_FILENAME), "utf8").then(
+      () => true,
+      () => false,
+    );
+    if (found) return dir;
+    const parent = join(dir, "..");
+    if (parent === dir) return undefined;
+    dir = parent;
+  }
+}
+
+/** Convenience: load the bundle of a repo checkout from its docket.yaml. */
+export async function loadRepo(repoRoot: string): Promise<Bundle> {
+  const configSource = await readFile(
+    join(repoRoot, CONFIG_FILENAME),
+    "utf8",
+  ).catch(() => undefined);
+  const config = parseConfig(configSource);
+  return loadBundle(new LocalFileStore(join(repoRoot, config.bundle)), config);
+}

package/src/cache.ts

@@ -0,0 +1,268 @@
+// SQLite cache: disposable, derived, gitignored — files stay the
+// source of truth. bun:sqlite makes this module Bun-only, so it ships as the
+// `@gitdocket/core/cache` subpath and the main entry stays runtime-portable.
+// Callers with a repo (the CLI) pass in git-derived activity rows.
+
+import type { Database } from "bun:sqlite";
+import { execFileSync } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { join } from "node:path";
+import { Glob } from "bun";
+import type { Bundle } from "./bundle";
+import type { DocketConfig } from "./config";
+import { resolveLink } from "./lint";
+import {
+  resolveVerifyMarkers,
+  scanVerifyMarkers,
+  type VerifyMarker,
+} from "./verify";
+
+export interface ActivityRow {
+  taskId: string;
+  sha: string;
+  date: string;
+  subject: string;
+}
+
+export interface GitCheckpoint {
+  revision: string;
+  time: string;
+}
+
+/** Current Git revision and commit time, or undefined outside usable history. */
+export function gitCheckpoint(cwd: string): GitCheckpoint | undefined {
+  try {
+    const [revision, time] = execFileSync(
+      "git",
+      ["show", "-s", "--format=%H%x1f%cI", "HEAD"],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    )
+      .trim()
+      .split("\x1f");
+    return revision && time ? { revision, time } : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Scan configured repo files for verification markers. This lives beside the
+ * cache because both `docket index` and `docket serve` populate the same
+ * disposable verification rows from it. No config means a fully dormant
+ * feature, and nothing here invokes a test runner.
+ */
+export async function scanRepoMarkers(
+  root: string,
+  config: DocketConfig,
+  bundle: Bundle,
+): Promise<VerifyMarker[]> {
+  if (!config.verify) return [];
+  const seen = new Set<string>();
+  const markers: VerifyMarker[] = [];
+  for (const pattern of config.verify.tests) {
+    for await (const path of new Glob(pattern).scan({ cwd: root })) {
+      const posix = path.replaceAll("\\", "/");
+      if (posix.includes("node_modules/") || seen.has(posix)) continue;
+      seen.add(posix);
+      const content = await readFile(join(root, path), "utf8").catch(() => "");
+      markers.push(...scanVerifyMarkers(posix, content));
+    }
+  }
+  markers.sort((a, z) => a.source.localeCompare(z.source) || a.line - z.line);
+  return resolveVerifyMarkers(
+    markers,
+    new Set(bundle.concepts.map((concept) => concept.path)),
+  );
+}
+
+/** Every commit carrying a Task trailer, one row per (task, commit). Empty if git can't answer. */
+export function scanActivity(
+  cwd: string,
+  trailerKey: string,
+  byId: Bundle["byId"],
+): ActivityRow[] {
+  try {
+    const records = execFileSync(
+      "git",
+      [
+        "log",
+        `--format=%x1e%H%x1f%cI%x1f%s%x1f%(trailers:key=${trailerKey},valueonly)`,
+      ],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).split("\x1e");
+    return records.slice(1).flatMap((record) => {
+      const [sha, date, subject, trailers] = record.split("\x1f");
+      if (!sha || !date) return [];
+      return (trailers ?? "")
+        .split("\n")
+        .map((t) => t.trim())
+        .filter(Boolean)
+        .map((id) => ({
+          taskId: byId(id)?.fm.id ?? id, // aliases resolve to the canonical id
+          sha,
+          date,
+          subject: (subject ?? "").trim(),
+        }));
+    });
+  } catch {
+    return [];
+  }
+}
+
+/**
+ * Count distinct Task-trailered commits after a state-of-play watermark.
+ * Undefined means Git could not resolve the watermark/repository; callers
+ * render that uncertainty instead of pretending the note is current.
+ */
+export function taskLinkedCommitsSince(
+  cwd: string,
+  trailerKey: string,
+  sha: string,
+): number | undefined {
+  if (!/^[0-9a-f]{7,40}$/i.test(sha)) return undefined;
+  try {
+    const records = execFileSync(
+      "git",
+      [
+        "log",
+        `${sha}..HEAD`,
+        `--format=%x1e%H%x1f%(trailers:key=${trailerKey},valueonly)`,
+      ],
+      { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] },
+    ).split("\x1e");
+    return records.slice(1).filter((record) => {
+      const [, trailers = ""] = record.split("\x1f");
+      return trailers.trim().length > 0;
+    }).length;
+  } catch {
+    return undefined;
+  }
+}
+
+const SCHEMA = `
+DROP VIEW IF EXISTS backlinks;
+DROP VIEW IF EXISTS board;
+DROP VIEW IF EXISTS epic_rollup;
+DROP TABLE IF EXISTS concepts;
+DROP TABLE IF EXISTS links;
+DROP TABLE IF EXISTS activity;
+DROP TABLE IF EXISTS verifications;
+DROP TABLE IF EXISTS verification_results;
+CREATE TABLE concepts (
+  path TEXT PRIMARY KEY,
+  id TEXT,
+  type TEXT NOT NULL,
+  title TEXT,
+  status TEXT,
+  priority TEXT,
+  rank REAL,
+  epic TEXT,
+  timestamp TEXT
+);
+CREATE TABLE links (from_path TEXT NOT NULL, target TEXT NOT NULL, to_path TEXT);
+CREATE TABLE activity (task_id TEXT NOT NULL, sha TEXT NOT NULL, date TEXT NOT NULL, subject TEXT NOT NULL);
+-- Verification linkage: resolved docket:verifies markers.
+-- kind is 'test' today; 'case' arrives with the eval profile (Phase B).
+CREATE TABLE verifications (
+  concept_path TEXT NOT NULL,
+  kind TEXT NOT NULL,
+  source_path TEXT NOT NULL,
+  line INTEGER,
+  anchor TEXT
+);
+-- Populated by verify ingest; empty until then. Ephemeral by design:
+-- a cache of CI's last word, dropped on rebuild like every other table.
+CREATE TABLE verification_results (
+  source_path TEXT PRIMARY KEY,
+  status TEXT NOT NULL,
+  ran_at TEXT,
+  detail TEXT
+);
+CREATE VIEW backlinks AS
+  SELECT to_path AS path, from_path FROM links WHERE to_path IS NOT NULL;
+-- Terminal history sorts by transition time (setStatus bumps timestamp),
+-- newest first; active columns lead with manual rank — unranked
+-- tasks trail in the default priority-then-id order.
+CREATE VIEW board AS
+  SELECT status, priority, rank, id, title, path, timestamp FROM concepts
+  WHERE type = 'Task'
+  ORDER BY status,
+           CASE WHEN status IN ('done', 'closed') THEN timestamp END DESC,
+           rank IS NULL, rank,
+           priority, id;
+-- last_activity: freshest timestamp across the epic and its tasks (setStatus
+-- bumps timestamps, so this tracks the latest status transition anywhere in
+-- the epic). Empty string when nothing is stamped, so DESC sorts it last.
+CREATE VIEW epic_rollup AS
+  SELECT e.id AS epic_id, e.title AS epic_title,
+         COUNT(t.path) AS total,
+         COALESCE(SUM(t.status = 'done'), 0) AS done,
+         COALESCE(SUM(t.status = 'closed'), 0) AS closed,
+         max(COALESCE(MAX(t.timestamp), ''), COALESCE(e.timestamp, '')) AS last_activity
+  FROM concepts e
+  LEFT JOIN concepts t ON t.type = 'Task' AND t.epic LIKE '%/' || e.id || '-%'
+  WHERE e.type = 'Epic'
+  GROUP BY e.path;
+`;
+
+/** Rebuild the cache from scratch — it is derived and disposable, never migrated. */
+export function buildCache(
+  db: Database,
+  bundle: Bundle,
+  activity: ActivityRow[] = [],
+  verifications: VerifyMarker[] = [],
+): void {
+  db.exec(SCHEMA);
+  const str = (v: unknown): string | null => (typeof v === "string" ? v : null);
+  const paths = new Set(bundle.concepts.map((c) => c.path));
+
+  const insertConcept = db.prepare(
+    "INSERT INTO concepts (path, id, type, title, status, priority, rank, epic, timestamp) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)",
+  );
+  const insertLink = db.prepare(
+    "INSERT INTO links (from_path, target, to_path) VALUES (?, ?, ?)",
+  );
+  const insertActivity = db.prepare(
+    "INSERT INTO activity (task_id, sha, date, subject) VALUES (?, ?, ?, ?)",
+  );
+  const insertVerification = db.prepare(
+    "INSERT INTO verifications (concept_path, kind, source_path, line, anchor) VALUES (?, ?, ?, ?, ?)",
+  );
+
+  db.transaction(() => {
+    for (const c of bundle.concepts) {
+      insertConcept.run(
+        c.path,
+        str(c.fm.id),
+        c.fm.type,
+        c.fm.title ?? null,
+        str(c.fm.status),
+        str(c.fm.priority),
+        typeof c.fm.rank === "number" ? c.fm.rank : null,
+        str(c.fm.epic),
+        str(c.fm.timestamp),
+      );
+      for (const l of c.links) {
+        if (!l.internal) continue;
+        const resolved = resolveLink(c.path, l.target);
+        insertLink.run(
+          c.path,
+          l.target,
+          resolved && paths.has(resolved) ? resolved : null,
+        );
+      }
+    }
+    for (const a of activity)
+      insertActivity.run(a.taskId, a.sha, a.date, a.subject);
+    for (const v of verifications) {
+      if (!v.spec) continue; // unresolved markers are lint's problem, not rows
+      insertVerification.run(
+        v.spec,
+        "test",
+        v.source,
+        v.line,
+        v.anchor ?? null,
+      );
+    }
+  })();
+}

package/src/config.ts

@@ -0,0 +1,96 @@
+// docket.yaml — parsed with explicit defaults rather than schema magic so a
+// missing or partial config always yields a fully-populated DocketConfig.
+// Unknown keys are preserved (OKF-style tolerance applies to config too).
+
+import { parse as parseYaml } from "yaml";
+import { STATES } from "./states";
+
+export interface DocketConfig {
+  project: string;
+  bundle: string;
+  ids: { scheme: string; decision_prefix: string };
+  workflow: { states: readonly string[] };
+  git: { trailer: string; branch_prefix: string };
+  /** Verification linkage. null = key absent = feature fully dormant. */
+  verify: { tests: string[] } | null;
+  extra: Record<string, unknown>;
+}
+
+export const CONFIG_FILENAME = "docket.yaml";
+
+/** Default bundle root — a Docket-signaling name that doesn't collide
+ * with a repo's existing docs/ folder. Repos with an explicit `bundle:` keep it. */
+export const DEFAULT_BUNDLE = "docket/";
+
+export function parseConfig(source?: string): DocketConfig {
+  const raw: Record<string, unknown> =
+    source &&
+    typeof parseYaml(source) === "object" &&
+    parseYaml(source) !== null
+      ? (parseYaml(source) as Record<string, unknown>)
+      : {};
+
+  const section = (key: string): Record<string, unknown> => {
+    const value = raw[key];
+    return typeof value === "object" && value !== null
+      ? (value as Record<string, unknown>)
+      : {};
+  };
+  const str = (value: unknown, fallback: string): string =>
+    typeof value === "string" && value.length > 0 ? value : fallback;
+
+  const ids = section("ids");
+  const workflow = section("workflow");
+  const git = section("git");
+  const configuredStates = Array.isArray(workflow.states)
+    ? workflow.states.filter((s): s is string => typeof s === "string")
+    : [...STATES];
+  // Canonical states are engine semantics, not optional feature flags. Append
+  // newly introduced states for older adopting configs so upgraded clients can
+  // expose them without rewriting the user's docket.yaml.
+  const states = [
+    ...configuredStates,
+    ...STATES.filter((state) => !configuredStates.includes(state)),
+  ];
+
+  // verify: the whole feature's on/off switch is this key's presence.
+  const verifySection = section("verify");
+  const verify =
+    "verify" in raw
+      ? {
+          tests: Array.isArray(verifySection.tests)
+            ? verifySection.tests.filter(
+                (g): g is string => typeof g === "string",
+              )
+            : [],
+        }
+      : null;
+
+  const known = new Set([
+    "project",
+    "bundle",
+    "ids",
+    "workflow",
+    "git",
+    "verify",
+  ]);
+  const extra = Object.fromEntries(
+    Object.entries(raw).filter(([k]) => !known.has(k)),
+  );
+
+  return {
+    project: str(raw.project, "DKT"),
+    bundle: str(raw.bundle, DEFAULT_BUNDLE),
+    ids: {
+      scheme: str(ids.scheme, "sequential"),
+      decision_prefix: str(ids.decision_prefix, "DEC"),
+    },
+    workflow: { states },
+    git: {
+      trailer: str(git.trailer, "Task"),
+      branch_prefix: str(git.branch_prefix, "task/"),
+    },
+    verify,
+    extra,
+  };
+}

package/src/engine-semantics.ts

@@ -0,0 +1,26 @@
+/**
+ * Canonical agent-facing descriptions of engine-owned task semantics.
+ *
+ * Execution remains in states.ts, bundle.ts, and ops.ts. Shipped workflows
+ * and command adapters interpolate these claims instead of restating them,
+ * while workflow guard tests exercise the executable behavior behind them.
+ */
+
+export const ENGINE_SEMANTICS = {
+  readiness:
+    "Ready is derived, never written: a task is ready only when its stored status is `todo` and every dependency resolves to `done`; an unknown dependency blocks it.",
+  readyOrdering:
+    "The ready queue puts ranked tasks first by ascending `rank`; rank ties and the unranked tail use priority (`p0` through `p3`), then ascending task ID as the stable fallback.",
+  transitions:
+    "Stored status changes go through the engine's canonical transition table; invalid transitions are rejected, `done` and `closed` are terminal, and moving to `closed` requires a disposition note. Only `done` satisfies dependencies or counts as completion.",
+  mutationOwnership: {
+    pickup:
+      "The engine owns task selection, the state-machine-checked status transition, active-task state, title derivation, and the context packet; the pickup workflow owns only their sequence, and a native adapter owns only its bounded rename binding.",
+    grooming:
+      "The engine owns ready/list derivation and task mutation mechanics; the groom workflow owns audit judgment, proposed changes, and the authorization boundary.",
+    close:
+      "The engine owns the state-machine-checked terminal move and dated Log mutation; the close workflow owns the choice between completion (`done`) and non-completion (`closed`), Outcome or Disposition judgment, documentation review, and derived index/log reconciliation.",
+  },
+} as const;
+
+export const READY_QUEUE_DESCRIPTION = `${ENGINE_SEMANTICS.readiness} ${ENGINE_SEMANTICS.readyOrdering}`;

package/src/filestore.ts

@@ -0,0 +1,63 @@
+// FileStore abstracts where a bundle's files live. Local filesystem now;
+// a GitHub Git Data API implementation later lets the hosted App operate
+// without ever cloning a repo.
+
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, join } from "node:path";
+
+export interface FileStore {
+  /** Relative paths (posix separators) of every .md file under the root, sorted. */
+  list(): Promise<string[]>;
+  read(path: string): Promise<string>;
+  write(path: string, content: string): Promise<void>;
+}
+
+export class LocalFileStore implements FileStore {
+  constructor(readonly root: string) {}
+
+  async list(): Promise<string[]> {
+    const out: string[] = [];
+    const walk = async (rel: string): Promise<void> => {
+      const entries = await readdir(join(this.root, rel), {
+        withFileTypes: true,
+      });
+      for (const entry of entries) {
+        if (entry.name.startsWith(".")) continue;
+        const relPath = rel === "" ? entry.name : `${rel}/${entry.name}`;
+        if (entry.isDirectory()) await walk(relPath);
+        else if (entry.name.endsWith(".md")) out.push(relPath);
+      }
+    };
+    await walk("");
+    return out.sort();
+  }
+
+  read(path: string): Promise<string> {
+    return readFile(join(this.root, path), "utf8");
+  }
+
+  async write(path: string, content: string): Promise<void> {
+    const abs = join(this.root, path);
+    await mkdir(dirname(abs), { recursive: true });
+    await writeFile(abs, content, "utf8");
+  }
+}
+
+/** Test double and future in-process cache seed. */
+export class InMemoryFileStore implements FileStore {
+  constructor(readonly files = new Map<string, string>()) {}
+
+  async list(): Promise<string[]> {
+    return [...this.files.keys()].filter((p) => p.endsWith(".md")).sort();
+  }
+
+  async read(path: string): Promise<string> {
+    const content = this.files.get(path);
+    if (content === undefined) throw new Error(`not found: ${path}`);
+    return content;
+  }
+
+  async write(path: string, content: string): Promise<void> {
+    this.files.set(path, content);
+  }
+}