- add a plan for implementing @SInCE tag replacement

- add update-since-tags script
- add npm script for running the update-since-tags script
- add chalk as a dependency

Author: jasonbahl

.github/workflows/UPDATE_SINCE_TAGS.md

@@ -0,0 +1,72 @@
+# @since Tag Update Implementation Plan
+
+## Overview
+
+This document outlines the plan for implementing automated `@since` tag updates during the release process. The system will update placeholder version tags (such as `@since todo`, `@since next-version`, and `@since tbd`) with the actual version number during releases.
+
+## Implementation Checklist
+
+### 1. Package.json Updates
+- [ ] Add `chalk` to devDependencies
+- [ ] Add a new npm script for running the update-since-tags.js (e.g., `since-tags:update`)
+
+### 2. Script Enhancements (update-since-tags.js)
+- [ ] Add better console output formatting using chalk
+- [ ] Enhance logging to provide detailed information about updated files
+- [ ] Add functionality to generate a summary of updates for release notes
+- [ ] Add documentation for supported placeholders (`todo`, `next-version`, `tbd`)
+- [ ] Add error handling for file operations
+- [ ] Add validation for version number input
+
+### 3. Release Management Workflow Updates
+- [ ] Add new step in release-management.yml after version bump
+- [ ] Integrate since-tag updates into the workflow
+- [ ] Add logging output to release notes
+- [ ] Handle potential errors gracefully
+- [ ] Ensure changes are committed with version bump
+
+### 4. Changeset Integration
+- [ ] Modify generate-changeset.yml to detect files with @since placeholders
+- [ ] Add @since placeholder information to changeset content
+- [ ] Update release PR template to include @since placeholder information
+- [ ] Ensure this information flows through to final release notes
+
+### 5. Documentation Updates
+- [ ] Update SUMMARY.md with new functionality
+- [ ] Update main README.md with @since tag information
+- [ ] Update workflow documentation
+- [ ] Add examples of using @since placeholders
+- [ ] Document supported file types (PHP only for now)
+
+### 6. Testing
+- [ ] Test script locally with various scenarios
+- [ ] Test workflow with actual PR and release
+- [ ] Test error scenarios
+- [ ] Test with multiple @since tags in single file
+- [ ] Test with no @since tags present
+
+## Supported Placeholders
+
+The following placeholders will be automatically updated during release:
+- `@since todo`
+- `@since next-version`
+- `@since tbd`
+
+## File Types
+
+Currently, the system only scans PHP files for @since placeholders. This may be expanded in future versions.
+
+## Notes
+
+- The script currently works as-is, so we won't refactor the module system (ES modules vs CommonJS) at this time
+- We'll focus on PHP files only for the initial implementation
+- Changes should be made incrementally to avoid disrupting existing workflows
+- Each change should be tested thoroughly before moving to the next item
+
+## Future Considerations
+
+- Support for additional file types (js, jsx, tsx, etc.)
+- Support for additional placeholder formats
+- Integration with other documentation tools
+- Automated testing for the script
+- Performance optimization for large codebases 

package.json

@@ -14,7 +14,8 @@
     "build": "node scripts/build.js",
     "release:prepare": "npm run version:bump && npm run changelogs:update",
     "test": "echo \"Error: no test specified\" && exit 1",
-    "upgrade-notice:update": "node scripts/update-upgrade-notice.js"
+    "upgrade-notice:update": "node scripts/update-upgrade-notice.js",
+    "since-tags:update": "node scripts/update-since-tags.js"
   },
   "repository": {
     "type": "git",
@@ -35,6 +36,7 @@
   "homepage": "https://github.com/jasonbahl/automation-tests#readme",
   "devDependencies": {
     "archiver": "^5.3.1",
+    "chalk": "^5.3.0",
     "dotenv": "^16.4.7",
     "fs-extra": "^11.1.1",
     "glob": "^10.3.3",

scripts/update-since-tags.js

@@ -0,0 +1,173 @@
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+
+/**
+ * Find files containing @since todo tags
+ */
+async function findSinceTodoFiles(pattern = 'src/**/*.php') {
+    try {
+        console.log('\nDebug: Current working directory:', process.cwd());
+        console.log('Debug: Looking for files matching pattern:', pattern);
+
+        // Use glob.sync instead of async glob for simpler handling
+        const files = glob.sync(pattern, {
+            ignore: [
+                'node_modules/**',
+                'vendor/**',
+                'phpcs/**',
+                '.github/**',
+                '.wordpress-org/**',
+                'bin/**',
+                'build/**',
+                'docker/**',
+                'img/**',
+                'phpstan/**',
+                'docs/**'
+            ],
+            dot: false, // Ignore dot directories
+            cwd: process.cwd()
+        });
+
+        console.log('Debug: Found files:', files);
+
+        return files || [];
+    } catch (error) {
+        console.error('Error finding files:', error);
+        return [];
+    }
+}
+
+/**
+ * Get all @since placeholders from a file
+ */
+function getSincePlaceholders(content) {
+    // Update regex to match all our valid placeholders
+    const regex = /@since\s+(todo|next-version|tbd)|@next-version/gi;
+    const matches = content.match(regex);
+    return matches ? matches.length : 0;
+}
+
+/**
+ * Update @since placeholders in a file
+ */
+function updateSinceTags(filePath, version) {
+    try {
+        let content = fs.readFileSync(filePath, 'utf8');
+        const originalContent = content;
+
+        // Replace placeholders with the actual version
+        content = content.replace(
+            /@since\s+(todo|tbd|next-version)|@next-version/gi,
+            `@since ${version}`  // Use the provided version instead of 'next-version'
+        );
+
+        // Only write if content changed
+        if (content !== originalContent) {
+            fs.writeFileSync(filePath, content);
+            return true;
+        }
+
+        return false;
+    } catch (error) {
+        throw new Error(`Error updating ${filePath}: ${error.message}`);
+    }
+}
+
+/**
+ * Update all @since todo tags in the project
+ */
+async function updateAllSinceTags(version, pattern = '**/*.php') {
+    const results = {
+        updated: [],
+        errors: []
+    };
+
+    try {
+        const files = await findSinceTodoFiles(pattern);
+        console.log('Debug: Processing files:', files);
+
+        for (const file of files) {
+            try {
+                const content = fs.readFileSync(file, 'utf8');
+                const count = getSincePlaceholders(content);
+                console.log(`Debug: File ${file} has ${count} @since tags`);
+
+                if (count > 0) {
+                    const updated = updateSinceTags(file, version);
+                    if (updated) {
+                        results.updated.push(file);
+                    }
+                }
+            } catch (error) {
+                results.errors.push({ file, error: error.message });
+            }
+        }
+
+        return results;
+    } catch (error) {
+        throw new Error(`Error updating @since tags: ${error.message}`);
+    }
+}
+
+/**
+ * CLI command to update @since tags
+ */
+async function main() {
+    const { default: chalk } = await import('chalk');
+
+    try {
+        const version = process.argv[2];
+        if (!version) {
+            throw new Error('Version argument is required');
+        }
+
+        console.log(chalk.blue('\nUpdating @since todo tags...'));
+        const results = await updateAllSinceTags(version);
+
+        if (results.updated.length > 0) {
+            console.log(chalk.green('\n✓ Updated files:'));
+            results.updated.forEach(file => {
+                console.log(chalk.gray(`  - ${path.relative(process.cwd(), file)}`));
+            });
+        } else {
+            console.log(chalk.yellow('\nNo @since todo tags found'));
+        }
+
+        if (results.errors.length > 0) {
+            console.log(chalk.red('\n❌ Errors:'));
+            results.errors.forEach(({ file, error }) => {
+                console.log(chalk.gray(`  - ${path.relative(process.cwd(), file)}: ${error}`));
+            });
+            process.exit(1);
+        }
+
+        process.exit(0);
+    } catch (error) {
+        console.error(chalk.red('\n❌ Error:'), error.message);
+        process.exit(1);
+    }
+}
+
+// Run if called directly
+if (require.main === module) {
+    main();
+}
+
+/**
+ * Get count of @since todo tags in content
+ */
+function getSinceTodoTags(content) {
+    // Update to match all non-standard placeholders
+    const regex = /@since\s+(todo|tbd)|@next-version/gi;
+    const matches = content.match(regex);
+    return matches ? matches.length : 0;
+}
+
+module.exports = {
+    findSinceTodoFiles,
+    getSincePlaceholders,
+    updateSinceTags,
+    updateAllSinceTags,
+    getSinceTodoTags
+};