Skip to content
This repository was archived by the owner on Feb 9, 2026. It is now read-only.

chore: merge agent branch #38

Merged
andibeuge merged 1 commit into from
Feb 6, 2026
Merged

chore: merge agent branch #38

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
298 changes: 298 additions & 0 deletions AI_AGENT_README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -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
3 changes: 1 addition & 2 deletions lib/geo.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
Loading