@opengsd/gsd-core 1.2.0 → 1.3.0

package/{get-shit-done → gsd-core}/bin/lib/state-document.cjs

@@ -1,26 +1,36 @@
-'use strict';
-
+"use strict";
 /**
  * STATE.md Document Module — pure transforms for STATE.md text.
  * This module does not read the filesystem and does not own persistence or locking.
+ *
+ * ADR-457 build-at-publish: the hand-written bin/lib/state-document.cjs collapsed
+ * to a TypeScript source of truth. Behaviour is preserved byte-for-behaviour
+ * from the prior hand-written .cjs; only types are added.
  */
-
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.KNOWN_STATUS_PATTERNS = exports.KNOWN_TEMPLATE_DEFAULTS = void 0;
+exports.stateExtractField = stateExtractField;
+exports.stateReplaceField = stateReplaceField;
+exports.stateReplaceFieldWithFallback = stateReplaceFieldWithFallback;
+exports.normalizeStateStatus = normalizeStateStatus;
+exports.computeProgressPercent = computeProgressPercent;
+exports.shouldPreserveExistingProgress = shouldPreserveExistingProgress;
+exports.normalizeProgressNumbers = normalizeProgressNumbers;
+exports.isStateTemplateDefault = isStateTemplateDefault;
+exports.stateReplaceFieldIfTemplate = stateReplaceFieldIfTemplate;
 // Internal helpers
 function escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
-
 function toFiniteNumber(value) {
     const number = Number(value);
     return Number.isFinite(number) ? number : null;
 }
-
 function existingProgressExceedsDerived(existingProgress, derivedProgress, key) {
     const existing = toFiniteNumber(existingProgress[key]);
     const derived = toFiniteNumber(derivedProgress[key]);
     return existing !== null && derived !== null && existing > derived;
 }
-
 function stateExtractField(content, fieldName) {
     const escaped = escapeRegex(fieldName);
     const boldPattern = new RegExp(`\\*\\*${escaped}:\\*\\*[ \\t]*(.+)`, 'i');
@@ -31,7 +41,6 @@ function stateExtractField(content, fieldName) {
     const plainMatch = content.match(plainPattern);
     return plainMatch ? plainMatch[1].trim() : null;
 }
-
 function stateReplaceField(content, fieldName, newValue) {
     const escaped = escapeRegex(fieldName);
     const boldPattern = new RegExp(`(\\*\\*${escaped}:\\*\\*\\s*)(.*)`, 'i');
@@ -44,7 +53,6 @@ function stateReplaceField(content, fieldName, newValue) {
     }
     return null;
 }
-
 function stateReplaceFieldWithFallback(content, primary, fallback, value) {
     let result = stateReplaceField(content, primary, value);
     if (result)
@@ -56,7 +64,6 @@ function stateReplaceFieldWithFallback(content, primary, fallback, value) {
     }
     return content;
 }
-
 function normalizeStateStatus(status, pausedAt) {
     let normalizedStatus = status || 'unknown';
     const statusLower = (status || '').toLowerCase();
@@ -83,17 +90,17 @@ function normalizeStateStatus(status, pausedAt) {
     }
     return normalizedStatus;
 }
-
 function computeProgressPercent(completedPlans, totalPlans, completedPhases, totalPhases) {
     const hasPlanData = totalPlans !== null && totalPlans > 0 && completedPlans !== null;
     const hasPhaseData = totalPhases !== null && totalPhases > 0 && completedPhases !== null;
     if (!hasPlanData && !hasPhaseData)
         return null;
-    const planFraction = hasPlanData ? completedPlans / totalPlans : 1;
-    const phaseFraction = hasPhaseData ? completedPhases / totalPhases : 1;
+    // Use nullish coalescing to avoid non-null assertion operators (flow narrowing
+    // cannot track through intermediate boolean variables).
+    const planFraction = hasPlanData ? (completedPlans ?? 0) / (totalPlans ?? 1) : 1;
+    const phaseFraction = hasPhaseData ? (completedPhases ?? 0) / (totalPhases ?? 1) : 1;
     return Math.min(100, Math.round(Math.min(planFraction, phaseFraction) * 100));
 }
-
 function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
     if (!existingProgress || typeof existingProgress !== 'object')
         return false;
@@ -106,7 +113,6 @@ function shouldPreserveExistingProgress(existingProgress, derivedProgress) {
         existingProgressExceedsDerived(existing, derived, 'total_plans') ||
         existingProgressExceedsDerived(existing, derived, 'completed_plans'));
 }
-
 function normalizeProgressNumbers(progress) {
     if (!progress || typeof progress !== 'object')
         return progress;
@@ -118,7 +124,6 @@ function normalizeProgressNumbers(progress) {
     }
     return normalized;
 }
-
 /**
  * KNOWN_TEMPLATE_DEFAULTS — per-field table of string values that were written
  * by a GSD handler (not by an executor / human).  A value that appears in this
@@ -133,47 +138,45 @@ function normalizeProgressNumbers(progress) {
  * (KNOWN_STATUS_PATTERNS) that matches handler-generated values whose exact
  * text is variable (e.g. "Executing Phase 5").
  */
-const KNOWN_TEMPLATE_DEFAULTS = {
-  'Resume File': ['None'],
-  'Status': [
-    'Ready to execute',
-    'Phase complete — ready for verification',
-    'Ready to plan',
-    'Defining requirements',
-    'Planning complete',
-    // Legacy / abbreviated handler values present in older STATE.md files
-    'Executing',
-    'In progress',
-    'Planning',
-    'Verifying',
-    'Completed',
-    'Done',
-    'Active',
-    'Paused',
-    'unknown',
-  ],
-  // Last Activity is a date field; ISO date-only strings (YYYY-MM-DD) are the
-  // handler-generated form.  We detect them by shape rather than an exhaustive
-  // list because the date changes every day.
-  // NOTE: entries here are matched by isStateTemplateDefault using the date regex
-  // in addition to exact string equality.
-  'Last Activity': [],
-  'Last activity': [],
+exports.KNOWN_TEMPLATE_DEFAULTS = {
+    'Resume File': ['None'],
+    'Status': [
+        'Ready to execute',
+        'Phase complete — ready for verification',
+        'Ready to plan',
+        'Defining requirements',
+        'Planning complete',
+        // Legacy / abbreviated handler values present in older STATE.md files
+        'Executing',
+        'In progress',
+        'Planning',
+        'Verifying',
+        'Completed',
+        'Done',
+        'Active',
+        'Paused',
+        'unknown',
+    ],
+    // Last Activity is a date field; ISO date-only strings (YYYY-MM-DD) are the
+    // handler-generated form.  We detect them by shape rather than an exhaustive
+    // list because the date changes every day.
+    // NOTE: entries here are matched by isStateTemplateDefault using the date regex
+    // in addition to exact string equality.
+    'Last Activity': [],
+    'Last activity': [],
 };
-
 /**
  * Regex patterns that match handler-generated Status values whose text includes
  * a variable component (e.g. phase number).  Checked after the KNOWN_TEMPLATE_DEFAULTS
  * exact-match list in isStateTemplateDefault.
  */
-const KNOWN_STATUS_PATTERNS = [
-  /^Executing Phase\s+\d+/i,
-  /^Planning Phase\s+\d+/i,
-  /^Phase\s+\d+\s+complete/i,
-  /^Verifying Phase\s+\d+/i,
-  /^Phase complete/i,
+exports.KNOWN_STATUS_PATTERNS = [
+    /^Executing Phase\s+\d+/i,
+    /^Planning Phase\s+\d+/i,
+    /^Phase\s+\d+\s+complete/i,
+    /^Verifying Phase\s+\d+/i,
+    /^Phase complete/i,
 ];
-
 /**
  * Returns true when the given value is a known template default for the field,
  * meaning a GSD handler wrote it and a subsequent handler may replace it.
@@ -183,44 +186,42 @@ const KNOWN_STATUS_PATTERNS = [
  *   (b) it matches the ISO date-only shape (YYYY-MM-DD) for Last Activity fields
  *       (handlers always write bare dates; executors write narrative prose).
  *
- * @param {string} field  - Canonical field name (case-sensitive key lookup attempted
- *                          first, then case-insensitive fallback).
- * @param {string} value  - The current value extracted from STATE.md.
- * @returns {boolean}
+ * @param field  - Canonical field name (case-sensitive key lookup attempted
+ *                  first, then case-insensitive fallback).
+ * @param value  - The current value extracted from STATE.md.
+ * @returns boolean
  */
 function isStateTemplateDefault(field, value) {
-    if (value === null || value === undefined) return true; // absent → initial write
-    const v = String(value).trim();
-    if (v === '') return true; // blank → treat as absent
-
+    if (value === null || value === undefined)
+        return true; // absent → initial write
+    // Narrow to string: callers pass string values extracted from STATE.md.
+    const v = (typeof value === 'string' ? value : `${value}`).trim();
+    if (v === '')
+        return true; // blank → treat as absent
     // Look up the defaults list, trying exact key first then case-insensitive.
-    let defaults = KNOWN_TEMPLATE_DEFAULTS[field];
+    let defaults = exports.KNOWN_TEMPLATE_DEFAULTS[field];
     if (!defaults) {
         const fieldLower = field.toLowerCase();
-        const matchKey = Object.keys(KNOWN_TEMPLATE_DEFAULTS).find(k => k.toLowerCase() === fieldLower);
-        defaults = matchKey ? KNOWN_TEMPLATE_DEFAULTS[matchKey] : null;
+        const matchKey = Object.keys(exports.KNOWN_TEMPLATE_DEFAULTS).find(k => k.toLowerCase() === fieldLower);
+        defaults = matchKey ? exports.KNOWN_TEMPLATE_DEFAULTS[matchKey] : null;
     }
-
     if (defaults && defaults.some(d => d.toLowerCase() === v.toLowerCase())) {
         return true;
     }
-
     const fieldLower = field.toLowerCase();
-
     // Status: also check pattern list for variable handler-generated values
     // (e.g. "Executing Phase 5", "Planning Phase 3").
     if (fieldLower === 'status') {
-        if (KNOWN_STATUS_PATTERNS.some(p => p.test(v))) return true;
+        if (exports.KNOWN_STATUS_PATTERNS.some(p => p.test(v)))
+            return true;
     }
-
     // Last Activity / Last activity: bare ISO date (YYYY-MM-DD) is handler-generated.
     if (fieldLower === 'last activity') {
-        if (/^\d{4}-\d{2}-\d{2}$/.test(v)) return true;
+        if (/^\d{4}-\d{2}-\d{2}$/.test(v))
+            return true;
     }
-
     return false;
 }
-
 /**
  * Replaces a field in STATE.md content only when the existing value is a known
  * template default (or the field is absent).  If the existing value is
@@ -228,20 +229,17 @@ function isStateTemplateDefault(field, value) {
  *
  * When `newValue` is null or undefined the function is a no-op (returns content).
  *
- * @param {string} content       - Full STATE.md text.
- * @param {string} field         - Field name as it appears in STATE.md.
- * @param {string[]} knownDefaults - The defaults list to check against (typically
- *                                   KNOWN_TEMPLATE_DEFAULTS[field]).
- * @param {string} newValue      - Value to write when replacement is permitted.
- * @returns {string}             - Updated content (or original if skipped).
+ * @param content       - Full STATE.md text.
+ * @param field         - Field name as it appears in STATE.md.
+ * @param knownDefaults - The defaults list to check against (typically
+ *                         KNOWN_TEMPLATE_DEFAULTS[field]).
+ * @param newValue      - Value to write when replacement is permitted.
+ * @returns Updated content (or original if skipped).
  */
 function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
-    if (newValue === null || newValue === undefined) return content;
+    if (newValue === null || newValue === undefined)
+        return content;
     const existing = stateExtractField(content, field);
-    // Build a temporary KNOWN_TEMPLATE_DEFAULTS-compatible lookup so we can reuse
-    // the isStateTemplateDefault logic for the provided knownDefaults array.
-    const tempField = '__tmp__';
-    const tempDefaults = { [tempField]: knownDefaults || [] };
     // Inline check: absent/blank → always write; in list → write; else → skip.
     if (existing === null || existing === undefined || existing.trim() === '') {
         return stateReplaceField(content, field, newValue) || content;
@@ -250,7 +248,7 @@ function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
     const inList = (knownDefaults || []).some(d => d.toLowerCase() === v.toLowerCase());
     const fieldLower = field.toLowerCase();
     // Special-case: Status pattern list for variable handler-generated values.
-    const matchesStatusPattern = (fieldLower === 'status') && KNOWN_STATUS_PATTERNS.some(p => p.test(v));
+    const matchesStatusPattern = (fieldLower === 'status') && exports.KNOWN_STATUS_PATTERNS.some(p => p.test(v));
     // Special-case: Last Activity bare ISO date (YYYY-MM-DD) is handler-generated.
     const isDateShape = (fieldLower === 'last activity') && /^\d{4}-\d{2}-\d{2}$/.test(v);
     if (inList || matchesStatusPattern || isDateShape) {
@@ -259,5 +257,3 @@ function stateReplaceFieldIfTemplate(content, field, knownDefaults, newValue) {
     // Executor-authored — preserve.
     return content;
 }
-
-module.exports = { stateExtractField, stateReplaceField, stateReplaceFieldWithFallback, normalizeStateStatus, computeProgressPercent, shouldPreserveExistingProgress, normalizeProgressNumbers, KNOWN_TEMPLATE_DEFAULTS, KNOWN_STATUS_PATTERNS, isStateTemplateDefault, stateReplaceFieldIfTemplate };