Resolve 52 security vulnerabilities + add AI agent maintenance guide (#37) (#38)

* Initial plan

* Initial analysis of security vulnerabilities



* Update dependencies to fix all security vulnerabilities



* Add comprehensive AI agent guide for security vulnerability fixes



---------

Co-authored-by: Copilot <198982749+Copilot@users.noreply.github.com>

Author: andibeuge

AI_AGENT_README.md

@@ -0,0 +1,298 @@
+# AI Agent Guide: Security Vulnerability Fixes
+
+This document provides a strategic guide for AI agents tasked with fixing security vulnerabilities in the parcellab-utilities repository.
+
+## 📋 Task Overview
+
+**Goal**: Address all security vulnerabilities reported by Dependabot/npm audit while maintaining code functionality and test coverage.
+
+**Repository**: parcelLab/parcellab-utilities  
+**Tech Stack**: Node.js, Babel, Mocha, ESLint  
+**Package Manager**: npm
+
+## 🎯 Strategy & Approach
+
+### Phase 1: Discovery & Analysis (5-10 minutes)
+
+1. **Understand the repository structure**
+   ```bash
+   cd /home/runner/work/parcellab-utilities/parcellab-utilities
+   ls -la
+   cat package.json
+   ```
+
+2. **Establish baseline**
+   ```bash
+   npm install  # Install current dependencies
+   npm audit    # Identify all vulnerabilities
+   npm test     # Verify tests pass before changes
+   npm run build # Verify build works
+   npm run lint  # Verify linter passes
+   ```
+
+3. **Analyze vulnerability report**
+   - Count total vulnerabilities by severity (critical, high, moderate, low)
+   - Identify vulnerable packages (direct vs transitive dependencies)
+   - Note which vulnerabilities can be auto-fixed
+
+### Phase 2: Automated Fixes (2-5 minutes)
+
+1. **Apply automatic fixes first**
+   ```bash
+   npm audit fix --dry-run  # Preview what will be fixed
+   npm audit fix            # Apply automatic fixes
+   npm audit                # Check remaining vulnerabilities
+   ```
+
+2. **Verify automatic fixes didn't break anything**
+   ```bash
+   npm test
+   npm run build
+   npm run lint
+   ```
+
+### Phase 3: Manual Dependency Updates (10-20 minutes)
+
+**Key Insight**: Most vulnerabilities in this repo come from transitive dependencies through semantic-release packages.
+
+1. **Identify the root cause packages**
+   - Check `npm ls <vulnerable-package>` to understand dependency tree
+   - Focus on updating parent packages rather than trying to update transitive deps directly
+
+2. **Strategic update order** (learned from experience):
+   
+   a. **@semantic-release packages** - These are the main culprits:
+      ```bash
+      npm install --save-dev @semantic-release/git@latest
+      ```
+      This single update typically cascades to:
+      - `semantic-release` (the core)
+      - `@semantic-release/npm`
+      - `@semantic-release/github`
+      - All `@octokit/*` packages
+      - Many other transitive dependencies
+
+   b. **Babel packages** - Usually auto-fixed, but if needed:
+      ```bash
+      npm update @babel/core @babel/cli @babel/preset-env @babel/register
+      ```
+
+   c. **Test framework packages**:
+      ```bash
+      npm update mocha nyc
+      ```
+
+   d. **Other dev dependencies** as needed
+
+3. **Verify after each major update**
+   ```bash
+   npm audit
+   npm test
+   ```
+
+### Phase 4: Verification (5-10 minutes)
+
+1. **Run full test suite**
+   ```bash
+   npm test
+   ```
+   - Should see: "103 passing"
+   - Coverage should remain stable (~90% statements)
+
+2. **Build the project**
+   ```bash
+   npm run build
+   ```
+   - Should compile successfully
+   - Check that `lib/` directory contains updated files
+   - Minor changes in generated code (e.g., Babel helpers) are expected and normal
+
+3. **Run linter**
+   ```bash
+   npm run lint
+   ```
+   - Should pass with no errors
+
+4. **Final security audit**
+   ```bash
+   npm audit
+   ```
+   - Target: "found 0 vulnerabilities"
+
+5. **Code quality checks**
+   - Run code review tool
+   - Run CodeQL security scanner
+   - Both should report no issues
+
+### Phase 5: Documentation & Commit (5 minutes)
+
+1. **Create comprehensive commit message**
+   - List specific packages updated
+   - Note vulnerabilities fixed (count by severity)
+   - Mention verification steps completed
+
+2. **Report progress regularly**
+   - Use report_progress after establishing baseline
+   - Use report_progress after successful fixes
+   - Use report_progress for final completion
+
+## 💡 Key Learnings & Tips
+
+### Critical Success Factors
+
+1. **Update parent dependencies, not transitive ones**
+   - ❌ Don't try: `npm install marked@latest` (if it's bundled in npm package)
+   - ✅ Do try: `npm install @semantic-release/git@latest` (which updates semantic-release)
+
+2. **Bundled dependencies cannot be directly fixed**
+   - npm package bundles many dependencies
+   - These will show warnings like "is a bundled dependency... cannot be fixed automatically"
+   - Solution: Update the parent package or wait for upstream fix
+
+3. **Single strategic update can fix many vulnerabilities**
+   - Updating `@semantic-release/git` from v9 to v10 resolved 47 vulnerabilities
+   - Always check the dependency tree before making multiple updates
+
+4. **Test early and often**
+   - Run tests after each significant update
+   - Don't wait until the end to discover breaking changes
+
+5. **Generated code changes are normal**
+   - Babel may generate slightly different code with newer versions
+   - As long as tests pass, these changes are safe
+   - Example: `lib/geo.js` had minor helper function changes
+
+### Common Pitfalls to Avoid
+
+❌ **Don't skip the baseline**
+- Always run tests/build/lint BEFORE making changes
+- You need to know what failures are pre-existing vs. caused by your changes
+
+❌ **Don't update all packages blindly**
+- Start with strategic packages (semantic-release family)
+- Verify after each major update
+- Only update what's necessary
+
+❌ **Don't ignore test failures**
+- All 103 tests must pass
+- If tests fail, investigate before proceeding
+- May need to revert and try a different approach
+
+❌ **Don't forget to rebuild**
+- After updating Babel, always run `npm run build`
+- Commit the updated `lib/` directory
+- This is part of the package's release process
+
+❌ **Don't leave security checks for the end**
+- Run code review and CodeQL before finalizing
+- Address any findings immediately
+
+## 🔍 Troubleshooting Guide
+
+### Problem: Vulnerabilities remain after npm audit fix
+
+**Solution**: Check if vulnerabilities are in bundled dependencies (npm package). Update the parent package instead.
+
+### Problem: Tests fail after dependency update
+
+**Solution**: 
+1. Check error messages carefully
+2. Revert the problematic update: `git checkout package.json package-lock.json`
+3. Try updating packages one at a time
+4. Look for breaking changes in package changelogs
+
+### Problem: Build fails with new Babel version
+
+**Solution**:
+1. Check `.babelrc` configuration
+2. Ensure all Babel packages are compatible versions
+3. Update all Babel packages together: `npm update @babel/core @babel/cli @babel/preset-env @babel/register`
+
+### Problem: npm audit shows 0 vulnerabilities but Dependabot still shows alerts
+
+**Solution**: 
+- Dependabot may be checking different things
+- Check the Dependabot URL: https://github.com/parcelLab/parcellab-utilities/security/dependabot
+- May need to wait for Dependabot to re-scan after your changes are merged
+
+## 📊 Success Metrics
+
+- ✅ npm audit reports: "found 0 vulnerabilities"
+- ✅ All 103 tests passing
+- ✅ Build completes successfully
+- ✅ Linter passes with no errors
+- ✅ Code review finds no issues
+- ✅ CodeQL reports 0 security alerts
+- ✅ Test coverage remains stable (~90%)
+
+## ⏱️ Estimated Time
+
+- **Simple case** (npm audit fix resolves everything): 15-20 minutes
+- **Complex case** (manual dependency updates needed): 30-45 minutes
+- **This case** (strategic @semantic-release update): 25 minutes
+
+## 📝 Checklist Template
+
+Use this checklist when reporting progress:
+
+```markdown
+- [ ] Install dependencies and establish baseline
+- [ ] Run npm audit to identify vulnerabilities
+- [ ] Apply npm audit fix for automatic fixes
+- [ ] Identify root cause packages for remaining vulnerabilities
+- [ ] Update strategic parent packages (e.g., @semantic-release/git)
+- [ ] Verify all tests pass (103 tests)
+- [ ] Verify build succeeds
+- [ ] Verify linter passes
+- [ ] Confirm npm audit shows 0 vulnerabilities
+- [ ] Run code review
+- [ ] Run CodeQL security scan
+- [ ] Document changes and commit
+```
+
+## 🔄 Maintenance Notes
+
+**For future updates:**
+- This guide reflects the state as of February 2026
+- Dependency update strategies may evolve
+- Always check npm/Node.js best practices for the current year
+- Review this guide periodically and update based on new learnings
+
+## 📚 Useful Commands Reference
+
+```bash
+# Audit commands
+npm audit                          # Show all vulnerabilities
+npm audit --json                   # JSON format for parsing
+npm audit fix                      # Auto-fix what's possible
+npm audit fix --force             # Force updates (use with caution)
+
+# Dependency inspection
+npm ls <package-name>              # Show dependency tree
+npm outdated                       # Show outdated packages
+npm view <package-name> versions   # Show available versions
+
+# Update commands
+npm update <package-name>          # Update to wanted version
+npm install <package>@latest       # Update to latest version
+npm install --save-dev <package>   # Update dev dependency
+
+# Verification commands
+npm test                           # Run tests
+npm run build                      # Build the project
+npm run lint                       # Run linter
+git diff package.json              # See what changed
+git status                         # Check working tree status
+```
+
+## 🎓 Learning Resources
+
+- [npm audit documentation](https://docs.npmjs.com/cli/v8/commands/npm-audit)
+- [Semantic versioning](https://semver.org/)
+- [Dependabot documentation](https://docs.github.com/en/code-security/dependabot)
+
+---
+
+**Last Updated**: February 6, 2026  
+**Last Successful Run**: Fixed 52 vulnerabilities (4 critical, 32 high, 14 moderate, 2 low)  
+**Key Update**: @semantic-release/git v9.0.1 → v10.0.1

lib/geo.js

@@ -8,8 +8,7 @@ exports.resolveCountryToISO3 = resolveCountryToISO3;
 var Country = _interopRequireWildcard(require("countryjs"));
 var _lodash = require("lodash");
 var _logger = require("./logger");
-function _getRequireWildcardCache(e) { if ("function" != typeof WeakMap) return null; var r = new WeakMap(), t = new WeakMap(); return (_getRequireWildcardCache = function (e) { return e ? t : r; })(e); }
-function _interopRequireWildcard(e, r) { if (!r && e && e.__esModule) return e; if (null === e || "object" != typeof e && "function" != typeof e) return { default: e }; var t = _getRequireWildcardCache(r); if (t && t.has(e)) return t.get(e); var n = { __proto__: null }, a = Object.defineProperty && Object.getOwnPropertyDescriptor; for (var u in e) if ("default" !== u && {}.hasOwnProperty.call(e, u)) { var i = a ? Object.getOwnPropertyDescriptor(e, u) : null; i && (i.get || i.set) ? Object.defineProperty(n, u, i) : n[u] = e[u]; } return n.default = e, t && t.set(e, n), n; }
+function _interopRequireWildcard(e, t) { if ("function" == typeof WeakMap) var r = new WeakMap(), n = new WeakMap(); return (_interopRequireWildcard = function (e, t) { if (!t && e && e.__esModule) return e; var o, i, f = { __proto__: null, default: e }; if (null === e || "object" != typeof e && "function" != typeof e) return f; if (o = t ? n : r) { if (o.has(e)) return o.get(e); o.set(e, f); } for (const t in e) "default" !== t && {}.hasOwnProperty.call(e, t) && ((i = (o = Object.defineProperty) && Object.getOwnPropertyDescriptor(e, t)) && (i.get || i.set) ? o(f, t, i) : f[t] = e[t]); return f; })(e, t); }
 /**
  * takes unidentified country info and tries to get the ISO2/ISO3 Code
  * @param  {String} countryInfo some text about the country