If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/JanKallman/EPPlus shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

AVOID — Stale and unlicensed — last commit 6y ago

• 16 active contributors
• Distributed ownership (top contributor 48% of recent commits)
• ⚠ Stale — last commit 6y ago
• ⚠ No license — legally unclear to depend on
• ⚠ No CI workflows detected
• ⚠ No test directory detected

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live JanKallman/EPPlus repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/JanKallman/EPPlus.

What it runs against: a local clone of JanKallman/EPPlus — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in JanKallman/EPPlus | Confirms the artifact applies here, not a fork | | 2 | Default branch master exists | Catches branch renames | | 3 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 4 | Last commit ≤ 2109 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of JanKallman/EPPlus. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/JanKallman/EPPlus.git
#   cd EPPlus
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of JanKallman/EPPlus and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "JanKallman/EPPlus(\\.git)?\\b" \\
  && ok "origin remote is JanKallman/EPPlus" \\
  || miss "origin remote is not JanKallman/EPPlus (artifact may be from a fork)"

# 3. Default branch
git rev-parse --verify master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "EPPlus/CellStore.cs" \\
  && ok "EPPlus/CellStore.cs" \\
  || miss "missing critical file: EPPlus/CellStore.cs"
test -f "EPPlus/ConditionalFormatting/CF Implementation.cs" \\
  && ok "EPPlus/ConditionalFormatting/CF Implementation.cs" \\
  || miss "missing critical file: EPPlus/ConditionalFormatting/CF Implementation.cs"
test -f "EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs" \\
  && ok "EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs" \\
  || miss "missing critical file: EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs"
test -f "EPPlus/ConditionalFormatting/RangeConditionalFormatting.cs" \\
  && ok "EPPlus/ConditionalFormatting/RangeConditionalFormatting.cs" \\
  || miss "missing critical file: EPPlus/ConditionalFormatting/RangeConditionalFormatting.cs"
test -f "EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingRule.cs" \\
  && ok "EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingRule.cs" \\
  || miss "missing critical file: EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingRule.cs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 2109 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~2079d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/JanKallman/EPPlus"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

EPPlus is a .NET library that creates and manipulates Excel spreadsheets (XLSX format) using the Office Open XML standard without requiring Excel interop. It provides low-level APIs for styling, data validation, conditional formatting, charts, pivot tables, and formula calculation—all backed by dictionary-based cell storage for performance. Single-package structure: EPPlus/ contains the core library with feature modules (ConditionalFormatting/, with interface contracts in Contracts/) organized by functionality. CellStore.cs manages the dictionary-backed cell storage layer. Compatibility/ abstracts platform-specific code. Doc/ holds Sandcastle documentation generation. No clear test directory visible in top 60 files.

.NET developers (C# primarily) building server-side Excel generation systems, reporting tools, and data export pipelines who need to avoid Excel COM interop and its licensing/deployment complexity. Also used by enterprises automating financial reports, dashboards, and bulk data operations.

This repository (JanKallman/EPPlus) is archived and no longer maintained—it represents the final LGPL version (pre-5.0). The active development has migrated to EPPlusSoftware/EPPlus under a Polyform Noncommercial license. The codebase is production-grade and widely used, but this specific fork is frozen and should not be relied on for new projects.

CRITICAL: This repo is officially abandoned and archived; use EPPlusSoftware/EPPlus instead (see README). The license switch from LGPL to Polyform Noncommercial in v5+ breaks copyleft guarantees—commercial use now requires paid licensing. Single-maintainer risk is extreme since development has centralized at EPPlusSoftware. No visible CI/CD config (no .github/workflows), suggesting minimal ongoing QA.

Nothing—this repository is archived. The README explicitly states 'There will be no more activity here.' All active development shifted to https://github.com/EPPlusSoftware/EPPlus starting with v5.0 under the new license model.

git clone https://github.com/JanKallman/EPPlus.git && cd EPPlus && dotnet build EPPlus.sln (or open in Visual Studio). However, this archive is read-only; for active work, clone https://github.com/EPPlusSoftware/EPPlus instead.

Daily commands: dotnet build EPPlus.sln for the main library. Doc/EPPlusDoc.sln builds Sandcastle documentation. EPPlus.testsettings suggests MSTest framework, but no visible test runner command in repo data.

• EPPlus/CellStore.cs — Core data structure managing cell storage and retrieval—all spreadsheet content flows through this layer
• EPPlus/ConditionalFormatting/CF Implementation.cs — Central orchestrator for conditional formatting rules; essential for understanding how rule types are applied to ranges
• EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs — Factory pattern for creating all conditional formatting rule types; required for extending with new rule implementations
• EPPlus/ConditionalFormatting/RangeConditionalFormatting.cs — Primary API entry point for applying conditional formatting to cell ranges; demonstrates the public-facing design
• EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingRule.cs — Base contract defining all rule behaviors; architectural foundation for the rule hierarchy
• EPPlus/Compatibility/CompatibilitySettings.cs — Compatibility layer managing .NET version differences; critical for cross-platform stability

• CellStore — Manages all cell values, formulas, and metadata; provides O(1) lookup and update for cell coordinates

Add a New Conditional Formatting Rule Type

1. Create a new contract interface in Contracts/ inheriting from IExcelConditionalFormattingRule (EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingCustom.cs)
2. Implement the rule in Rules/ directory following naming convention ExcelConditionalFormatting{RuleType}.cs (EPPlus/ConditionalFormatting/Rules/ExcelConditionalFormattingCustom.cs)
3. Add rule type enum value to ExcelConditionalFormattingRuleType.cs (EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleType.cs)
4. Register factory method in ExcelConditionalFormattingRuleFactory.cs to instantiate your rule type (EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs)
5. Add operator or operator enum constants to ExcelConditionalFormattingOperatorType.cs if needed (EPPlus/ConditionalFormatting/ExcelConditionalFormattingOperatorType.cs)

Extend Conditional Formatting with Icon Set Variants

1. Create new icon set interface in Contracts/ inheriting from IExcelConditionalFormattingIconSetGroup (EPPlus/ConditionalFormatting/Contracts/IExcelConditionalFormattingSixIconSet.cs)
2. Implement concrete rule class in Rules/ with icon configuration logic (EPPlus/ConditionalFormatting/Rules/ExcelConditionalFormattingSixIconSet.cs)
3. Add icon set type to ExcelConditionalFormattingEnums.cs (EPPlus/ConditionalFormatting/ExcelConditionalFormattingEnums.cs)
4. Update ExcelConditionalFormattingRuleFactory.cs to handle new icon set creation (EPPlus/ConditionalFormatting/ExcelConditionalFormattingRuleFactory.cs)

Add Support for New .NET Framework Version

1. Extend CompatibilitySettings.cs with version detection and feature flags (EPPlus/Compatibility/CompatibilitySettings.cs)
2. Add type compatibility mappings in TypeCompat.cs for new framework APIs (EPPlus/Compatibility/TypeCompat.cs)
3. Extend ImageCompat.cs with platform-specific image rendering logic if needed (EPPlus/Compatibility/ImageCompat.cs)
4. Test CellStore.cs performance and memory usage under new framework conditions (EPPlus/CellStore.cs)

• .NET (no external dependencies) — EPPlus targets zero-dependency Excel manipulation, enabling lightweight deployment in any .NET environment without COM interop
• Office Open XML (OOXML) format — Standard xlsx format ensures compatibility with Excel 2007+ and any OOXML-compliant reader; enables round-trip editing
• Contract/Interface-based rule hierarchy — Conditional formatting has 50+ rule types; interfaces enable factory pattern for extensible rule creation without massive switch statements
• Compatibility layer abstraction — Bridges .NET Framework, .NET Core, and future runtimes, allowing single codebase to support multiple platform versions with conditional logic

• Moved to Polyform Noncommercial 1.0.0 license from LGPL

  • Why: Enables commercial sustainability for the library maintainers while keeping community use free
  • Consequence: Commercial users must obtain paid license; forks under LGPL will diverge from active development

• 60+ separate rule type classes instead of unified parameterized rule

  • Why: Each rule type has unique properties (e.g., DataBar has gradient, IconSet has thresholds); explicit types catch errors at compile time
  • Consequence: Large codebase, but strong type safety and intuitive fluent API for developers

• CellStore as single central repository for all cell data

  • Why: Simplifies consistency: values, formulas, formatting all tracked in one location; easier to sync with OOXML
  • Consequence: CellStore becomes a bottleneck for large sheets; memory-intensive if not optimized

• Does not provide Excel UI or interactive spreadsheet editor—purely programmatic generation and read/write
• Does not include VBA or macro execution engine—VBA code is preserved but not executed
• Does not support real-time collaborative editing—single-threaded file write model
• Does not handle legacy Excel formats (.xls)—OOXML (.xlsx) only

1. This repo is archived and read-only—PRs/issues will not be reviewed. 2) No visible test directory in top 60 files; full test suite may be in a separate location or missing documentation. 3) License is LGPL (not MIT/Apache)—copyleft obligations apply to derived works in this version only. 4) Building the doc project requires Sandcastle Help File Builder, an external tool. 5) .nuget/ directory suggests legacy NuGet restore flow; may not work with modern dotnet tooling without adjustment.

• Office Open XML (OOXML) Format — EPPlus reads/writes .xlsx files as ZIP-compressed XML; understanding OOXML structure (workbook.xml, worksheets/, styles.xml, etc.) is essential for debugging serialization issues and extending features.
• Dictionary-Based Sparse Data Structure — CellStore.cs uses dictionaries instead of 2D arrays to store cells, enabling O(1) lookup and memory efficiency for sparse sheets; this is EPPlus's core performance advantage over naive implementations.
• Conditional Formatting Rule Trees — The ConditionalFormatting module implements hierarchical rule evaluation (averages, color scales, icon sets, formulas); understanding predicate composition is critical for debugging CF features.
• Interface Segregation Pattern (ISP) — The 50+ IExcelConditionalFormatting*.cs contracts show ISP in action—each rule type has its own interface; this design enables runtime polymorphism and clean feature discovery.
• ZIP Archive as File Container — .xlsx files are ZIP archives; EPPlus must serialize/deserialize XML payloads and manage compression; understanding this layer is key for performance optimization and file corruption debugging.
• Cell Address Parsing (A1 Notation) — EPPlus accepts Excel cell references like 'A1', 'Z99', '$A$1' (mixed anchoring); the library must parse and validate these strings into row/column indices; a common source of off-by-one errors.
• Platform Abstraction / Compatibility Shims — Compatibility/ folder abstracts .NET Framework vs .NET Core API differences (e.g., ImageCompat.cs for graphics); critical for maintaining single codebase across target frameworks.

• EPPlusSoftware/EPPlus — Official continuation of this project; active development, v5.0+, Polyform Noncommercial license. Use this for new projects instead of the archived fork.
• ClosedXML/ClosedXML — Alternative .NET XLSX library with a higher-level, fluent API; MIT licensed, community-maintained; direct competitor solving the same problem.
• npoi/npoi — Apache POI port to .NET; supports both XLS and XLSX; Apache 2.0 licensed; heavier but more feature-complete for legacy Excel formats.
• DocumentFormat.OpenXml/Open-XML-SDK — Microsoft's low-level OOXML SDK; EPPlus builds on this conceptually; community-maintained alternative if you need direct XML control.
• ExcelPackage/ExcelPackage — Original predecessor that EPPlus forked from (per README); historical reference for understanding design evolution.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add comprehensive unit tests for ConditionalFormatting rule implementations

The ConditionalFormatting folder contains 30+ interface contracts and rule implementations (ExcelConditionalFormattingAboveAverage.cs, ExcelConditionalFormattingAboveStdDev.cs, etc.) but there's no visible test coverage in the file structure. Each rule type (Average, StdDev, ColorScale, IconSet, DataBar, TimePeriod, TopBottom) needs dedicated unit tests to ensure XML serialization/deserialization and rule application logic work correctly across different scenarios.

• [ ] Create EPPlus.Tests/ConditionalFormatting/Rules/ directory structure
• [ ] Add unit tests for each rule class in EPPlus/ConditionalFormatting/Rules/ (AboveAverage, AboveStdDev, etc.)
• [ ] Test XML serialization roundtrips using ExcelConditionalFormattingRuleFactory.cs
• [ ] Test edge cases: empty ranges, invalid formulas, boundary values for color/icon scales
• [ ] Verify integration with RangeConditionalFormatting.cs and ExcelConditionalFormattingCollection.cs

Add GitHub Actions CI workflow for .NET multi-version testing

The repo contains two solution files (EPPlus.sln and EPPlus.Core.sln) suggesting support for multiple .NET versions, but there's no visible GitHub Actions workflow file (.github/workflows/*.yml). Adding automated testing against .NET Framework 4.5+, .NET Core, and .NET 5+ would catch regressions early, validate Compatibility/ module works correctly, and reduce maintainer burden.

• [ ] Create .github/workflows/dotnet-build-test.yml with matrix strategy for .NET versions (4.5, 4.6.1, .NET Core 3.1, .NET 5.0+)
• [ ] Add build steps for both EPPlus.sln and EPPlus.Core.sln
• [ ] Configure test execution using vstest or xunit runners
• [ ] Add NuGet restore step using .nuget/NuGet.targets configuration
• [ ] Include compatibility validation for ImageCompat.cs and TypeCompat.cs across target frameworks

Refactor monolithic CellStore.cs and create data structure tests

CellStore.cs appears to be a core component for managing cell data but its size and centrality suggest it may contain multiple responsibilities. Splitting this into focused modules (CellValueStore, CellMetadataStore, CellReferenceIndex) would improve maintainability and testability, especially given the complexity of styling, validation, and conditional formatting features that depend on it.

• [ ] Analyze CellStore.cs to identify separable concerns (value storage, metadata, indexing, caching)
• [ ] Create EPPlus/CellStore/ folder with split implementations
• [ ] Update dependencies in EPPlus/ConditionalFormatting/, EPPlus/DataValidation/, and styling classes
• [ ] Add unit tests for each CellStore component covering CRUD operations, range queries, and event propagation
• [ ] Verify performance with existing integration tests remains unchanged

• Add unit tests for CellStore.cs dictionary operations (no visible test coverage in repo structure); start with null-safety and edge cases like negative indices or extremely large ranges.
• Document the ConditionalFormatting interface contract pattern in a ARCHITECTURE.md file; the 50+ IExcelConditionalFormatting*.cs files lack a cohesive design guide for new contributors.
• Ensure Compatibility/TypeCompat.cs and ImageCompat.cs have complete coverage for .NET Standard 2.1+ APIs; compare against newer .NET runtime capabilities and flag obsolete shims for removal.

The EPPlus codebase has a moderate security posture with several areas of concern. The main risks are: (1) License compliance complexity due to the LGPL-to-Polyform transition requiring careful tracking; (2) Potential XXE vulnerabilities in XML parsing of XLSX files; (3) Formula injection risks when processing Excel content; (4) Archived repository status creating confusion about supported versions. The library's dependency-free design is a security strength, but explicit XXE mitigations and formula validation should be implemented. Users should migrate to the active repository (EPPlusSoftware/EPPlus) to receive security updates.

• High · License Change to Polyform Noncommercial — README.md, License terms. The project has transitioned from LGPL to Polyform Noncommercial 1.0.0 license starting from version 5. This creates legal and compliance risks for commercial users who may unknowingly use the library without obtaining a commercial license. The README clearly states commercial usage requires a paid license, which could lead to license violations. Fix: Implement license header comments in all source files. Add license validation or version checks at runtime for commercial deployments. Maintain clear documentation of version-specific licensing. Consider implementing a license key verification system for commercial users.
• Medium · No Visible Dependency Management File — Package management files (.csproj, packages.config, etc.). The analysis shows no package dependency file content (packages.config, .csproj, or nuget.lock file contents provided). Without explicit dependency tracking, there's potential risk of using outdated or vulnerable third-party libraries. The README states 'EPPlus has no dependencies other than .NET' but this should be verified and maintained. Fix: Maintain and audit a lock file (packages.lock.json or similar) to track all dependencies and their versions. Implement automated dependency vulnerability scanning using tools like NuGet security advisories. Regularly update dependencies to patch known vulnerabilities.
• Medium · XML External Entity (XXE) Risk in Excel File Processing — EPPlus/CellStore.cs and XML parsing components. EPPlus reads and processes Office Open XML (XLSX) files which use XML internally. Without explicit XXE protections, malicious Excel files could exploit XML parsing vulnerabilities to cause denial of service or information disclosure attacks. Fix: Disable XXE processing by setting XML parser properties: XmlReaderSettings with ProhibitDtd=true and DtdProcessing=Prohibit. Validate and sanitize all XML content before parsing. Implement file size limits for uploaded Excel files.
• Medium · Insufficient Input Validation for Formula Injection — EPPlus/ConditionalFormatting/Rules and cell value processing. Excel files can contain formulas that execute arbitrary code. EPPlus processes cell values and formulas without apparent validation. An attacker could craft a malicious Excel file with formula injection payloads (e.g., =cmd|'/c calc'!A1) that execute when opened in Excel. Fix: Implement formula validation to detect and neutralize dangerous Excel functions. Prefix potentially dangerous cells with a single quote to prevent formula execution. Add configuration options to restrict formula types. Validate all user-provided content before inserting into cells.
• Low · Repository Archive Status — README.md. The repository is marked as archived with the message 'This repository has moved to https://github.com/EPPlusSoftware/EPPlus.' This archive may contain outdated code with unpatched vulnerabilities. Users cloning this old repository may miss critical security updates. Fix: Redirect users to the active repository. Add prominent deprecation warnings in documentation. Consider adding automatic checks in the code to warn about outdated versions. Maintain security patches even in archived versions or clearly indicate end-of-life status.
• Low · Missing Security Policy — .github directory. No SECURITY.md or security policy file is visible in the provided file structure. This makes it difficult for security researchers to report vulnerabilities responsibly. Fix: Create a SECURITY.md file with clear vulnerability disclosure procedures. Include contact information for security issues and expected response times. Reference the responsible disclosure process on the active repository.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.