chore: add version sync tooling and CI check

Author: marklearst

.github/workflows/deploy-docs.yml

@@ -38,6 +38,9 @@ jobs:
       - name: Install dependencies
         run: pnpm install --frozen-lockfile
 
+      - name: Check version sync
+        run: pnpm run version:check
+
       - name: Build site
         run: pnpm run docs:build
 

.gitignore

@@ -1,4 +1,5 @@
 node_modules
 .vercel
 .env*.local
-site/
+site/
+md_notes/

package.json

@@ -1,13 +1,15 @@
 {
-  "name": "variables-contract",
+  "name": "variable-design-standard",
   "private": true,
-  "version": "0.3.7",
+  "version": "0.4.0",
   "packageManager": "pnpm@10.26.0",
   "scripts": {
     "dev": "docmd dev",
     "build": "docmd build",
     "docs:dev": "docmd dev",
-    "docs:build": "docmd build"
+    "docs:build": "docmd build",
+    "version:sync": "node scripts/sync-version.js",
+    "version:check": "node scripts/check-version.js"
   },
   "devDependencies": {
     "@mgks/docmd": "^0.3.2"

scripts/check-version.js

@@ -0,0 +1,101 @@
+#!/usr/bin/env node
+
+/**
+ * Version Check Script
+ * 
+ * Validates that version numbers in documentation files match package.json version.
+ * Exits with error code 1 if mismatches are found (for CI).
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read version from package.json
+const pkgPath = path.join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const expectedVersion = pkg.version;
+
+if (!expectedVersion) {
+  console.error('Error: No version found in package.json');
+  process.exit(1);
+}
+
+console.log(`Checking version consistency (expected: ${expectedVersion})...\n`);
+
+// Define files and their patterns to check
+const files = [
+  {
+    path: path.join(__dirname, '..', 'README.md'),
+    patterns: [
+      {
+        regex: /\*\*Version:\*\* (\d+\.\d+\.\d+)/,
+        name: 'Version field'
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'index.md'),
+    patterns: [
+      {
+        regex: /\| \*\*Version\*\*    \| (\d+\.\d+\.\d+)/,
+        name: 'Version field'
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'faq.md'),
+    patterns: [
+      {
+        regex: /Version (\d+\.\d+\.\d+) is in Draft status/,
+        name: 'Production-ready answer'
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'meta', 'change-log.md'),
+    patterns: [
+      {
+        regex: /## Version (\d+\.\d+\.\d+) \(Current\)/,
+        name: 'Current version header'
+      }
+    ]
+  }
+];
+
+let hasMismatches = false;
+
+// Check each file
+files.forEach(({ path: filePath, patterns }) => {
+  if (!fs.existsSync(filePath)) {
+    console.warn(`Warning: File not found: ${filePath}`);
+    return;
+  }
+
+  const content = fs.readFileSync(filePath, 'utf8');
+  const relativePath = path.relative(process.cwd(), filePath);
+
+  patterns.forEach(({ regex, name }) => {
+    const match = content.match(regex);
+    if (match) {
+      const foundVersion = match[1];
+      if (foundVersion !== expectedVersion) {
+        console.error(`✗ ${relativePath} (${name}): Found ${foundVersion}, expected ${expectedVersion}`);
+        hasMismatches = true;
+      } else {
+        console.log(`✓ ${relativePath} (${name}): ${foundVersion}`);
+      }
+    } else {
+      console.warn(`⚠ ${relativePath} (${name}): Pattern not found`);
+    }
+  });
+});
+
+console.log('');
+
+if (hasMismatches) {
+  console.error('Version mismatch detected! Run "pnpm run version:sync" to fix.');
+  process.exit(1);
+} else {
+  console.log('All version numbers are in sync.');
+  process.exit(0);
+}

scripts/sync-version.js

@@ -0,0 +1,98 @@
+#!/usr/bin/env node
+
+/**
+ * Version Synchronization Script
+ * 
+ * Reads version from package.json and updates version numbers in:
+ * - README.md
+ * - docs/index.md
+ * - docs/faq.md
+ * - docs/meta/change-log.md
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Read version from package.json
+const pkgPath = path.join(__dirname, '..', 'package.json');
+const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
+const version = pkg.version;
+
+if (!version) {
+  console.error('Error: No version found in package.json');
+  process.exit(1);
+}
+
+console.log(`Syncing version ${version} across documentation files...\n`);
+
+// Define files and their patterns
+const files = [
+  {
+    path: path.join(__dirname, '..', 'README.md'),
+    patterns: [
+      {
+        regex: /\*\*Version:\*\* \d+\.\d+\.\d+/,
+        replacement: `**Version:** ${version}`
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'index.md'),
+    patterns: [
+      {
+        regex: /\| \*\*Version\*\*    \| \d+\.\d+\.\d+/,
+        replacement: `| **Version**    | ${version}`
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'faq.md'),
+    patterns: [
+      {
+        regex: /Version \d+\.\d+\.\d+ is in Draft status/,
+        replacement: `Version ${version} is in Draft status`
+      }
+    ]
+  },
+  {
+    path: path.join(__dirname, '..', 'docs', 'meta', 'change-log.md'),
+    patterns: [
+      {
+        regex: /## Version \d+\.\d+\.\d+ \(Current\)/,
+        replacement: `## Version ${version} (Current)`
+      }
+    ]
+  }
+];
+
+let updatedCount = 0;
+
+// Process each file
+files.forEach(({ path: filePath, patterns }) => {
+  if (!fs.existsSync(filePath)) {
+    console.warn(`Warning: File not found: ${filePath}`);
+    return;
+  }
+
+  let content = fs.readFileSync(filePath, 'utf8');
+  let fileUpdated = false;
+
+  patterns.forEach(({ regex, replacement }) => {
+    if (regex.test(content)) {
+      content = content.replace(regex, replacement);
+      fileUpdated = true;
+    }
+  });
+
+  if (fileUpdated) {
+    fs.writeFileSync(filePath, content, 'utf8');
+    const relativePath = path.relative(process.cwd(), filePath);
+    console.log(`✓ Updated ${relativePath}`);
+    updatedCount++;
+  } else {
+    const relativePath = path.relative(process.cwd(), filePath);
+    console.log(`- No changes needed in ${relativePath}`);
+  }
+});
+
+console.log(`\nSync complete. Updated ${updatedCount} file(s).`);