instar 0.28.35 → 0.28.42

package/scripts/check-upgrade-guide.js

@@ -31,6 +31,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import {
+  REQUIRED_SECTIONS,
+  NEXT_TEMPLATE,
+  validateGuideContent,
+  parseBumpType,
+} from './upgrade-guide-validator.mjs';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const ROOT = path.resolve(__dirname, '..');
@@ -42,125 +48,13 @@ const nextPath = path.join(ROOT, 'upgrades', 'NEXT.md');
 const guideExists = fs.existsSync(guidePath);
 const nextExists = fs.existsSync(nextPath);
 
-// Required sections for a well-formed guide
-const REQUIRED_SECTIONS = [
-  '## What Changed',
-  '## What to Tell Your User',
-  '## Summary of New Capabilities',
-];
-
-const MIN_LENGTH = 200;
-
-// Template for a fresh NEXT.md after finalization
-const NEXT_TEMPLATE = `# Upgrade Guide — vNEXT
-
-<!-- bump: patch -->
-<!-- Valid values: patch, minor, major -->
-<!-- patch = bug fixes, refactors, test additions, doc updates -->
-<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
-<!-- major = breaking changes to existing APIs or behavior -->
-
-## What Changed
-
-<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
-<!-- Write this for the AGENT — they need to understand the system deeply. -->
-
-## What to Tell Your User
-
-<!-- Write talking points the agent should relay to their user. -->
-<!-- This should be warm, conversational, user-facing — not a changelog. -->
-<!-- Focus on what THEY can now do, not internal plumbing. -->
-<!--                                                                    -->
-<!-- PROHIBITED in this section (will fail validation):                 -->
-<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
-<!--   Inline code backtick references like silentReject: false        -->
-<!--   Fenced code blocks                                              -->
-<!--   Instructions to edit files or run commands                      -->
-<!--                                                                    -->
-<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
-<!-- The agent relays this to their user — keep it human.              -->
-
-- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
-
-## Summary of New Capabilities
-
-| Capability | How to Use |
-|-----------|-----------|
-| [Capability] | [Endpoint, command, or "automatic"] |
-`;
-
 /**
- * Validate a guide file and return any issues found.
+ * Validate a guide file. Thin wrapper around validateGuideContent that handles
+ * the file read.
  */
 function validateGuide(filePath) {
   const content = fs.readFileSync(filePath, 'utf-8');
-  const issues = [];
-
-  for (const section of REQUIRED_SECTIONS) {
-    if (!content.includes(section)) {
-      issues.push(`missing "${section}" section`);
-    }
-  }
-
-  if (content.length < MIN_LENGTH) {
-    issues.push(`guide is too short (${content.length} chars, minimum ${MIN_LENGTH}) — probably incomplete`);
-  }
-
-  // Check for template placeholders that were never filled in
-  if (content.includes('<!-- Describe what changed')) {
-    issues.push(`"What Changed" section still contains template placeholder — fill it in`);
-  }
-  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
-    issues.push(`"What to Tell Your User" section still contains template placeholder — fill it in`);
-  }
-  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
-    issues.push(`"Summary of New Capabilities" section still contains template placeholder — fill it in`);
-  }
-
-  // Validate "What to Tell Your User" section for technical leakage.
-  // This section is relayed verbatim to users — it must be conversational, not a config reference.
-  const userSectionMatch = content.match(/## What to Tell Your User([\s\S]*?)(?:##|$)/);
-  if (userSectionMatch) {
-    const userSection = userSectionMatch[1];
-
-    // Detect camelCase config key references (e.g. silentReject, maxRetries, telegramNotify)
-    const camelCaseConfigKey = /\b[a-z]+[A-Z][a-zA-Z]+\s*(?::|=)/.test(userSection);
-    if (camelCaseConfigKey) {
-      issues.push(
-        `"What to Tell Your User" contains a camelCase config key reference (e.g. "silentReject: false"). ` +
-        `Users should never be told to edit config directly. ` +
-        `Rephrase conversationally: "I can turn that on for you" not "set silentReject: false".`
-      );
-    }
-
-    // Detect inline code blocks — config syntax, CLI commands, file paths
-    const hasInlineCode = /`[^`]+`/.test(userSection);
-    if (hasInlineCode) {
-      issues.push(
-        `"What to Tell Your User" contains inline code (\`...\`). ` +
-        `Remove code formatting — user-facing language should be plain and conversational.`
-      );
-    }
-
-    // Detect fenced code blocks
-    if (/```/.test(userSection)) {
-      issues.push(
-        `"What to Tell Your User" contains a fenced code block. ` +
-        `This section is for user-facing narrative — move technical examples to "What Changed".`
-      );
-    }
-  }
-
-  return issues;
-}
-
-/**
- * Parse the declared bump type from a guide's <!-- bump: TYPE --> comment.
- * Returns 'patch' | 'minor' | 'major' | null.
- */
-function parseBumpType(content) {
-  const match = /<!--\s*bump:\s*(patch|minor|major)\s*-->/.exec(content);
-  return match ? match[1] : null;
+  return validateGuideContent(content);
 }
 
 /**

package/scripts/collect-metrics.py

@@ -123,76 +123,37 @@ def fetch_github_metrics():
     return metrics
 
 
-def compute_trends(current_snapshot, state_dir):
-    """Compare current metrics to historical baseline using rolling median.
-
-    Returns dict with:
-    - alerts: list of significant changes detected
-    - baseline_npm_day: 7-day rolling median (from prior days only)
-    - comparison: raw comparison data
-    """
+def compute_trends(state_dir):
+    """Compare current metrics to previous snapshots for trend detection."""
     history_file = Path(state_dir) / "telemetry.jsonl"
     if not history_file.exists():
-        return {"alerts": [], "baseline_npm_day": None}
-
-    # Get today's date
-    today_str = current_snapshot.get("timestamp", "").split("T")[0]
+        return None
 
-    # Read all entries and dedupe by date, keeping one per day
+    # Read last 7 entries
     lines = history_file.read_text().strip().split("\n")
-    daily_values = {}  # date -> npm_last_day
-
-    for line in lines:
+    recent = []
+    for line in lines[-7:]:
         try:
-            snap = json.loads(line)
-            snap_date = snap.get("timestamp", "").split("T")[0]
-            npm_day = snap.get("npm", {}).get("last_day")
-            if npm_day is not None:
-                # Keep the latest snapshot for each date
-                daily_values[snap_date] = npm_day
+            recent.append(json.loads(line))
         except json.JSONDecodeError:
             continue
 
-    # Get values from prior days only (exclude today)
-    prior_days = {k: v for k, v in daily_values.items() if k < today_str}
-    if len(prior_days) < 1:
-        return {"alerts": [], "baseline_npm_day": None}
-
-    # Calculate median from last 7 prior days
-    sorted_values = sorted(prior_days.values())
-    if len(sorted_values) > 7:
-        sorted_values = sorted_values[-7:]  # Last 7 days
-
-    median_idx = len(sorted_values) // 2
-    baseline = sorted_values[median_idx]
-
-    # Check for significant changes
-    current_npm_day = current_snapshot.get("npm", {}).get("last_day")
-    alerts = []
-
-    if current_npm_day is not None and baseline > 0:
-        # Alert if >20% deviation from baseline
-        pct_change = ((current_npm_day - baseline) / baseline) * 100
-        if abs(pct_change) > 20:
-            direction = "📈" if pct_change > 0 else "📉"
-            alerts.append({
-                "type": "npm_anomaly",
-                "message": f"{direction} npm downloads {abs(pct_change):.0f}% from baseline ({current_npm_day} vs {baseline} median)",
-                "current": current_npm_day,
-                "baseline": baseline,
-                "pct_change": pct_change
-            })
-
-    return {
-        "alerts": alerts,
-        "baseline_npm_day": baseline,
-        "comparison": {
-            "current": current_npm_day,
-            "baseline": baseline,
-            "history_count": len(sorted_values),
-            "prior_days": len(prior_days)
-        }
-    }
+    if len(recent) < 2:
+        return None
+
+    prev = recent[-2] if len(recent) >= 2 else None
+    week_ago = recent[0] if len(recent) >= 7 else recent[0]
+
+    trends = {}
+    if prev:
+        prev_npm = prev.get("npm", {}).get("last_day")
+        trends["npm_day_prev"] = prev_npm
+
+    if week_ago:
+        week_npm = week_ago.get("npm", {}).get("last_week")
+        trends["npm_week_prev"] = week_npm
+
+    return trends
 
 
 def save_snapshot(snapshot, state_dir):
@@ -211,49 +172,6 @@ def save_snapshot(snapshot, state_dir):
         json.dump(snapshot, f, indent=2)
 
 
-def send_telegram_notification(alerts, snapshot):
-    """Send Telegram notification if significant alerts exist."""
-    if not alerts:
-        return
-
-    # Build message
-    ts = snapshot.get("timestamp", "").split("T")[0]  # Date only
-    lines = [f"🔔 Instar Metrics Alert ({ts})"]
-
-    for alert in alerts:
-        lines.append(f"\n{alert['message']}")
-
-    message = "\n".join(lines)
-
-    # Try multiple locations for the telegram-reply script
-    possible_paths = [
-        os.path.expanduser("~/.dawn-server/scripts/telegram-reply.py"),
-        os.path.expanduser("~/.claude/scripts/telegram-reply.py"),
-        "./.claude/scripts/telegram-reply.py",
-    ]
-
-    script_path = None
-    for path in possible_paths:
-        if os.path.exists(path):
-            script_path = path
-            break
-
-    if script_path:
-        # Topic ID 2278 is the instar metrics topic
-        cmd = [
-            "python3", script_path, "2278", message
-        ]
-        try:
-            result = subprocess.run(cmd, capture_output=True, text=True, timeout=10)
-            print(f"[Telegram] Sent alert notification to topic 2278")
-            if result.returncode != 0 and result.stderr:
-                print(f"[Telegram] Warning: {result.stderr}")
-        except Exception as e:
-            print(f"[Telegram] Failed to send notification: {e}")
-    else:
-        print(f"[Telegram] Script not found in any expected location (skipping notification)")
-
-
 def format_summary(snapshot):
     """Format a human-readable summary."""
     lines = []
@@ -311,30 +229,17 @@ def main():
     # Collect
     snapshot["npm"] = fetch_npm_downloads()
     snapshot["github"] = fetch_github_metrics()
+    snapshot["trends"] = compute_trends(args.state_dir)
 
     # Save
     save_snapshot(snapshot, args.state_dir)
 
-    # Analyze trends and detect anomalies
-    trends_analysis = compute_trends(snapshot, args.state_dir)
-    snapshot["trends"] = trends_analysis
-
-    # Send Telegram notification if alerts detected
-    alerts = trends_analysis.get("alerts", [])
-    if alerts:
-        send_telegram_notification(alerts, snapshot)
-
     # Output
     if not args.quiet:
         if args.json:
             print(json.dumps(snapshot, indent=2))
         else:
-            summary = format_summary(snapshot)
-            if alerts:
-                summary += "\n\n⚠️ Alerts:\n"
-                for alert in alerts:
-                    summary += f"  • {alert['message']}\n"
-            print(summary)
+            print(format_summary(snapshot))
 
     return 0
 

package/scripts/upgrade-guide-validator.mjs

@@ -0,0 +1,221 @@
+// Pure validation logic for upgrade guides — no filesystem side effects.
+// The CLI entry point (check-upgrade-guide.js) wraps this with I/O.
+// Extracted for unit testability.
+
+export const REQUIRED_SECTIONS = [
+  '## What Changed',
+  '## What to Tell Your User',
+  '## Summary of New Capabilities',
+];
+
+export const MIN_LENGTH = 200;
+
+// Keywords that indicate the guide is claiming to fix a bug. When any of these
+// appear inside "## What Changed", the Evidence section becomes mandatory.
+// Limited to "What Changed" (not the whole doc) to reduce false positives from
+// marketing language in "What to Tell Your User".
+const FIX_PATTERNS = [
+  /\bfix(es|ed|ing)?\b/i,
+  /\bbug(fix)?\b/i,
+  /\bregression\b/i,
+  /\bresolves?\b/i,
+  /\bresolved\b/i,
+  /\bcrashes?\b/i,
+  /\bcrashed\b/i,
+  /\bcrashing\b/i,
+  /\bbroken\b/i,
+  /\bstall(s|ed|ing)?\b/i,
+];
+
+export const NEXT_TEMPLATE = `# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- Valid values: patch, minor, major -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+<!-- minor = new features, new APIs, new capabilities (backwards-compatible) -->
+<!-- major = breaking changes to existing APIs or behavior -->
+
+## What Changed
+
+<!-- Describe what changed technically. What new features, APIs, behavioral changes? -->
+<!-- Write this for the AGENT — they need to understand the system deeply. -->
+
+## What to Tell Your User
+
+<!-- Write talking points the agent should relay to their user. -->
+<!-- This should be warm, conversational, user-facing — not a changelog. -->
+<!-- Focus on what THEY can now do, not internal plumbing. -->
+<!--                                                                    -->
+<!-- PROHIBITED in this section (will fail validation):                 -->
+<!--   camelCase config keys: silentReject, maxRetries, telegramNotify -->
+<!--   Inline code backtick references like silentReject: false        -->
+<!--   Fenced code blocks                                              -->
+<!--   Instructions to edit files or run commands                      -->
+<!--                                                                    -->
+<!-- CORRECT style: "I can turn that on for you" not "set X to false"  -->
+<!-- The agent relays this to their user — keep it human.              -->
+
+- **[Feature name]**: "[Brief, friendly description of what this means for the user]"
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| [Capability] | [Endpoint, command, or "automatic"] |
+
+## Evidence
+
+<!-- REQUIRED if this release claims to fix a bug. -->
+<!-- Unit tests passing is NOT evidence. Provide ONE of: -->
+<!--   (a) Reproduction steps + observed before/after on a live system. -->
+<!--       Include log excerpts, observed command output, or behavior -->
+<!--       description. Make it specific enough that a future reader can -->
+<!--       re-run it and see the same thing. -->
+<!--   (b) "Not reproducible in dev — [concrete reason]" if the failure -->
+<!--       mode truly can't be exercised locally (race conditions, -->
+<!--       event-driven paths requiring external signals, etc). -->
+<!--                                                                 -->
+<!-- If this release doesn't claim a bug fix (pure feature / refactor), -->
+<!-- leave this section blank or delete it — it's only enforced when -->
+<!-- "What Changed" describes a fix. -->
+
+[Describe reproduction + verified fix, OR "Not reproducible in dev — [concrete reason]"]
+`;
+
+/**
+ * Extract the content of a markdown H2 section by title. Returns the section
+ * body (between `## Title` and the next `## ` or end of file), or null if the
+ * section isn't present.
+ */
+export function extractSection(content, title) {
+  const pattern = new RegExp(`## ${title.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')}([\\s\\S]*?)(?:\\n## |$)`);
+  const m = content.match(pattern);
+  return m ? m[1] : null;
+}
+
+/**
+ * Does the guide claim to fix a bug? Scans "## What Changed" for fix-indicating
+ * keywords. Returns true when any pattern matches.
+ */
+export function claimsFix(content) {
+  const section = extractSection(content, 'What Changed');
+  if (!section) return false;
+  return FIX_PATTERNS.some(p => p.test(section));
+}
+
+/**
+ * Validate the Evidence section when a fix is claimed. Returns an array of
+ * issue strings (empty when valid).
+ */
+export function evidenceIssues(content) {
+  const issues = [];
+  const section = extractSection(content, 'Evidence');
+  if (section === null) {
+    issues.push(
+      '"What Changed" claims a bug fix, but the guide has no "## Evidence" section. ' +
+      'Add one with reproduction + observed before/after, or "Not reproducible in dev — [reason]". ' +
+      'Unit tests passing is not evidence.'
+    );
+    return issues;
+  }
+  // Strip HTML comments and trim
+  const stripped = section.replace(/<!--[\s\S]*?-->/g, '').trim();
+  if (!stripped) {
+    issues.push(
+      '"## Evidence" section is empty (only template comments). ' +
+      'Fill it in with reproduction + verified fix, or "Not reproducible in dev — [reason]".'
+    );
+    return issues;
+  }
+  // Reject obvious placeholder text
+  if (
+    /\[Describe reproduction/i.test(stripped) ||
+    /\[evidence goes here\]/i.test(stripped) ||
+    /TODO\b/.test(stripped) ||
+    /FIXME\b/.test(stripped)
+  ) {
+    issues.push(
+      '"## Evidence" section still contains placeholder text. ' +
+      'Replace it with a real reproduction + verification, or explicit "Not reproducible in dev — [reason]".'
+    );
+    return issues;
+  }
+  // Require at least 80 chars of real content — any less and it can't describe
+  // a reproduction meaningfully.
+  if (stripped.length < 80) {
+    issues.push(
+      `"## Evidence" section is too short (${stripped.length} chars). ` +
+      'Include concrete reproduction + observed before/after, or "Not reproducible in dev" with a concrete reason.'
+    );
+  }
+  return issues;
+}
+
+/**
+ * Full structural validation of a guide's content. Returns issue strings.
+ */
+export function validateGuideContent(content) {
+  const issues = [];
+
+  for (const section of REQUIRED_SECTIONS) {
+    if (!content.includes(section)) {
+      issues.push(`missing "${section}" section`);
+    }
+  }
+
+  if (content.length < MIN_LENGTH) {
+    issues.push(`guide is too short (${content.length} chars, minimum ${MIN_LENGTH}) — probably incomplete`);
+  }
+
+  // Template placeholders that were never filled in
+  if (content.includes('<!-- Describe what changed')) {
+    issues.push('"What Changed" section still contains template placeholder — fill it in');
+  }
+  if (content.includes('[Feature name]') || content.includes('[Brief, friendly description')) {
+    issues.push('"What to Tell Your User" section still contains template placeholder — fill it in');
+  }
+  if (content.includes('[Capability]') && content.includes('[Endpoint, command')) {
+    issues.push('"Summary of New Capabilities" section still contains template placeholder — fill it in');
+  }
+
+  // "What to Tell Your User" technical-leakage checks
+  const userSection = extractSection(content, 'What to Tell Your User');
+  if (userSection) {
+    const camelCaseConfigKey = /\b[a-z]+[A-Z][a-zA-Z]+\s*(?::|=)/.test(userSection);
+    if (camelCaseConfigKey) {
+      issues.push(
+        '"What to Tell Your User" contains a camelCase config key reference (e.g. "silentReject: false"). ' +
+        'Users should never be told to edit config directly. ' +
+        'Rephrase conversationally: "I can turn that on for you" not "set silentReject: false".'
+      );
+    }
+    if (/`[^`]+`/.test(userSection)) {
+      issues.push(
+        '"What to Tell Your User" contains inline code (`...`). ' +
+        'Remove code formatting — user-facing language should be plain and conversational.'
+      );
+    }
+    if (/```/.test(userSection)) {
+      issues.push(
+        '"What to Tell Your User" contains a fenced code block. ' +
+        'This section is for user-facing narrative — move technical examples to "What Changed".'
+      );
+    }
+  }
+
+  // Evidence bar — when the guide claims a fix, require an Evidence section.
+  if (claimsFix(content)) {
+    issues.push(...evidenceIssues(content));
+  }
+
+  return issues;
+}
+
+/**
+ * Parse the declared bump type from a guide's <!-- bump: TYPE --> comment.
+ * Returns 'patch' | 'minor' | 'major' | null.
+ */
+export function parseBumpType(content) {
+  const match = /<!--\s*bump:\s*(patch|minor|major)\s*-->/.exec(content);
+  return match ? match[1] : null;
+}