dotmd-cli 0.14.2 → 0.14.4

package/README.md

@@ -430,27 +430,78 @@ When `dotmd init` runs in a directory with existing `.md` files, it scans them a
 
 ## Configuration
 
-Create `dotmd.config.mjs` at your project root (or run `dotmd init`):
+Create `dotmd.config.mjs` at your project root (or run `dotmd init`).
+
+### Rich status definitions (recommended)
+
+Define each status as an object that co-locates all behavioral properties. Adding a new status is one line in one place — no need to update separate `lifecycle`, `staleDays`, `context`, or `taxonomy` sections.
+
+```js
+export const root = 'docs/plans';
+export const archiveDir = 'archived';
+
+export const types = {
+  plan: {
+    statuses: {
+      'active':   { context: 'expanded', staleDays: 14, requiresModule: true },
+      'planned':  { context: 'listed', staleDays: 30, requiresModule: true },
+      'blocked':  { context: 'listed', staleDays: 30, skipStale: true },
+      'archived': { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+    },
+  },
+};
+```
+
+**Status properties:**
+
+| Property | Type | Default | Effect |
+|---|---|---|---|
+| `context` | `'expanded'` \| `'listed'` \| `'counted'` | `'counted'` | Display mode in `dotmd context` |
+| `staleDays` | `number` \| `null` | `null` | Days before doc is stale (`null` = never) |
+| `requiresModule` | `boolean` | `false` | Require `module` in frontmatter |
+| `terminal` | `boolean` | `false` | Skip `current_state`/`next_step` warnings |
+| `archive` | `boolean` | `false` | Auto-move to `archiveDir` on transition |
+| `skipStale` | `boolean` | `false` | Exempt from stale checks |
+| `skipWarnings` | `boolean` | `false` | Exempt from validation warnings |
+
+Object key order determines display order. The config resolver derives `statuses.order`, `lifecycle.*`, `taxonomy.moduleRequiredFor`, and `context.*` from these definitions. Explicit global sections still win when provided.
+
+### Array form (also supported)
+
+The traditional array form remains fully backwards compatible:
 
 ```js
-export const root = 'docs/plans';         // string or array of paths
-export const archiveDir = 'archived';     // subdirectory for archived docs
+export const types = {
+  plan: {
+    statuses: ['active', 'planned', 'blocked', 'archived'],
+    context: { expanded: ['active'], listed: ['planned', 'blocked'], counted: ['archived'] },
+    staleDays: { active: 14, planned: 30, blocked: 30 },
+  },
+};
 
+// When using array form, define behavior in separate sections:
 export const statuses = {
-  order: ['draft', 'active', 'approved', 'superseded', 'archived'],
-  staleDays: { draft: 7, active: 14, approved: 30 },
+  order: ['active', 'planned', 'blocked', 'archived'],
+  staleDays: { active: 14, planned: 30, blocked: 30 },
 };
 
 export const lifecycle = {
-  archiveStatuses: ['archived'],          // auto-move to archiveDir
+  archiveStatuses: ['archived'],
   skipStaleFor: ['archived'],
   skipWarningsFor: ['archived'],
-  terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],
+  terminalStatuses: ['archived'],
+};
+
+export const taxonomy = {
+  moduleRequiredFor: ['active', 'planned', 'blocked'],
 };
+```
 
+### Other config
+
+```js
 export const taxonomy = {
   surfaces: ['web', 'ios', 'backend', 'api', 'platform'],
-  moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],
 };
 
 export const referenceFields = {
@@ -465,7 +516,7 @@ export const index = {
 };
 ```
 
-All exports are optional. Additional options: `types`, `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
+All exports are optional. Additional options: `context`, `display`, `presets`, `templates`, `excludeDirs`, `notion`. See [`dotmd.config.example.mjs`](dotmd.config.example.mjs) for the full reference.
 
 Config discovery walks up from cwd looking for `dotmd.config.mjs` or `.dotmd.config.mjs`.
 

package/dotmd.config.example.mjs

@@ -13,27 +13,58 @@ export const archiveDir = 'archived';
 // Directories to skip when scanning
 export const excludeDirs = ['evidence'];
 
-// Document types — each type has its own status vocabulary and context layout
+// Document types — each type has its own status vocabulary and context layout.
 // Defaults: plan, doc, research. Override to customize statuses per type.
+//
+// Statuses can be defined as an array (names only) or as an object (rich form).
+// The object form co-locates all behavioral properties with each status,
+// eliminating the need for separate lifecycle, staleDays, context, and taxonomy sections.
+
+// ─── Rich status definitions (recommended) ──────────────────────────────────
+// Each status is an object with optional properties:
+//   context:        'expanded' | 'listed' | 'counted' (default: 'counted')
+//   staleDays:      number | null — stale threshold (default: null = never stale)
+//   requiresModule: boolean — require `module` frontmatter (default: false)
+//   terminal:       boolean — skip current_state/next_step warnings (default: false)
+//   archive:        boolean — auto-move to archiveDir on transition (default: false)
+//   skipStale:      boolean — exempt from stale checks (default: false)
+//   skipWarnings:   boolean — exempt from validation warnings (default: false)
+//
 // export const types = {
 //   plan: {
-//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
-//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
-//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
+//     statuses: {
+//       'in-session': { context: 'expanded', staleDays: 1, requiresModule: true },
+//       'active':     { context: 'expanded', staleDays: 14, requiresModule: true },
+//       'planned':    { context: 'listed', staleDays: 30, requiresModule: true },
+//       'blocked':    { context: 'listed', staleDays: 30, requiresModule: true, skipStale: true },
+//       'done':       { context: 'counted', terminal: true, skipStale: true, skipWarnings: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
 //   doc: {
-//     statuses: ['draft', 'active', 'review', 'reference', 'deprecated', 'archived'],
-//     context: { expanded: ['active'], listed: ['draft', 'review'], counted: ['reference', 'deprecated', 'archived'] },
-//     staleDays: { draft: 30, active: 14, review: 14 },
+//     statuses: {
+//       'draft':      { context: 'listed', staleDays: 30 },
+//       'active':     { context: 'expanded', staleDays: 14 },
+//       'review':     { context: 'listed', staleDays: 14 },
+//       'reference':  { context: 'counted', skipStale: true },
+//       'deprecated': { context: 'counted', terminal: true, skipStale: true },
+//       'archived':   { context: 'counted', archive: true, terminal: true, skipStale: true, skipWarnings: true },
+//     },
 //   },
-//   research: {
-//     statuses: ['active', 'reference', 'archived'],
-//     context: { expanded: ['active'], listed: [], counted: ['reference', 'archived'] },
-//     staleDays: { active: 30 },
+// };
+
+// ─── Array form (also supported) ────────────────────────────────────────────
+// When using array form, define behavior in separate statuses/lifecycle/taxonomy sections.
+// export const types = {
+//   plan: {
+//     statuses: ['in-session', 'active', 'planned', 'blocked', 'done', 'archived'],
+//     context: { expanded: ['in-session', 'active'], listed: ['planned', 'blocked'], counted: ['done', 'archived'] },
+//     staleDays: { 'in-session': 1, active: 14, planned: 30, blocked: 30 },
 //   },
 // };
 
 // Status workflow — fallback for docs without a type field. Order determines display grouping.
+// When using rich status definitions, statuses.order and staleDays are derived automatically.
 export const statuses = {
   order: ['active', 'ready', 'planned', 'research', 'blocked', 'reference', 'archived'],
   // Additional statuses valid only in specific roots (merged with order)
@@ -52,7 +83,8 @@ export const statuses = {
   },
 };
 
-// Lifecycle behavior — which statuses trigger special handling
+// Lifecycle behavior — which statuses trigger special handling.
+// When using rich status definitions, these are derived from per-status flags.
 export const lifecycle = {
   archiveStatuses: ['archived'],      // auto-move to archiveDir on transition
   skipStaleFor: ['archived'],         // skip staleness checks
@@ -60,7 +92,8 @@ export const lifecycle = {
   terminalStatuses: ['archived', 'deprecated', 'reference', 'done'],  // skip current_state/next_step warnings, exclude from stats scope
 };
 
-// Taxonomy validation — set fields to null to skip validation
+// Taxonomy validation — set fields to null to skip validation.
+// moduleRequiredFor is derived from requiresModule when using rich status definitions.
 export const taxonomy = {
   surfaces: ['web', 'ios', 'android', 'mobile', 'full-stack', 'frontend', 'backend', 'api', 'docs', 'ops', 'platform', 'infra', 'design'],
   moduleRequiredFor: ['active', 'ready', 'planned', 'blocked'],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dotmd-cli",
-  "version": "0.14.2",
+  "version": "0.14.4",
   "description": "CLI for managing markdown documents with YAML frontmatter — index, query, validate, graph, export, Notion sync, AI summaries.",
   "type": "module",
   "license": "MIT",

package/src/config.mjs

@@ -97,6 +97,118 @@ const DEFAULTS = {
   },
 };
 
+const VALID_CONTEXT_VALUES = new Set(['expanded', 'listed', 'counted']);
+
+/**
+ * Normalize rich status definitions (object form) into array form + derived config.
+ * When types.<type>.statuses is an object like:
+ *   { 'active': { context: 'expanded', staleDays: 14, requiresModule: true }, ... }
+ * this extracts all behavioral properties, converts statuses to an array for
+ * downstream processing, and returns derived values for lifecycle/taxonomy/context.
+ *
+ * Returns null if no types use object-form statuses.
+ */
+function normalizeRichStatuses(config, userConfig) {
+  const derived = {
+    archiveStatuses: [],
+    skipStaleFor: [],
+    skipWarningsFor: [],
+    terminalStatuses: [],
+    moduleRequiredFor: [],
+    staleDays: {},
+    statusOrder: [],
+    context: { expanded: [], listed: [], counted: [] },
+  };
+
+  let hasRich = false;
+
+  for (const [typeName, typeDef] of Object.entries(config.types ?? {})) {
+    if (!typeDef.statuses || Array.isArray(typeDef.statuses)) continue;
+    if (typeof typeDef.statuses !== 'object') continue;
+
+    hasRich = true;
+    const statusNames = [];
+    const typeContext = { expanded: [], listed: [], counted: [] };
+    const typeStaleDays = {};
+
+    for (const [name, props] of Object.entries(typeDef.statuses)) {
+      const p = props ?? {};
+      statusNames.push(name);
+
+      const ctx = p.context ?? 'counted';
+      if (typeContext[ctx]) typeContext[ctx].push(name);
+      // Global context: only add if not already in any bucket (first type wins)
+      const inGlobal = derived.context.expanded.includes(name) ||
+        derived.context.listed.includes(name) || derived.context.counted.includes(name);
+      if (!inGlobal && derived.context[ctx]) derived.context[ctx].push(name);
+
+      if (p.staleDays != null) {
+        typeStaleDays[name] = p.staleDays;
+        derived.staleDays[name] = p.staleDays;
+      }
+
+      if (p.archive && !derived.archiveStatuses.includes(name)) derived.archiveStatuses.push(name);
+      if (p.skipStale && !derived.skipStaleFor.includes(name)) derived.skipStaleFor.push(name);
+      if (p.skipWarnings && !derived.skipWarningsFor.includes(name)) derived.skipWarningsFor.push(name);
+      if (p.terminal && !derived.terminalStatuses.includes(name)) derived.terminalStatuses.push(name);
+      if (p.requiresModule && !derived.moduleRequiredFor.includes(name)) derived.moduleRequiredFor.push(name);
+
+      if (!derived.statusOrder.includes(name)) derived.statusOrder.push(name);
+    }
+
+    // Convert to array form for downstream pipeline
+    typeDef.statuses = statusNames;
+
+    // Derive type-level context/staleDays unless user explicitly provided them
+    const userTypeDef = userConfig.types?.[typeName];
+    if (!userTypeDef?.context) typeDef.context = typeContext;
+    if (!userTypeDef?.staleDays) typeDef.staleDays = typeStaleDays;
+  }
+
+  if (!hasRich) return null;
+  return derived;
+}
+
+/**
+ * Apply derived values from rich status definitions into the merged config.
+ * Explicit user config always wins over derived values.
+ */
+function applyDerivedConfig(config, userConfig, derived) {
+  // statuses.order — derive from types if user didn't explicitly set
+  if (!userConfig.statuses?.order && derived.statusOrder.length) {
+    config.statuses.order = derived.statusOrder;
+  }
+
+  // statuses.staleDays — merge derived as base, user overrides
+  if (!userConfig.statuses?.staleDays && Object.keys(derived.staleDays).length) {
+    config.statuses.staleDays = derived.staleDays;
+  }
+
+  // lifecycle — each sub-key independently
+  if (!userConfig.lifecycle?.archiveStatuses && derived.archiveStatuses.length) {
+    config.lifecycle.archiveStatuses = derived.archiveStatuses;
+  }
+  if (!userConfig.lifecycle?.skipStaleFor && derived.skipStaleFor.length) {
+    config.lifecycle.skipStaleFor = derived.skipStaleFor;
+  }
+  if (!userConfig.lifecycle?.skipWarningsFor && derived.skipWarningsFor.length) {
+    config.lifecycle.skipWarningsFor = derived.skipWarningsFor;
+  }
+  if (!userConfig.lifecycle?.terminalStatuses && derived.terminalStatuses.length) {
+    config.lifecycle.terminalStatuses = derived.terminalStatuses;
+  }
+
+  // taxonomy.moduleRequiredFor
+  if (!userConfig.taxonomy?.moduleRequiredFor && derived.moduleRequiredFor.length) {
+    config.taxonomy.moduleRequiredFor = derived.moduleRequiredFor;
+  }
+
+  // context — only the status-related arrays, not recentDays/recentLimit/etc
+  if (!userConfig.context?.expanded) config.context.expanded = derived.context.expanded;
+  if (!userConfig.context?.listed) config.context.listed = derived.context.listed;
+  if (!userConfig.context?.counted) config.context.counted = derived.context.counted;
+}
+
 function findConfigFile(startDir) {
   let dir = path.resolve(startDir);
   const root = path.parse(dir).root;
@@ -218,6 +330,10 @@ export async function resolveConfig(cwd, explicitConfigPath) {
 
   const config = deepMerge(DEFAULTS, userConfig);
 
+  // Normalize rich status definitions (object form → array + derived config)
+  const derived = normalizeRichStatuses(config, userConfig);
+  if (derived) applyDerivedConfig(config, userConfig, derived);
+
   const rootPaths = Array.isArray(config.root) ? config.root : [config.root];
   const docsRoots = rootPaths.map(r => path.resolve(configDir, r));
   const docsRoot = docsRoots[0]; // primary root for backwards compat