@gitdocket/core 0.0.0 → 0.1.1

package/src/lint.ts

@@ -0,0 +1,240 @@
+// PM 101 encoded as lint, not UI. Errors are profile conformance
+// per the spec's Conformance section; warnings are practice. Core stays
+// git-free: callers with a repo (the CLI) compute git-derived inputs like
+// the trailerless-commit count and pass them in.
+
+import type { Bundle } from "./bundle";
+import type { FileStore } from "./filestore";
+import { type Diagnostic, isReserved } from "./parse";
+import {
+  parseStateOfPlay,
+  presentStateOfPlay,
+  STATE_OF_PLAY_PATH,
+} from "./state-of-play";
+import type { VerifyMarker } from "./verify";
+
+export interface LintOptions {
+  now?: Date;
+  /** Staleness threshold for in-flight statuses and the Freshness watermark. */
+  maxAgeDays?: number;
+  /** Commits without a Task trailer since the watermark — computed by callers with git. */
+  trailerlessCommits?: number;
+  /** Task-linked commits after overview.md's as_of watermark, computed by Git-aware callers. */
+  stateOfPlayCommitsAgo?: number;
+  /**
+   * docket:verifies markers scanned by callers with repo access.
+   * The epic's only lint rule: an unresolvable target warns; "spec is
+   * unverified" deliberately does not — that lives in `verify status`.
+   */
+  verifyMarkers?: VerifyMarker[];
+}
+
+export interface FreshnessWatermark {
+  sha: string;
+  /** The `## YYYY-MM-DD` section the watermark entry sits under. */
+  date?: string;
+}
+
+/**
+ * Latest `**Freshness** … reviewed through <sha>` entry in log.md
+ * (newest-first, so first match wins). Prose may sit between the marker and
+ * the sha — init's baseline stamp reads "baseline at adoption; reviewed
+ * through `<sha>`".
+ */
+export function findFreshnessWatermark(
+  logSource: string,
+): FreshnessWatermark | undefined {
+  let date: string | undefined;
+  for (const line of logSource.split("\n")) {
+    const heading = line.match(/^## (\d{4}-\d{2}-\d{2})/);
+    if (heading) {
+      date = heading[1];
+      continue;
+    }
+    const mark = line.match(
+      /\*\*Freshness\*\*.*reviewed through `?([0-9a-f]{7,40})`?/,
+    );
+    if (mark?.[1]) return { sha: mark[1], date };
+  }
+  return undefined;
+}
+
+/** Resolve an internal link against the bundle root; undefined = not checkable (non-md, escapes bundle). */
+export function resolveLink(
+  fromPath: string,
+  target: string,
+): string | undefined {
+  const clean = target.split("#")[0] ?? "";
+  if (!clean.endsWith(".md")) return undefined;
+  const parts = clean.startsWith("/")
+    ? clean.slice(1).split("/")
+    : [...fromPath.split("/").slice(0, -1), ...clean.split("/")];
+  const out: string[] = [];
+  for (const part of parts) {
+    if (part === "" || part === ".") continue;
+    if (part === "..") {
+      if (out.length === 0) return undefined;
+      out.pop();
+    } else out.push(part);
+  }
+  return out.join("/");
+}
+
+export async function lintBundle(
+  store: FileStore,
+  bundle: Bundle,
+  opts: LintOptions = {},
+): Promise<Diagnostic[]> {
+  const now = opts.now ?? new Date();
+  const maxAgeDays = opts.maxAgeDays ?? 14;
+  const out: Diagnostic[] = [...bundle.diagnostics];
+  const files = new Set(await store.list());
+  const report = (severity: Diagnostic["severity"]) => {
+    return (path: string, message: string) =>
+      out.push({ path, message, severity });
+  };
+  const error = report("error");
+  const warn = report("warning");
+  const ageDays = (iso: string): number =>
+    (now.getTime() - new Date(iso).getTime()) / 86_400_000;
+
+  for (const item of bundle.workItems) {
+    // Conformance: every depends_on entry resolves to an existing task id.
+    for (const dep of item.fm.depends_on) {
+      if (bundle.byId(dep)?.kind !== "work")
+        error(item.path, `depends_on ${dep} does not resolve to a work item`);
+    }
+
+    const filename = item.path.split("/").at(-1) ?? item.path;
+    if (!filename.startsWith(`${item.fm.id}-`))
+      warn(
+        item.path,
+        `filename does not start with ${item.fm.id}- (slug drift?)`,
+      );
+
+    if (item.fm.type === "Epic" && !item.fm.spec)
+      warn(item.path, "epic has no spec link");
+
+    if (
+      item.fm.status === "done" &&
+      /^\s*- \[ \]/m.test(await store.read(item.path))
+    )
+      warn(item.path, "done but has unchecked criteria");
+
+    if (item.fm.status === "in-progress" || item.fm.status === "in-review") {
+      const ts = item.fm.timestamp;
+      if (typeof ts === "string" && ageDays(ts) > maxAgeDays)
+        warn(
+          item.path,
+          `${item.fm.status} but untouched for ${Math.floor(ageDays(ts))} days — stale?`,
+        );
+    }
+  }
+
+  for (const concept of bundle.concepts) {
+    for (const link of concept.links) {
+      if (!link.internal) continue;
+      const resolved = resolveLink(concept.path, link.target);
+      if (resolved && !files.has(resolved))
+        warn(concept.path, `broken link: ${link.target}`);
+    }
+  }
+
+  // overview.md is optional. The linked re-entry note expires on either
+  // substantial task-linked movement or review age. Superseded formats stay
+  // readable and are accepted non-destructively but ask for a linked refresh.
+  if (files.has(STATE_OF_PLAY_PATH)) {
+    const parsed = parseStateOfPlay(await store.read(STATE_OF_PLAY_PATH));
+    out.push(...parsed.diagnostics);
+    if (parsed.note) {
+      const view = presentStateOfPlay(parsed.note, opts.stateOfPlayCommitsAgo, {
+        now,
+      });
+      if (view.review.status === "needs-review") {
+        const why = [
+          ...(view.review.reasons.includes("legacy-format")
+            ? ["legacy prose format"]
+            : []),
+          ...(view.review.reasons.includes("superseded-format")
+            ? ["superseded re-entry/v1 format"]
+            : []),
+          ...(view.review.reasons.includes("evidence-moved")
+            ? [`${view.taskCommitsAgo} task-linked commits behind ${view.asOf}`]
+            : []),
+          ...(view.review.reasons.includes("review-expired")
+            ? [`reviewed ${view.review.reviewedDaysAgo} days ago`]
+            : []),
+        ].join(", ");
+        warn(
+          STATE_OF_PLAY_PATH,
+          `product context needs review (${why}) — run the docket-state-of-play workflow`,
+        );
+      }
+    }
+  }
+
+  // Reserved files (index.md, log.md) aren't concepts, but the hand-maintained
+  // index is exactly where links rot — check them with a light regex pass.
+  for (const path of files) {
+    if (!isReserved(path)) continue;
+    const source = await store.read(path);
+    for (const match of source.matchAll(/\]\(([^)\s]+)\)/g)) {
+      const target = match[1] ?? "";
+      if (/^[a-z][a-z0-9+.-]*:/i.test(target)) continue; // external
+      const resolved = resolveLink(path, target);
+      if (resolved && !files.has(resolved))
+        warn(path, `broken link: ${target}`);
+    }
+  }
+
+  // Stray merge-conflict markers: an ordinary git merge — or a
+  // docket upgrade conflict left unresolved — can land markers in committed
+  // files, and upgrade re-runs report up-to-date once origin is bumped, so
+  // lint is the recurring nag. Requires all three marker lines at line
+  // starts; a fenced code block quoting a complete conflict still trips this
+  // (accepted — quote partial markers instead).
+  for (const path of files) {
+    const source = await store.read(path);
+    if (
+      /^<{7} /m.test(source) &&
+      /^={7}$/m.test(source) &&
+      /^>{7} /m.test(source)
+    )
+      warn(path, "merge-conflict markers present — resolve and remove them");
+  }
+
+  // Verification markers: the target must name an existing concept
+  // by bundle-absolute path. Marker sources live outside the bundle, so the
+  // diagnostic path is repo-relative.
+  for (const m of opts.verifyMarkers ?? []) {
+    if (!m.spec || !files.has(m.spec))
+      warn(
+        m.source,
+        `docket:verifies target does not resolve: ${m.target} (line ${m.line})`,
+      );
+  }
+
+  // Freshness nag — only for bundles that keep a log.md at all.
+  if (files.has("log.md")) {
+    const watermark = findFreshnessWatermark(await store.read("log.md"));
+    if (!watermark) {
+      warn(
+        "log.md",
+        "no **Freshness** watermark — run the docket-freshness workflow",
+      );
+    } else {
+      if (watermark.date && ageDays(watermark.date) > maxAgeDays)
+        warn(
+          "log.md",
+          `Freshness watermark is ${Math.floor(ageDays(watermark.date))} days old — run the docket-freshness workflow`,
+        );
+      if ((opts.trailerlessCommits ?? 0) > 0)
+        warn(
+          "log.md",
+          `${opts.trailerlessCommits} trailerless work commit(s) since Freshness watermark ${watermark.sha} (tracker-only chore(docket) commits exempt) — run /docket-freshness`,
+        );
+    }
+  }
+
+  return out;
+}

package/src/ops.ts

@@ -0,0 +1,320 @@
+// Write operations. Every surface (CLI, MCP, web, App) calls these — there is
+// exactly one write path. Mutations are targeted line edits inside the
+// frontmatter block, never a full YAML re-serialize, so hand-authored
+// formatting and comments survive.
+
+import { stringify as stringifyYaml } from "yaml";
+import { type Bundle, loadBundle } from "./bundle";
+import type { DocketConfig } from "./config";
+import type { FileStore } from "./filestore";
+import type { WorkItemIdCoordinator } from "./id-allocation";
+import { resolveLink } from "./lint";
+import {
+  canTransition,
+  isPriority,
+  isStatus,
+  type Priority,
+  type Status,
+  type WorkItemType,
+} from "./states";
+
+export interface CreateInput {
+  title: string;
+  type?: WorkItemType;
+  description?: string;
+  epic?: string;
+  dependsOn?: string[];
+  priority?: Priority;
+  rank?: number;
+  assignee?: string;
+  tags?: string[];
+  slug?: string;
+}
+
+export function slugify(title: string): string {
+  return (
+    title
+      .toLowerCase()
+      .replace(/[^a-z0-9]+/g, "-")
+      .replace(/^-+|-+$/g, "")
+      .slice(0, 40)
+      .replace(/-+$/g, "") || "item"
+  );
+}
+
+/** Next work-item number: max over ids matching `<project>-<n>`, plus one. */
+export function nextId(
+  bundle: Bundle,
+  knownIds: ReadonlySet<string> = new Set(),
+): string {
+  const pattern = new RegExp(`^${bundle.config.project}-(\\d+)$`);
+  let max = 0;
+  for (const id of [
+    ...bundle.workItems.map((item) => item.fm.id),
+    ...knownIds,
+  ]) {
+    const match = id.match(pattern);
+    if (match?.[1]) max = Math.max(max, Number(match[1]));
+  }
+  return `${bundle.config.project}-${max + 1}`;
+}
+
+const yamlLine = (key: string, value: unknown): string =>
+  stringifyYaml({ [key]: value }).trimEnd();
+
+export async function createWorkItem(
+  store: FileStore,
+  config: DocketConfig,
+  input: CreateInput,
+  coordinator?: WorkItemIdCoordinator,
+): Promise<{ id: string; path: string }> {
+  const create = async (
+    knownIds: ReadonlySet<string>,
+  ): Promise<{ id: string; path: string }> => {
+    // Load inside the coordination boundary: another caller may have created
+    // an item while this process waited for the shared lock.
+    const bundle = await loadBundle(store, config);
+    const id = nextId(bundle, knownIds);
+    if (bundle.byId(id) || knownIds.has(id))
+      throw new Error(`id collision on ${id} — bundle has duplicate ids?`);
+
+    const type = input.type ?? "Task";
+    const slug = input.slug ?? slugify(input.title);
+    const dir = type === "Epic" ? "work/epics" : "work/tasks";
+    const path = `${dir}/${id}-${slug}.md`;
+
+    const lines = [
+      yamlLine("type", type),
+      yamlLine("title", input.title),
+      ...(input.description
+        ? [yamlLine("description", input.description)]
+        : []),
+      yamlLine("id", id),
+      yamlLine("status", "todo"),
+      ...(input.epic ? [yamlLine("epic", input.epic)] : []),
+      ...(input.dependsOn?.length
+        ? [`depends_on: [${input.dependsOn.join(", ")}]`]
+        : []),
+      yamlLine("priority", input.priority ?? "p2"),
+      ...(input.rank !== undefined ? [yamlLine("rank", input.rank)] : []),
+      ...(input.assignee ? [yamlLine("assignee", input.assignee)] : []),
+      ...(input.tags?.length ? [`tags: [${input.tags.join(", ")}]`] : []),
+      yamlLine("timestamp", new Date().toISOString().replace(/\.\d{3}Z$/, "Z")),
+    ];
+
+    const context = input.epic
+      ? `See [epic](${input.epic}).`
+      : "(links to specs/docs here)";
+    const body = `# Context\n\n${context}\n\n# Acceptance Criteria\n\n- [ ] …\n`;
+
+    await store.write(path, `---\n${lines.join("\n")}\n---\n\n${body}`);
+    return { id, path };
+  };
+
+  return coordinator
+    ? coordinator.allocate(config.project, create)
+    : create(new Set());
+}
+
+function splitFrontmatter(source: string): { fm: string; rest: string } {
+  const match = source.match(/^---\n([\s\S]*?)\n---\n?/);
+  if (!match) throw new Error("file has no frontmatter block");
+  return { fm: match[0], rest: source.slice(match[0].length) };
+}
+
+export async function setStatus(
+  store: FileStore,
+  config: DocketConfig,
+  id: string,
+  to: string,
+  opts: { note?: string } = {},
+): Promise<{ id: string; path: string; from: Status; to: Status }> {
+  if (!isStatus(to)) throw new Error(`unknown status "${to}"`);
+  if (to === "closed" && !opts.note?.trim()) {
+    throw new Error("closing without completion requires a disposition note");
+  }
+  const bundle = await loadBundle(store, config);
+  const item = bundle.byId(id);
+  if (item?.kind !== "work") throw new Error(`no work item with id ${id}`);
+
+  const from = item.fm.status;
+  if (from === to) throw new Error(`${item.fm.id} is already ${to}`);
+  if (!canTransition(from, to)) {
+    throw new Error(`invalid transition ${from} → ${to} for ${item.fm.id}`);
+  }
+
+  const source = await store.read(item.path);
+  const { fm, rest } = splitFrontmatter(source);
+  let updated = fm.replace(/^status:.*$/m, `status: ${to}`);
+  const stamp = new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
+  if (/^timestamp:.*$/m.test(updated)) {
+    updated = updated.replace(/^timestamp:.*$/m, `timestamp: ${stamp}`);
+  }
+  await store.write(item.path, updated + rest);
+
+  if (opts.note?.trim())
+    await appendLog(store, config, item.fm.id, opts.note.trim());
+  return { id: item.fm.id, path: item.path, from, to };
+}
+
+// Replace (or remove, line = null) a frontmatter field in place; when the
+// field is absent, insert after the first matching anchor so the result keeps
+// the field order createWorkItem writes. Anchored fields are single-line in
+// CLI-shape files; block-style lists are skipped as anchors on purpose.
+function upsertFmLine(
+  fm: string,
+  key: string,
+  line: string | null,
+  anchors: readonly RegExp[],
+): string {
+  const existing = new RegExp(`^${key}:.*$`, "m");
+  if (existing.test(fm)) {
+    if (line !== null) return fm.replace(existing, line);
+    return fm.replace(new RegExp(`^${key}:.*\\n`, "m"), "");
+  }
+  if (line === null) return fm;
+  for (const anchor of anchors) {
+    const match = fm.match(anchor);
+    if (match?.index !== undefined) {
+      const at = match.index + match[0].length;
+      return `${fm.slice(0, at)}\n${line}${fm.slice(at)}`;
+    }
+  }
+  throw new Error(`no anchor line to place ${key}: after`);
+}
+
+export async function setPriority(
+  store: FileStore,
+  config: DocketConfig,
+  id: string,
+  to: string,
+): Promise<{ id: string; path: string; from: Priority; to: Priority }> {
+  if (!isPriority(to)) throw new Error(`unknown priority "${to}"`);
+  const bundle = await loadBundle(store, config);
+  const item = bundle.byId(id);
+  if (item?.kind !== "work") throw new Error(`no work item with id ${id}`);
+
+  const from = item.fm.priority ?? "p2";
+  if (from === to) throw new Error(`${item.fm.id} is already ${to}`);
+
+  const source = await store.read(item.path);
+  const { fm, rest } = splitFrontmatter(source);
+  // No timestamp bump: timestamp marks status transitions (the epic lists
+  // order on it); a priority tweak shouldn't reshuffle those.
+  const updated = upsertFmLine(fm, "priority", yamlLine("priority", to), [
+    /^depends_on: \[.*$/m,
+    /^epic:.*$/m,
+    /^status:.*$/m,
+  ]);
+  await store.write(item.path, updated + rest);
+  return { id: item.fm.id, path: item.path, from, to };
+}
+
+// Rank is the manual within-lane order: one global number per task,
+// lower first, decimals allowed so an insert between neighbors takes the
+// midpoint and touches only the moved task's file. Unranked sorts last.
+export async function setRank(
+  store: FileStore,
+  config: DocketConfig,
+  id: string,
+  to: number | null,
+): Promise<{
+  id: string;
+  path: string;
+  from: number | null;
+  to: number | null;
+}> {
+  if (to !== null && !Number.isFinite(to))
+    throw new Error(`rank must be a finite number, got ${to}`);
+  const bundle = await loadBundle(store, config);
+  const item = bundle.byId(id);
+  if (item?.kind !== "work") throw new Error(`no work item with id ${id}`);
+  if (item.fm.type === "Epic")
+    throw new Error(`${item.fm.id} is an epic — rank orders tasks`);
+
+  const from = item.fm.rank ?? null;
+  if (from === to)
+    throw new Error(`${item.fm.id} rank is already ${to ?? "unset"}`);
+
+  const source = await store.read(item.path);
+  const { fm, rest } = splitFrontmatter(source);
+  // No timestamp bump — same reasoning as priority: reordering a lane
+  // shouldn't reshuffle the activity-ordered lists.
+  const updated = upsertFmLine(
+    fm,
+    "rank",
+    to === null ? null : yamlLine("rank", to),
+    [/^priority:.*$/m, /^depends_on: \[.*$/m, /^epic:.*$/m, /^status:.*$/m],
+  );
+  await store.write(item.path, updated + rest);
+  return { id: item.fm.id, path: item.path, from, to };
+}
+
+export async function setEpic(
+  store: FileStore,
+  config: DocketConfig,
+  id: string,
+  to: string | null,
+): Promise<{
+  id: string;
+  path: string;
+  from: string | null;
+  to: string | null;
+}> {
+  const bundle = await loadBundle(store, config);
+  const item = bundle.byId(id);
+  if (item?.kind !== "work") throw new Error(`no work item with id ${id}`);
+  if (item.fm.type === "Epic")
+    throw new Error(`${item.fm.id} is an epic — epics don't nest`);
+
+  let link: string | null = null;
+  if (to) {
+    link = to.startsWith("/") ? to : `/${to}`;
+    const resolved = resolveLink(item.path, link);
+    const target = resolved
+      ? bundle.concepts.find((c) => c.path === resolved)
+      : undefined;
+    if (target?.kind !== "work" || target.fm.type !== "Epic")
+      throw new Error(`no epic at ${link}`);
+  }
+
+  const from = typeof item.fm.epic === "string" ? item.fm.epic : null;
+  if (from === link)
+    throw new Error(`${item.fm.id} epic is already ${link ?? "unset"}`);
+
+  const source = await store.read(item.path);
+  const { fm, rest } = splitFrontmatter(source);
+  const updated = upsertFmLine(
+    fm,
+    "epic",
+    link === null ? null : yamlLine("epic", link),
+    [/^status:.*$/m],
+  );
+  await store.write(item.path, updated + rest);
+  return { id: item.fm.id, path: item.path, from, to: link };
+}
+
+/** Insert a dated entry directly under `# Log` (newest first), creating the section if needed. */
+export async function appendLog(
+  store: FileStore,
+  config: DocketConfig,
+  id: string,
+  entry: string,
+): Promise<{ path: string }> {
+  const bundle = await loadBundle(store, config);
+  const item = bundle.byId(id);
+  if (!item) throw new Error(`no item with id ${id}`);
+
+  const date = new Date().toISOString().slice(0, 10);
+  const line = `**${date}** — ${entry}`;
+  const source = await store.read(item.path);
+
+  // Consume the blank lines after the heading and re-emit them around the new
+  // entry, so consecutive entries stay separated by exactly one blank line.
+  const updated = /^# Log\s*$/m.test(source)
+    ? `${source.replace(/^# Log[ \t]*\n*/m, `# Log\n\n${line}\n\n`).trimEnd()}\n`
+    : `${source.trimEnd()}\n\n# Log\n\n${line}\n`;
+
+  await store.write(item.path, updated);
+  return { path: item.path };
+}

package/src/orientation.ts

@@ -0,0 +1,88 @@
+// Repository orientation is one bounded, read-only derivation shared by the
+// CLI and MCP. It intentionally reads only the bundle, the optional committed
+// product checkpoint, and task-linked Git activity; it never writes cache or
+// bundle state.
+
+import { Database } from "bun:sqlite";
+import type { Bundle } from "./bundle";
+import {
+  buildCache,
+  type GitEvidence,
+  scanActivity,
+  scanGitEvidence,
+  taskLinkedCommitsSince,
+} from "./cache";
+import type { DocketConfig } from "./config";
+import type { FileStore } from "./filestore";
+import { deriveOverview, type OverviewModel } from "./overview";
+import {
+  parseStateOfPlay,
+  presentStateOfPlay,
+  REENTRY_CONTEXT_FORMAT,
+  REENTRY_CONTEXT_V1_FORMAT,
+  STATE_OF_PLAY_PATH,
+  type StateOfPlayView,
+} from "./state-of-play";
+
+export type RepositoryOverview = OverviewModel & {
+  narrative?: StateOfPlayView;
+  git: GitEvidence;
+};
+
+export interface RepositoryOverviewInput {
+  bundle: Bundle;
+  config: DocketConfig;
+  store: FileStore;
+  /** Omit outside a Git-backed repository; the derived task selection remains valid. */
+  root?: string;
+}
+
+export async function deriveRepositoryOverview({
+  bundle,
+  config,
+  store,
+  root,
+}: RepositoryOverviewInput): Promise<RepositoryOverview> {
+  const db = new Database(":memory:");
+  try {
+    const git = root
+      ? scanGitEvidence(root, config.git.trailer, bundle.byId)
+      : {
+          status: "history-unavailable" as const,
+          checkpoint: null,
+          activity: [],
+          unmergedActivity: [],
+          worktrees: [],
+          truncated: false,
+          reason: "repository root was not provided",
+        };
+    buildCache(
+      db,
+      bundle,
+      root ? scanActivity(root, config.git.trailer, bundle.byId) : [],
+    );
+    const source = await store.read(STATE_OF_PLAY_PATH).catch(() => undefined);
+    const note = source ? parseStateOfPlay(source).note : undefined;
+    const model = deriveOverview(bundle, db, {
+      checkpoint: git.checkpoint ?? undefined,
+      historyAvailable: git.status === "available",
+      decisionLinks:
+        note?.format === REENTRY_CONTEXT_FORMAT
+          ? note.decisionLinks
+          : note?.format === REENTRY_CONTEXT_V1_FORMAT
+            ? note.assessment.decisionLinks
+            : undefined,
+    });
+    const narrative = note
+      ? presentStateOfPlay(
+          note,
+          root
+            ? taskLinkedCommitsSince(root, config.git.trailer, note.asOf)
+            : undefined,
+        )
+      : undefined;
+    return narrative ? { narrative, ...model, git } : { ...model, git };
+  } finally {
+    db.close();
+  }
+}