@deskwork/core 0.9.5

package/dist/doctor/runner.js

@@ -0,0 +1,289 @@
+/**
+ * Doctor runner — orchestrates rule execution.
+ *
+ * The runner owns the per-site setup (read calendar, build content
+ * index, scope workflows) and walks the registered rules in a stable
+ * order. `runAudit` only calls `audit()`; `runRepair` chains audit →
+ * plan → (interaction) → apply.
+ *
+ * Sibling-relative imports per the project convention.
+ */
+import { readCalendar } from "../calendar.js";
+import { buildContentIndex } from "../content-index.js";
+import { resolveCalendarPath } from "../paths.js";
+import { readWorkflows } from "../review/pipeline.js";
+import missingFrontmatterId from "./rules/missing-frontmatter-id.js";
+import orphanFrontmatterId from "./rules/orphan-frontmatter-id.js";
+import duplicateId from "./rules/duplicate-id.js";
+import slugCollision from "./rules/slug-collision.js";
+import schemaRejected from "./rules/schema-rejected.js";
+import workflowStale from "./rules/workflow-stale.js";
+import calendarUuidMissing from "./rules/calendar-uuid-missing.js";
+import legacyTopLevelIdMigration from "./rules/legacy-top-level-id-migration.js";
+import { loadProjectRules, mergeRules } from "./project-rules.js";
+/**
+ * Registry of all rules in the order they run. The order matters: we
+ * detect calendar-uuid-missing first (to flush UUIDs), then run the
+ * frontmatter-id rules (which depend on UUIDs being persisted on
+ * disk to be useful in long-lived data).
+ *
+ * `legacy-top-level-id-migration` (Issue #38) runs BEFORE
+ * `missing-frontmatter-id` so that v0.7.0/v0.7.1-shaped files migrate
+ * to the namespaced form first; on the same run, the
+ * missing-frontmatter-id rule then sees the migrated files as bound
+ * (via `deskwork.id`) and doesn't re-report them.
+ */
+export const RULES = [
+    calendarUuidMissing,
+    legacyTopLevelIdMigration,
+    missingFrontmatterId,
+    orphanFrontmatterId,
+    duplicateId,
+    slugCollision,
+    workflowStale,
+    schemaRejected,
+];
+const RULE_BY_ID = new Map(RULES.map((r) => [r.id, r]));
+/**
+ * Resolve a CSV/comma-separated `--fix=` argument to rule ids.
+ *
+ * Returns the full list of built-in rule ids for `''` and `'all'`.
+ * Unknown built-in id strings are rejected (exit 2 in the CLI).
+ *
+ * Project rules registered via `<projectRoot>/.deskwork/doctor/*.ts`
+ * (Phase 23f) are selected by passing `'all'`; the runner picks them
+ * up from the merged rule list. Selecting an individual project rule
+ * by id via `--fix=<id>` is not yet supported — file an issue if the
+ * usage emerges.
+ */
+export function parseFixArgument(arg) {
+    const trimmed = arg.trim();
+    if (trimmed === '' || trimmed === 'all') {
+        return RULES.map((r) => r.id);
+    }
+    const ids = trimmed
+        .split(',')
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+    for (const id of ids) {
+        if (!RULE_BY_ID.has(id)) {
+            throw new Error(`Unknown doctor rule: "${id}". Known: ${RULES.map((r) => r.id).join(', ')}, all`);
+        }
+    }
+    return ids;
+}
+/** Build the per-site context once for a run. */
+function buildContext(opts, site, interaction) {
+    const calendarPath = resolveCalendarPath(opts.projectRoot, opts.config, site);
+    const calendar = readCalendar(calendarPath);
+    const index = buildContentIndex(opts.projectRoot, opts.config, site);
+    const allWorkflows = readWorkflows(opts.projectRoot, opts.config);
+    const workflows = allWorkflows.filter((w) => w.site === site);
+    return {
+        projectRoot: opts.projectRoot,
+        config: opts.config,
+        site,
+        calendar,
+        index,
+        workflows,
+        interaction,
+    };
+}
+function selectSites(opts) {
+    if (opts.site !== undefined) {
+        if (!(opts.site in opts.config.sites)) {
+            throw new Error(`Unknown site "${opts.site}". Configured sites: ${Object.keys(opts.config.sites).join(', ')}`);
+        }
+        return [opts.site];
+    }
+    return Object.keys(opts.config.sites);
+}
+function selectRules(available, ruleIds) {
+    if (ruleIds === undefined)
+        return [...available];
+    const byId = new Map(available.map((r) => [r.id, r]));
+    const out = [];
+    for (const id of ruleIds) {
+        const rule = byId.get(id);
+        if (!rule) {
+            throw new Error(`Unknown doctor rule: "${id}". Known: ${available.map((r) => r.id).join(', ')}, all`);
+        }
+        out.push(rule);
+    }
+    return out;
+}
+/**
+ * Phase 23f: build the effective rule set for an audit or repair run.
+ * Built-in rules merged with project rules from
+ * `<projectRoot>/.deskwork/doctor/*.ts`. Project rules with a basename
+ * matching a built-in's basename REPLACE that built-in (override
+ * semantics); new basenames append.
+ *
+ * Loaded once per run — not per finding — so disk i/o for
+ * `readdirSync` + N dynamic imports happens at the start of an audit.
+ */
+async function buildEffectiveRules(projectRoot) {
+    const projectRules = await loadProjectRules(projectRoot);
+    return mergeRules(RULES, projectRules);
+}
+/**
+ * Audit: collect findings without mutating the world. Returns a fully-
+ * built report with empty `repairs`. Suitable for pre-commit hooks
+ * that just want a non-zero exit code on any finding.
+ */
+export async function runAudit(opts, interaction) {
+    const sites = selectSites(opts);
+    const available = await buildEffectiveRules(opts.projectRoot);
+    const rules = selectRules(available, opts.ruleIds);
+    const findings = [];
+    for (const site of sites) {
+        const ctx = buildContext(opts, site, interaction);
+        for (const rule of rules) {
+            const out = await rule.audit(ctx);
+            findings.push(...out);
+        }
+    }
+    return { findings, repairs: [], sites };
+}
+/**
+ * Repair: run audit → plan → (consult interaction) → apply. Returns
+ * the audit findings AND the repair results so callers can render
+ * a single report covering both phases.
+ *
+ * For `prompt` plans the runner consults `interaction.pickChoice` to
+ * resolve to an apply payload; for `apply` plans it consults
+ * `interaction.confirmApply`. `report-only` plans never apply.
+ */
+export async function runRepair(opts, interaction) {
+    const sites = selectSites(opts);
+    const available = await buildEffectiveRules(opts.projectRoot);
+    const rules = selectRules(available, opts.ruleIds);
+    const findings = [];
+    const repairs = [];
+    for (const site of sites) {
+        const ctx = buildContext(opts, site, interaction);
+        for (const rule of rules) {
+            const ruleFindings = await rule.audit(ctx);
+            findings.push(...ruleFindings);
+            for (const finding of ruleFindings) {
+                const plan = await rule.plan(ctx, finding);
+                const result = await resolveAndApply(rule, ctx, plan, interaction);
+                repairs.push(result);
+            }
+        }
+    }
+    return { findings, repairs, sites };
+}
+/**
+ * Resolve a `prompt` plan via the interaction adapter and apply it.
+ * `apply` plans go through `confirmApply` first; `report-only` plans
+ * record a non-applied result.
+ */
+async function resolveAndApply(rule, ctx, plan, interaction) {
+    if (plan.kind === 'report-only') {
+        // `report-only` is the rule's signal that the finding can't be
+        // auto-repaired in this run. The granularity (prerequisite vs
+        // editorial-decision vs schema-rejected) is rule-specific; the
+        // rule sets `skipReason` via the report-only finding's details
+        // — see `reportOnlySkipReason()` below.
+        return {
+            finding: plan.finding,
+            applied: false,
+            message: plan.reason,
+            skipReason: reportOnlySkipReason(rule, plan.finding),
+        };
+    }
+    if (plan.kind === 'prompt') {
+        const choiceId = await interaction.pickChoice(plan);
+        if (choiceId === undefined) {
+            return {
+                finding: plan.finding,
+                applied: false,
+                message: 'skipped (operator declined or --yes mode encountered ambiguity)',
+                skipReason: 'ambiguous',
+            };
+        }
+        const choice = plan.choices.find((c) => c.id === choiceId);
+        if (!choice) {
+            return {
+                finding: plan.finding,
+                applied: false,
+                message: `unknown choice id: ${choiceId}`,
+                skipReason: 'apply-failed',
+            };
+        }
+        const applyPlan = {
+            kind: 'apply',
+            finding: plan.finding,
+            summary: choice.label,
+            payload: choice.payload,
+        };
+        return rule.apply(ctx, applyPlan);
+    }
+    // apply
+    const ok = await interaction.confirmApply(plan);
+    if (!ok) {
+        return {
+            finding: plan.finding,
+            applied: false,
+            message: 'skipped (operator declined)',
+            skipReason: 'operator-declined',
+        };
+    }
+    return rule.apply(ctx, plan);
+}
+/**
+ * Map a rule's `report-only` plan to a `SkipReason`. The mapping is by
+ * rule id because the existing rules don't carry an explicit skip-
+ * reason field on their `report-only` plans — adding one to every
+ * rule would be churn for a 1:1 relationship that's already implicit
+ * in the rule's purpose.
+ */
+function reportOnlySkipReason(rule, _finding) {
+    switch (rule.id) {
+        case 'missing-frontmatter-id':
+            // Always "no candidate file found" — the operator hasn't
+            // scaffolded the body file yet (run /deskwork:outline).
+            return 'prerequisite-missing';
+        case 'slug-collision':
+            // Editorial: which slug "owns" the public URL.
+            return 'editorial-decision';
+        case 'schema-rejected':
+            // Patch instructions only; nothing to apply automatically.
+            return 'schema-rejected';
+        default:
+            // Conservative fallback — treat unfamiliar rules as needing
+            // operator follow-up.
+            return 'editorial-decision';
+    }
+}
+/**
+ * Pre-built interaction: always confirm `apply` plans, skip `prompt`
+ * plans (no way to choose without a UI). Used by `--yes` mode.
+ *
+ * Exposed for the CLI command to construct.
+ */
+export const yesInteraction = {
+    async pickChoice(_plan) {
+        // `--yes` skips ambiguous cases by design — the workplan calls
+        // out missing-frontmatter-id with multiple candidates as the
+        // canonical example.
+        return undefined;
+    },
+    async confirmApply(_plan) {
+        return true;
+    },
+};
+/**
+ * Pre-built interaction: never apply anything. Used to dry-run a
+ * repair pipeline (prompt resolution + apply both no-op).
+ */
+export const declineInteraction = {
+    async pickChoice(_plan) {
+        return undefined;
+    },
+    async confirmApply(_plan) {
+        return false;
+    },
+};
+//# sourceMappingURL=runner.js.map

package/dist/doctor/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/doctor/runner.ts"],"names":[],"mappings":"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"}

package/dist/doctor/schema-patch.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Schema-patch instructions for host content collections that reject
+ * the deskwork frontmatter binding.
+ *
+ * Astro's content collection schemas are strict by default — a
+ * `z.object({ ... })` schema without `.passthrough()` (or an explicit
+ * entry for the deskwork namespace) refuses files whose frontmatter
+ * carries unknown keys. Phase 19 introduced the binding key in
+ * frontmatter; v0.7.2 (Issue #38) moved it under a `deskwork:`
+ * namespace so deskwork doesn't claim the global top-level keyspace.
+ *
+ * The `schema-rejected` doctor rule and the scaffolder both surface
+ * this text when an actual schema rejection is observed at write time.
+ */
+/**
+ * Return the operator-facing schema-patch instructions. The optional
+ * `collection` argument is reserved for future per-collection scoping
+ * (the current implementation returns the same text regardless).
+ */
+export declare function printSchemaPatchInstructions(collection?: string): string;
+//# sourceMappingURL=schema-patch.d.ts.map

package/dist/doctor/schema-patch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-patch.d.ts","sourceRoot":"","sources":["../../src/doctor/schema-patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAqEH;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,CAKxE"}

package/dist/doctor/schema-patch.js

@@ -0,0 +1,92 @@
+/**
+ * Schema-patch instructions for host content collections that reject
+ * the deskwork frontmatter binding.
+ *
+ * Astro's content collection schemas are strict by default — a
+ * `z.object({ ... })` schema without `.passthrough()` (or an explicit
+ * entry for the deskwork namespace) refuses files whose frontmatter
+ * carries unknown keys. Phase 19 introduced the binding key in
+ * frontmatter; v0.7.2 (Issue #38) moved it under a `deskwork:`
+ * namespace so deskwork doesn't claim the global top-level keyspace.
+ *
+ * The `schema-rejected` doctor rule and the scaffolder both surface
+ * this text when an actual schema rejection is observed at write time.
+ */
+const TEMPLATE = `# Host content schema must permit the \`deskwork\` namespace in frontmatter
+
+Deskwork binds calendar entries to markdown files via a UUID written
+under a \`deskwork:\` mapping in frontmatter (\`deskwork.id\`, UUID v4).
+For Astro projects with strict content collection schemas, this means
+the site's \`src/content/config.ts\` must allow the namespace to pass
+through.
+
+Note: top-level \`id:\` is NOT what to add — that field belongs to the
+operator's keyspace. Deskwork no longer claims it.
+
+Pick one of the following patches and apply it to your collection
+schema. Re-run the failing command after the patch.
+
+## Option 1 — explicit \`deskwork\` namespace (recommended)
+
+\`\`\`ts
+import { defineCollection, z } from 'astro:content';
+
+const blog = defineCollection({
+  type: 'content',
+  schema: z.object({
+    deskwork: z.object({ id: z.string().uuid() }).passthrough().optional(),
+    title: z.string(),
+    description: z.string().optional(),
+    // ...your existing fields
+  }),
+});
+
+export const collections = { blog };
+\`\`\`
+
+The \`deskwork\` block is optional so legacy files without it keep
+validating; deskwork sets it on every new scaffold and via
+\`deskwork doctor --fix=missing-frontmatter-id\` /
+\`--fix=legacy-top-level-id-migration\`. The inner \`.passthrough()\`
+leaves room for additional deskwork-scoped fields without forcing a
+schema change every release.
+
+## Option 2 — passthrough unknown keys at the top level
+
+\`\`\`ts
+const blog = defineCollection({
+  type: 'content',
+  schema: z.object({
+    title: z.string(),
+    // ...your existing fields
+  }).passthrough(),
+});
+\`\`\`
+
+Less precise but a smaller diff. Top-level \`.passthrough()\` accepts
+any extra keys — including the entire \`deskwork:\` namespace — without
+complaint. Use this when the schema is wide and you don't want to
+enumerate every deskwork-internal field.
+
+## Hugo / Jekyll / Eleventy / plain markdown
+
+These engines don't validate frontmatter against a schema; the
+\`deskwork:\` mapping already passes through untouched. No patch
+needed.
+
+After patching, re-run the original deskwork command. The
+\`schema-rejected\` rule's findings will clear on the next
+\`deskwork doctor\` audit.
+`;
+/**
+ * Return the operator-facing schema-patch instructions. The optional
+ * `collection` argument is reserved for future per-collection scoping
+ * (the current implementation returns the same text regardless).
+ */
+export function printSchemaPatchInstructions(collection) {
+    if (collection !== undefined && collection.length > 0) {
+        return `${TEMPLATE}\n(Reported for collection: ${collection})\n`;
+    }
+    return TEMPLATE;
+}
+//# sourceMappingURL=schema-patch.js.map

package/dist/doctor/schema-patch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema-patch.js","sourceRoot":"","sources":["../../src/doctor/schema-patch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,MAAM,QAAQ,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAiEhB,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,4BAA4B,CAAC,UAAmB;IAC9D,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtD,OAAO,GAAG,QAAQ,+BAA+B,UAAU,KAAK,CAAC;IACnE,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/doctor/types.d.ts

@@ -0,0 +1,185 @@
+/**
+ * Doctor — type definitions.
+ *
+ * `deskwork doctor` walks calendar + content tree + workflow store and
+ * produces structured reports. Each rule audits, optionally proposes a
+ * repair plan, and (with operator consent) applies the plan. The runner
+ * orchestrates rule execution; this module owns the data shapes.
+ *
+ * Sibling-relative imports per the project convention — `@/` doesn't
+ * resolve under tsx at runtime in this package's `src/`, only in tests.
+ */
+import type { DeskworkConfig } from '../config.ts';
+import type { EditorialCalendar } from '../types.ts';
+import type { ContentIndex } from '../content-index.ts';
+import type { DraftWorkflowItem } from '../review/types.ts';
+/** Severity for a finding — used only to color text-mode output. */
+export type FindingSeverity = 'error' | 'warning' | 'info';
+/**
+ * A single audit finding produced by a rule. The `details` map is rule-
+ * specific and meant for both human display and for `plan()` to reuse
+ * without re-walking the world.
+ */
+export interface Finding {
+    /** Stable rule id (matches `DoctorRule.id`). */
+    ruleId: string;
+    /** Site slug the finding belongs to (multi-site projects). */
+    site: string;
+    /** Severity bucket. */
+    severity: FindingSeverity;
+    /** Short human-readable label, suitable for one-line text output. */
+    message: string;
+    /** Rule-defined payload (entry id, file paths, etc.). */
+    details: Readonly<Record<string, unknown>>;
+}
+/**
+ * What a rule would do if applied. `kind` discriminates: rules either
+ * have a concrete repair (`apply`), need operator input (`prompt`), or
+ * can only be reported on (`report-only`).
+ *
+ * The runner uses `kind` to decide whether to ask the operator (in
+ * interactive mode) or skip with a clear message (in `--yes` mode).
+ */
+export type RepairPlan = {
+    kind: 'apply';
+    /** The finding this plan addresses. */
+    finding: Finding;
+    /** One-line summary the runner shows before applying. */
+    summary: string;
+    /** Rule-defined payload — passed verbatim to `apply()`. */
+    payload: Readonly<Record<string, unknown>>;
+} | {
+    kind: 'prompt';
+    finding: Finding;
+    /** Operator-facing question. */
+    question: string;
+    /** Possible answers — first is the default. */
+    choices: ReadonlyArray<RepairChoice>;
+} | {
+    kind: 'report-only';
+    finding: Finding;
+    /** Why no repair is offered (e.g. "operator must decide manually"). */
+    reason: string;
+};
+/** A single choice the operator can pick when a plan is `prompt`. */
+export interface RepairChoice {
+    /** Stable id — what the runner records when the operator picks this. */
+    id: string;
+    /** Operator-facing label. */
+    label: string;
+    /** Rule-defined payload to pass to `apply()` if chosen. */
+    payload: Readonly<Record<string, unknown>>;
+}
+/**
+ * Reason a `RepairResult` was not applied — the granularity matters for
+ * the exit-code logic in `--fix` mode (Issue #44, Phase 22).
+ *
+ *  - `prerequisite-missing`: the rule could not run because something
+ *    outside doctor's scope hasn't happened yet (e.g. the entry has no
+ *    body file because `outline` hasn't been called). Operator action
+ *    is required, but it's not a doctor failure — `--fix` should still
+ *    exit 0 once every applicable rule has been applied.
+ *  - `ambiguous`: the rule has multiple valid resolutions and refuses
+ *    to pick one without operator input. `--yes` mode skips these; the
+ *    operator has to re-run interactively. `--fix` exits non-zero.
+ *  - `editorial-decision`: the rule has a single resolution path but
+ *    that path requires a human judgment call (e.g. picking which slug
+ *    "owns" a public URL when two collide). `--fix` exits non-zero.
+ *  - `schema-rejected`: the host's content-collection schema refused
+ *    the write. `--fix` exits non-zero — the operator must patch the
+ *    schema before retrying.
+ *  - `operator-declined`: interactive mode and the operator said no.
+ *    `--fix` exits non-zero (the operator chose not to proceed).
+ *  - `apply-failed`: the rule's `apply()` raised on disk. `--fix` exits
+ *    non-zero — a real failure to track down.
+ *  - `no-action-needed`: the rule's plan resolved to a no-op (e.g. the
+ *    operator chose "leave as-is" in an orphan-id prompt). `--fix`
+ *    treats this as a successful skip.
+ */
+export type SkipReason = 'prerequisite-missing' | 'ambiguous' | 'editorial-decision' | 'schema-rejected' | 'operator-declined' | 'apply-failed' | 'no-action-needed';
+/** Outcome of applying a repair plan. */
+export interface RepairResult {
+    finding: Finding;
+    /** True when the repair landed on disk. */
+    applied: boolean;
+    /** Human-readable summary of what happened (or why it was skipped). */
+    message: string;
+    /**
+     * When `applied` is false, why. Used by the CLI command to decide
+     * whether the skip is a real follow-up (exit non-zero) or a no-op
+     * waiting on operator action outside doctor's scope (exit zero).
+     * Optional for backward compatibility — older rule implementations
+     * may not set it; the CLI defaults to "treat as a real follow-up".
+     */
+    skipReason?: SkipReason;
+    /** Optional rule-defined details — e.g. paths written. */
+    details?: Readonly<Record<string, unknown>>;
+}
+/**
+ * Operator interaction adapter. Rules don't depend on the runner's UI;
+ * they declare prompts in their `plan()` and the runner provides an
+ * interaction implementation (interactive readline, `--yes` auto-pick,
+ * or a test stub).
+ */
+export interface DoctorInteraction {
+    /**
+     * Resolve a `prompt` plan to a single choice id. Returns `undefined`
+     * to skip without applying — `--yes` mode does this for ambiguous
+     * cases; interactive mode does it when the operator declines.
+     */
+    pickChoice(plan: Extract<RepairPlan, {
+        kind: 'prompt';
+    }>): Promise<string | undefined>;
+    /**
+     * Confirm an `apply` plan. Returns `true` to apply, `false` to skip.
+     * `--yes` mode always returns `true`; interactive mode shows the
+     * summary and asks.
+     */
+    confirmApply(plan: Extract<RepairPlan, {
+        kind: 'apply';
+    }>): Promise<boolean>;
+}
+/**
+ * Carrier of every per-site input a rule needs. Rules receive this and
+ * return findings without re-walking the calendar or re-reading config.
+ */
+export interface DoctorContext {
+    projectRoot: string;
+    config: DeskworkConfig;
+    /** Site slug the runner is currently auditing. */
+    site: string;
+    /** Calendar for `site` — already parsed. */
+    calendar: EditorialCalendar;
+    /** Content index for `site` — already built. */
+    index: ContentIndex;
+    /** Workflows from the review store, scoped to `site`. */
+    workflows: ReadonlyArray<DraftWorkflowItem>;
+    /** Operator interaction — used by the runner during repair. */
+    interaction: DoctorInteraction;
+}
+/**
+ * The contract every rule implements.
+ *
+ * `audit` is a pure read of the world. `plan` decides what (if anything)
+ * the rule would do for a finding. `apply` executes the plan. The runner
+ * decides whether to chain these — audit-only mode stops after `audit`.
+ */
+export interface DoctorRule {
+    /** Stable identifier — appears in `--fix=<id>`. Use kebab-case. */
+    readonly id: string;
+    /** One-line operator-facing label. */
+    readonly label: string;
+    audit(ctx: DoctorContext): Promise<Finding[]>;
+    plan(ctx: DoctorContext, finding: Finding): Promise<RepairPlan>;
+    apply(ctx: DoctorContext, plan: RepairPlan): Promise<RepairResult>;
+}
+/** Aggregate report returned by the runner. */
+export interface DoctorReport {
+    /** Per-site findings, in rule iteration order. */
+    findings: Finding[];
+    /** Per-site repair results — empty in audit-only mode. */
+    repairs: RepairResult[];
+    /** Sites the runner exercised, in iteration order. */
+    sites: string[];
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/doctor/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/doctor/types.ts"],"names":[],"mappings":"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"}

package/dist/doctor/types.js

@@ -0,0 +1,13 @@
+/**
+ * Doctor — type definitions.
+ *
+ * `deskwork doctor` walks calendar + content tree + workflow store and
+ * produces structured reports. Each rule audits, optionally proposes a
+ * repair plan, and (with operator consent) applies the plan. The runner
+ * orchestrates rule execution; this module owns the data shapes.
+ *
+ * Sibling-relative imports per the project convention — `@/` doesn't
+ * resolve under tsx at runtime in this package's `src/`, only in tests.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/doctor/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/doctor/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG"}