@deskwork/core 0.9.5 → 0.9.6

package/dist/doctor/rules/missing-frontmatter-id.ts

@@ -0,0 +1,317 @@
+/**
+ * Rule: missing-frontmatter-id.
+ *
+ * Audit: every calendar entry whose `id` is not a key in `index.byId`
+ * is a finding. The file binding for that entry isn't there yet.
+ *
+ * Repair: search the content tree for candidate files. Three searches,
+ * widening:
+ *   1. The file at the slug-template path (today's behavior — pre-Phase-19
+ *      scaffolds and most Astro flat layouts).
+ *   2. Any file whose frontmatter `title` matches the entry title.
+ *   3. Any file whose basename (without extension) matches the slug.
+ *
+ * If exactly one candidate emerges, the plan is "write `id: <entry.id>`
+ * into <path>". Multiple candidates produce a prompt the operator
+ * resolves; `--yes` mode skips. Zero candidates is reported and skipped
+ * (nothing to repair without operator input — the file may not exist
+ * at all yet).
+ *
+ * Sibling-relative imports per the project convention.
+ */
+
+import { existsSync, readdirSync, statSync } from 'node:fs';
+import { basename, extname, join, relative } from 'node:path';
+import type { CalendarEntry } from '../../types.ts';
+import { resolveBlogFilePath, resolveContentDir } from '../../paths.ts';
+import { readFrontmatter, updateFrontmatter } from '../../frontmatter.ts';
+import { readFileSync, writeFileSync } from 'node:fs';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'missing-frontmatter-id';
+
+const MARKDOWN_EXTENSIONS = new Set(['.md', '.mdx', '.markdown']);
+const SKIP_DIRS = new Set(['scrapbook', 'node_modules', 'dist', '.git']);
+
+interface CandidateFile {
+  /** Absolute path to the candidate. */
+  absolutePath: string;
+  /** Why this file was considered (for operator-facing labels). */
+  matchReason: 'template-path' | 'title-match' | 'basename-match';
+}
+
+function shouldSkipDir(name: string): boolean {
+  if (name.startsWith('.')) return true;
+  return SKIP_DIRS.has(name.toLowerCase());
+}
+
+function collectMarkdownFiles(dir: string): string[] {
+  const out: string[] = [];
+  visit(dir);
+  out.sort();
+  return out;
+
+  function visit(currentDir: string): void {
+    let names: string[];
+    try {
+      names = readdirSync(currentDir);
+    } catch {
+      return;
+    }
+    for (const name of names) {
+      const abs = join(currentDir, name);
+      let st;
+      try {
+        st = statSync(abs);
+      } catch {
+        continue;
+      }
+      if (st.isDirectory()) {
+        if (shouldSkipDir(name)) continue;
+        visit(abs);
+        continue;
+      }
+      if (!st.isFile()) continue;
+      if (MARKDOWN_EXTENSIONS.has(extname(name).toLowerCase())) {
+        out.push(abs);
+      }
+    }
+  }
+}
+
+function readTitle(absPath: string): string | undefined {
+  try {
+    const parsed = readFrontmatter(absPath);
+    const t = parsed.data.title;
+    return typeof t === 'string' ? t : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function basenameNoExt(p: string): string {
+  return basename(p, extname(p));
+}
+
+/**
+ * Search the content tree for files that could be bound to `entry`.
+ * Excludes files already claiming a (different) id — those are not
+ * candidates here; the duplicate-id and orphan rules handle them.
+ */
+export function findCandidatesForEntry(
+  projectRoot: string,
+  config: DoctorContext['config'],
+  site: string,
+  entry: CalendarEntry,
+): CandidateFile[] {
+  const candidates: CandidateFile[] = [];
+  const seen = new Set<string>();
+  const contentDir = resolveContentDir(projectRoot, config, site);
+
+  function consider(abs: string, reason: CandidateFile['matchReason']): void {
+    if (!existsSync(abs)) return;
+    if (seen.has(abs)) return;
+    // Skip files whose frontmatter already has a deskwork.id (they
+    // belong to another entry or are duplicates — out of this rule's
+    // scope). Top-level `id:` is the operator's keyspace per Issue #38
+    // and doesn't disqualify a file as a candidate.
+    try {
+      const parsed = readFrontmatter(abs);
+      const existingId = readDeskworkId(parsed.data);
+      if (existingId !== undefined) {
+        return;
+      }
+    } catch {
+      // Unreadable frontmatter — skip; the index already reports it.
+      return;
+    }
+    seen.add(abs);
+    candidates.push({ absolutePath: abs, matchReason: reason });
+  }
+
+  // 1. Slug-template path.
+  const templatePath = resolveBlogFilePath(
+    projectRoot,
+    config,
+    site,
+    entry.slug,
+  );
+  consider(templatePath, 'template-path');
+
+  // 2. + 3. Walk content tree once, match by title and basename.
+  let files: string[];
+  try {
+    files = collectMarkdownFiles(contentDir);
+  } catch {
+    return candidates;
+  }
+  const slugBasename = entry.slug.split('/').pop() ?? entry.slug;
+  for (const abs of files) {
+    if (seen.has(abs)) continue;
+    const title = readTitle(abs);
+    if (title !== undefined && title.trim() === entry.title.trim()) {
+      consider(abs, 'title-match');
+      continue;
+    }
+    const bn = basenameNoExt(abs);
+    if (bn === slugBasename) {
+      consider(abs, 'basename-match');
+    }
+  }
+
+  return candidates;
+}
+
+/**
+ * Write `deskwork.id: <entryId>` into the markdown file's frontmatter.
+ * Idempotent when the file already carries the same id (no-op write
+ * avoided). Issue #38: writes under the `deskwork:` namespace, not the
+ * global top-level `id:`.
+ */
+export function bindFrontmatterId(absPath: string, entryId: string): void {
+  const raw = readFileSync(absPath, 'utf-8');
+  const updated = updateFrontmatter(raw, { deskwork: { id: entryId } });
+  if (updated === raw) return;
+  writeFileSync(absPath, updated, 'utf-8');
+}
+
+/**
+ * Read `deskwork.id` from frontmatter data. Returns `undefined` when
+ * either the `deskwork` block or the nested `id` is missing or
+ * malformed. Used by candidate filters and the migration rule to keep
+ * the namespaced-key reads consistent across rules.
+ */
+function readDeskworkId(data: Record<string, unknown>): string | undefined {
+  const block = data.deskwork;
+  if (block === undefined || block === null) return undefined;
+  if (typeof block !== 'object' || Array.isArray(block)) return undefined;
+  const id = (block as Record<string, unknown>).id;
+  if (typeof id !== 'string') return undefined;
+  const trimmed = id.trim();
+  return trimmed === '' ? undefined : trimmed;
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Calendar entries with no matching frontmatter id',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    const findings: Finding[] = [];
+    for (const entry of ctx.calendar.entries) {
+      if (!entry.id) {
+        // Calendar entries without an id are reported by
+        // calendar-uuid-missing instead — keep concerns separate.
+        continue;
+      }
+      if (ctx.index.byId.has(entry.id)) continue;
+      findings.push({
+        ruleId: RULE_ID,
+        site: ctx.site,
+        severity: 'warning',
+        message: `Entry "${entry.slug}" (id ${entry.id}) is not bound to any file via frontmatter id`,
+        details: {
+          entryId: entry.id,
+          slug: entry.slug,
+          title: entry.title,
+          stage: entry.stage,
+        },
+      });
+    }
+    return findings;
+  },
+
+  async plan(ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    const entryId = String(finding.details.entryId ?? '');
+    const entry = ctx.calendar.entries.find((e) => e.id === entryId);
+    if (!entry) {
+      return {
+        kind: 'report-only',
+        finding,
+        reason: `entry id ${entryId} no longer present in calendar — re-run audit`,
+      };
+    }
+    const candidates = findCandidatesForEntry(
+      ctx.projectRoot,
+      ctx.config,
+      ctx.site,
+      entry,
+    );
+    const contentDir = resolveContentDir(ctx.projectRoot, ctx.config, ctx.site);
+
+    if (candidates.length === 0) {
+      return {
+        kind: 'report-only',
+        finding,
+        reason:
+          `no candidate file found under ${contentDir} for slug "${entry.slug}". ` +
+          'Create the file (e.g. via `deskwork outline`) or move an existing one ' +
+          'into place, then re-run.',
+      };
+    }
+    if (candidates.length === 1) {
+      const c = candidates[0];
+      return {
+        kind: 'apply',
+        finding,
+        summary: `write \`id: ${entry.id}\` into ${relative(ctx.projectRoot, c.absolutePath)} (${c.matchReason})`,
+        payload: { absolutePath: c.absolutePath, entryId: entry.id },
+      };
+    }
+    return {
+      kind: 'prompt',
+      finding,
+      question: `Multiple candidate files for entry "${entry.slug}" (id ${entry.id}). Which file should carry the id?`,
+      choices: candidates.map((c) => ({
+        id: c.absolutePath,
+        label: `${relative(ctx.projectRoot, c.absolutePath)} (${c.matchReason})`,
+        payload: { absolutePath: c.absolutePath, entryId: entry.id },
+      })),
+    };
+  },
+
+  async apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    if (plan.kind !== 'apply') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'plan is not directly appliable; runner should resolve prompt first',
+        skipReason: 'apply-failed',
+      };
+    }
+    const absPath = String(plan.payload.absolutePath ?? '');
+    const entryId = String(plan.payload.entryId ?? '');
+    if (!absPath || !entryId) {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'apply payload missing absolutePath or entryId',
+        skipReason: 'apply-failed',
+      };
+    }
+    try {
+      bindFrontmatterId(absPath, entryId);
+    } catch (err) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: `failed to write frontmatter id: ${reason}`,
+        skipReason: 'apply-failed',
+      };
+    }
+    return {
+      finding: plan.finding,
+      applied: true,
+      message: `wrote id ${entryId} to ${relative(ctx.projectRoot, absPath)}`,
+      details: { absolutePath: absPath, entryId },
+    };
+  },
+};
+
+export default rule;

package/dist/doctor/rules/orphan-frontmatter-id.ts

@@ -0,0 +1,162 @@
+/**
+ * Rule: orphan-frontmatter-id.
+ *
+ * Audit: every entry in the content index whose id has no matching
+ * calendar entry. The file is bound to "something", but the calendar
+ * doesn't know about it.
+ *
+ * Repair: there are three plausible operator intents — (a) add a
+ * calendar row for the file, (b) clear the orphan id from the file
+ * (un-bind), or (c) leave it alone. Without a way to gather the
+ * intent, the rule reports findings and presents a prompt; with
+ * `--yes`, the safest action is "do nothing" — auto-creating
+ * calendar rows or auto-deleting frontmatter is destructive.
+ */
+
+import { readFileSync, writeFileSync } from 'node:fs';
+import { relative } from 'node:path';
+import { parseFrontmatter, removeFrontmatterPaths } from '../../frontmatter.ts';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'orphan-frontmatter-id';
+
+/**
+ * Clear the `deskwork.id` field from a markdown file's frontmatter.
+ * Returns true when the field was present and cleared; false when there
+ * was nothing to clear. Issue #38: scoped to the namespaced key — top-
+ * level `id:` belongs to the operator and is left alone.
+ *
+ * Uses the round-trip-preserving emitter so untouched keys keep their
+ * exact bytes (quoting, comments, ordering). Empty `deskwork:` blocks
+ * are pruned via `removeFrontmatterPaths`.
+ */
+function clearFrontmatterId(absPath: string): boolean {
+  const raw = readFileSync(absPath, 'utf-8');
+  const { data } = parseFrontmatter(raw);
+  const block = data.deskwork;
+  if (block === undefined || block === null) return false;
+  if (typeof block !== 'object' || Array.isArray(block)) return false;
+  const blockObj = block as Record<string, unknown>;
+  if (!('id' in blockObj)) return false;
+
+  const updated = removeFrontmatterPaths(raw, [['deskwork', 'id']]);
+  if (updated === raw) return false;
+  writeFileSync(absPath, updated, 'utf-8');
+  return true;
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Files with frontmatter ids that are not in the calendar',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    const findings: Finding[] = [];
+    const calendarIds = new Set<string>();
+    for (const e of ctx.calendar.entries) {
+      if (e.id) calendarIds.add(e.id);
+    }
+    for (const [id, absPath] of ctx.index.byId) {
+      if (calendarIds.has(id)) continue;
+      findings.push({
+        ruleId: RULE_ID,
+        site: ctx.site,
+        severity: 'warning',
+        message: `File ${relative(ctx.projectRoot, absPath)} carries id ${id}, which is not in the calendar`,
+        details: { absolutePath: absPath, entryId: id },
+      });
+    }
+    return findings;
+  },
+
+  async plan(_ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    const absPath = String(finding.details.absolutePath ?? '');
+    const entryId = String(finding.details.entryId ?? '');
+    return {
+      kind: 'prompt',
+      finding,
+      question: `File ${absPath} has id ${entryId} but no calendar entry matches. Pick an action:`,
+      choices: [
+        {
+          id: 'none',
+          label: 'leave as-is (default; review manually)',
+          payload: { action: 'none' },
+        },
+        {
+          id: 'clear-id',
+          label: `clear the id from ${absPath} (un-bind the file)`,
+          payload: { action: 'clear-id', absolutePath: absPath },
+        },
+      ],
+    };
+  },
+
+  async apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    if (plan.kind !== 'apply') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'plan is not directly appliable; runner should resolve prompt first',
+        skipReason: 'apply-failed',
+      };
+    }
+    const action = String(plan.payload.action ?? '');
+    if (action === 'none') {
+      return {
+        finding: plan.finding,
+        applied: false,
+        message: 'left file unchanged per operator choice',
+        skipReason: 'no-action-needed',
+      };
+    }
+    if (action === 'clear-id') {
+      const absPath = String(plan.payload.absolutePath ?? '');
+      if (!absPath) {
+        return {
+          finding: plan.finding,
+          applied: false,
+          message: 'clear-id apply payload missing absolutePath',
+          skipReason: 'apply-failed',
+        };
+      }
+      try {
+        const changed = clearFrontmatterId(absPath);
+        if (!changed) {
+          return {
+            finding: plan.finding,
+            applied: false,
+            message: `no id field in ${relative(ctx.projectRoot, absPath)} to clear`,
+            skipReason: 'no-action-needed',
+          };
+        }
+      } catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+          finding: plan.finding,
+          applied: false,
+          message: `failed to clear frontmatter id: ${reason}`,
+          skipReason: 'apply-failed',
+        };
+      }
+      return {
+        finding: plan.finding,
+        applied: true,
+        message: `cleared id from ${relative(ctx.projectRoot, absPath)}`,
+        details: { absolutePath: absPath },
+      };
+    }
+    return {
+      finding: plan.finding,
+      applied: false,
+      message: `unknown apply action: ${action}`,
+      skipReason: 'apply-failed',
+    };
+  },
+};
+
+export default rule;

package/dist/doctor/rules/schema-rejected.ts

@@ -0,0 +1,58 @@
+/**
+ * Rule: schema-rejected.
+ *
+ * The host's content collection schema may reject the `id` frontmatter
+ * field that deskwork relies on for the calendar/file binding. We
+ * detect this at *write time* in other code paths (scaffolder, the
+ * other rules' apply()), not by an active probe — running an actual
+ * Astro build inside doctor would be slow and project-specific.
+ *
+ * This rule's audit always returns empty for that reason. The
+ * `printSchemaPatchInstructions` helper is the user-facing surface;
+ * other rules (and the CLI command) call it when they observe an
+ * actual schema rejection. Phase 19b-followup may add an active
+ * probe (write a tmpfile to contentDir, attempt astro check, etc.)
+ * once the integration cost is justified.
+ */
+
+import { printSchemaPatchInstructions } from '../schema-patch.ts';
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'schema-rejected';
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: "Host's content schema rejects the `id` frontmatter field",
+
+  async audit(_ctx: DoctorContext): Promise<Finding[]> {
+    // Passive — see file header. Other code paths surface schema-patch
+    // instructions when they observe an actual rejection.
+    return [];
+  },
+
+  async plan(_ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    return {
+      kind: 'report-only',
+      finding,
+      reason: printSchemaPatchInstructions(),
+    };
+  },
+
+  async apply(_ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    return {
+      finding: plan.finding,
+      applied: false,
+      message:
+        'schema-rejected has no automatic repair — operator must patch the host content schema',
+      skipReason: 'schema-rejected',
+    };
+  },
+};
+
+export default rule;

package/dist/doctor/rules/slug-collision.ts

@@ -0,0 +1,82 @@
+/**
+ * Rule: slug-collision.
+ *
+ * Audit: two or more calendar entries share the same slug. With UUID
+ * identity this is no longer a hard error (joins go through id), but
+ * it's still a bug — the host renderer maps URLs by slug, so two
+ * entries claiming the same slug produces duplicate or hidden public
+ * URLs.
+ *
+ * Repair: rename one slug. Doctor doesn't pick which one — that's an
+ * editorial decision (which entry "owns" the public URL). The rule
+ * reports findings; with no interactive UI it returns `report-only`.
+ * `--yes` mode skips.
+ */
+
+import type {
+  DoctorContext,
+  DoctorRule,
+  Finding,
+  RepairPlan,
+  RepairResult,
+} from '../types.ts';
+
+const RULE_ID = 'slug-collision';
+
+interface CollisionGroup {
+  slug: string;
+  /** Calendar-entry ids sharing this slug, in iteration order. */
+  entryIds: string[];
+}
+
+function findCollisions(ctx: DoctorContext): CollisionGroup[] {
+  const bySlug = new Map<string, string[]>();
+  for (const e of ctx.calendar.entries) {
+    if (!e.slug) continue;
+    const list = bySlug.get(e.slug);
+    if (list) list.push(e.id ?? '');
+    else bySlug.set(e.slug, [e.id ?? '']);
+  }
+  const out: CollisionGroup[] = [];
+  for (const [slug, ids] of bySlug) {
+    if (ids.length > 1) out.push({ slug, entryIds: ids });
+  }
+  return out;
+}
+
+const rule: DoctorRule = {
+  id: RULE_ID,
+  label: 'Duplicate slugs in the calendar',
+
+  async audit(ctx: DoctorContext): Promise<Finding[]> {
+    return findCollisions(ctx).map((g) => ({
+      ruleId: RULE_ID,
+      site: ctx.site,
+      severity: 'error',
+      message: `slug "${g.slug}" is shared by ${g.entryIds.length} calendar entries`,
+      details: { slug: g.slug, entryIds: g.entryIds },
+    }));
+  },
+
+  async plan(_ctx: DoctorContext, finding: Finding): Promise<RepairPlan> {
+    return {
+      kind: 'report-only',
+      finding,
+      reason:
+        'pick which entry owns the slug and rename the others via `deskwork rename-slug` ' +
+        '(or hand-edit the calendar). Doctor refuses to choose automatically — slug is ' +
+        'host-public-URL, an editorial decision.',
+    };
+  },
+
+  async apply(_ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult> {
+    return {
+      finding: plan.finding,
+      applied: false,
+      message: 'slug-collision has no automatic repair (operator must rename)',
+      skipReason: 'editorial-decision',
+    };
+  },
+};
+
+export default rule;