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/nissl-lab/npoi 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.

GO — Healthy across the board

• Last commit 2w ago
• 7 active contributors
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Concentrated ownership — top contributor handles 55% of recent commits

_{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 nissl-lab/npoi repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/nissl-lab/npoi.

What it runs against: a local clone of nissl-lab/npoi — 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 nissl-lab/npoi | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 41 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of nissl-lab/npoi. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/nissl-lab/npoi.git
#   cd npoi
#
# 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 nissl-lab/npoi and re-run."
  exit 2
fi

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 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 "OpenXmlFormats/OOXMLFactory.cs" \\
  && ok "OpenXmlFormats/OOXMLFactory.cs" \\
  || miss "missing critical file: OpenXmlFormats/OOXMLFactory.cs"
test -f "OpenXmlFormats/Spreadsheet/Document/WorkbookDocument.cs" \\
  && ok "OpenXmlFormats/Spreadsheet/Document/WorkbookDocument.cs" \\
  || miss "missing critical file: OpenXmlFormats/Spreadsheet/Document/WorkbookDocument.cs"
test -f "OpenXmlFormats/Spreadsheet/Document/WorksheetDocument.cs" \\
  && ok "OpenXmlFormats/Spreadsheet/Document/WorksheetDocument.cs" \\
  || miss "missing critical file: OpenXmlFormats/Spreadsheet/Document/WorksheetDocument.cs"
test -f "OpenXmlFormats/Drawing/Chart/ChartSpaceDocument.cs" \\
  && ok "OpenXmlFormats/Drawing/Chart/ChartSpaceDocument.cs" \\
  || miss "missing critical file: OpenXmlFormats/Drawing/Chart/ChartSpaceDocument.cs"
test -f "Directory.Build.props" \\
  && ok "Directory.Build.props" \\
  || miss "missing critical file: Directory.Build.props"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 41 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~11d)"
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/nissl-lab/npoi"
  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).

NPOI is a .NET library that reads and writes Microsoft Office file formats (Excel 2003/2007 .xls/.xlsx, Word .docx) without requiring Microsoft Office or COM interop installed. It's a direct port of Apache POI to C#, enabling pure managed code manipulation of office documents across Windows and Linux. Monorepo structure: OpenXmlFormats/ contains 60+ auto-generated C# classes mirroring Office Open XML schema (Bibliography.cs, Chart/.cs, Drawing/.cs); core NPOI.SS namespace (Spreadsheet) and NPOI.XWPF (Word) provide high-level APIs; Directory.Build.props and Directory.Packages.props centralize .NET build configuration; GitHub Actions workflows (CI.yml, opencode.yml) orchestrate testing and static analysis via NUKE build system.

.NET developers (Framework 4.0+, .NET Core, .NET 5-8) who need to generate reports, export data to Excel, read spreadsheets, or manipulate Word documents programmatically in server-side applications, data pipelines, or desktop tools without Excel dependencies.

Production-ready and actively maintained. The project has significant adoption (282nd on NuGet ranking, high download count), comprehensive Office format support, established CI/CD via GitHub Actions (.github/workflows/CI.yml, PR.yml), and a recent maintenance model (EULA added in v2.8.0 with sponsorship requirement). However, it's primarily maintained by a core team.

Moderate risk: single maintainer model (tonyqus as primary owner) creates succession risk; commercial EULA requirement since v2.8.0 adds licensing complexity for revenue-generating users; 27MB+ C# codebase with large OpenXmlFormats directory (auto-generated XML schema classes) makes code review difficult. Dependency on .NET 8 or .NET Standard 2.0+ limits legacy .NET Framework adoption.

Active maintenance with GitHub Sponsorship model enforced (OSMFEULA.txt + maintenance fee requirement). Recent activity includes CI pipeline refinement (.github/workflows/), static analysis integration, and potential cross-platform improvements (Linux support documented in wiki). No major breaking changes visible in recent commits based on versioning strategy.

git clone https://github.com/nissl-lab/npoi.git
cd npoi
# NUKE build system (see .nuke/build.schema.json)
./build.ps1  # Windows
./build.sh   # Linux/macOS
dotnet build npoi.sln
dotnet test  # Run test suite

Daily commands:

# Full build & test
./build.ps1 -Target Test  # Windows NUKE
./build.sh --target Test   # Linux NUKE

# Or direct dotnet
dotnet build npoi.sln
dotnet test npoi.sln --configuration Release

# Create NuGet package
dotnet pack npoi.sln --configuration Release --output ./artifacts

• OpenXmlFormats/OOXMLFactory.cs — Core factory for creating OpenXML format objects; entry point for document parsing and serialization across all Office formats.
• OpenXmlFormats/Spreadsheet/Document/WorkbookDocument.cs — Root document class for Excel workbooks; demonstrates the pattern for all Office document types in the codebase.
• OpenXmlFormats/Spreadsheet/Document/WorksheetDocument.cs — Worksheet model for Excel sheets; illustrates how content documents are structured and linked to parent documents.
• OpenXmlFormats/Drawing/Chart/ChartSpaceDocument.cs — Chart document model; shows how embedded drawing objects are represented in OpenXML format.
• Directory.Build.props — Global build configuration and package versioning; defines NuGet dependencies and compilation settings for all projects.
• .github/workflows/CI.yml — Continuous integration pipeline; defines build, test, and release processes.

• OOXMLFactory — Central dispatcher

Add a new OpenXML document type

1. Create a new document class in OpenXmlFormats/[Format]/Document/ extending the appropriate base document type (OpenXmlFormats/Spreadsheet/Document/WorkbookDocument.cs)
2. Define the XML schema structure using C# properties matching OpenXML spec (OpenXmlFormats/Spreadsheet/BaseTypes.cs)
3. Register the document type in OOXMLFactory to enable automatic instantiation (OpenXmlFormats/OOXMLFactory.cs)
4. Add serialization/deserialization logic to read and write the document XML (OpenXmlFormats/RelationshipReference.cs)

Add support for a new drawing element type

1. Create element class in OpenXmlFormats/Drawing/ with properties matching OpenXML schema (OpenXmlFormats/Drawing/ShapeProperties.cs)
2. Implement XML serialization following the pattern in existing drawing types (OpenXmlFormats/Drawing/Text.cs)
3. Register element in OOXMLFactory if it's a top-level drawable type (OpenXmlFormats/OOXMLFactory.cs)
4. Update relevant document type (spreadsheet, wordprocessing) to include the new element (OpenXmlFormats/Spreadsheet/Document/WorksheetDocument.cs)

Add encryption support for a new format

1. Create format-specific encryption document class in OpenXmlFormats/Encryption/ (OpenXmlFormats/Encryption/EncryptionDocument.cs)
2. Implement key derivation using existing KeyEncryptor classes (OpenXmlFormats/Encryption/KeyEncryptorPassword.cs)
3. Add encryption metadata parsing and generation (OpenXmlFormats/Encryption/Encryption.cs)

• .NET / C# — Cross-platform runtime support; enables Office format manipulation without Microsoft Office or COM+ interop; strong XML and compression support via System.Xml and System.IO.Compression
• OpenXML (ECMA-376) — Industry standard for Office document formats (xlsx, docx, pptx); enables read/write compatibility with Microsoft Office and other tools
• ZIP archive format — OOXML documents are ZIP containers; provides compression and multi-file organization for document parts
• Encryption (AES, SHA-512, PBKDF2) — Implements Office Open XML encryption standard for password-protected documents

• Generated/hand-coded XML schema classes instead of dynamic XML parsing

  • Why: Type safety, IntelliSense support, compile-time validation, easier refactoring across large codebase
  • Consequence: High maintenance burden when schemas change; large volume of repetitive class definitions; slower initial learning curve for contributors

• Factory pattern (OOXMLFactory) for document instantiation

  • Why: Centralizes format detection logic; simplifies adding new document types; maintains clean separation of concerns
  • Consequence: Factory becomes a bottleneck if many document types exist; requires registration of all types; potential for missing type registrations

• No dependency on Microsoft.Office.Interop or COM+

  • Why: Cross-platform support (Linux, Mac, Docker); no Office license required; lighter deployment footprint
  • Consequence: Must reimplement all format knowledge from ECMA spec; no fallback to Office for edge cases; higher complexity for format-specific behaviors

• Lazy loading of document relationships and parts

  • Why: Memory efficiency for large documents with many sheets/charts; faster initial load time
  • Consequence: Deferred errors (missing parts discovered on access); more complex error handling; harder to validate document integrity upfront

• Does not provide Microsoft Office interop or automation; no COM+ support
• Does not require Microsoft Office to be installed on the system
• Does not implement real-time collaborative editing features
• Does not support legacy Office binary formats (OLE2, pre-2007); only OOXML (.xlsx, .docx, .pptx)
• Does not include UI components; library-only; no GUI editors
• Does not implement Office macros or VBA execution
• Does not provide Office calculation engine re-implementation; formulas stored as strings

EULA/Licensing: Binary releases require OSMF maintenance fee payment since v2.8.0 (see OSMFEULA.txt)—open source projects and non-revenue users exempt but must verify status. Auto-generated code: OpenXmlFormats/.cs files are generated from Office XML schemas; manual edits will be overwritten—modify schema generators instead. Format dual implementation: HSSF (.xls, binary) and XSSF (.xlsx, OpenXML) have parallel APIs—feature parity not guaranteed between formats. No Office installed: Library does NOT support COM interop (Office.Interop.) and will fail if code assumes Excel/Word is running. .NET version targeting: Must match target framework capability (e.g., .NET Framework 4.0 lacks System.Collections.Immutable); see Directory.Build.props for supported versions.

• Office Open XML (OOXML) — NPOI's entire XSSF and XWPF subsystems depend on understanding OOXML—a ZIP archive containing XML files defining spreadsheets/documents; OpenXmlFormats/ classes map XML schema to C# objects
• Binary Office Format (OLE2/CFB) — HSSF subsystem parses legacy .xls files using Compound File Binary (CFB) format—a container format predating OOXML with binary cell records; critical for .xls file reading
• Factory & Strategy Patterns — NPOI uses WorkbookFactory to abstract HSSF vs. XSSF creation; understanding these patterns helps navigate dual .xls/.xlsx implementations without code duplication
• XML Schema Generation & Code Generation — 60+ OpenXmlFormats/*.cs files are auto-generated from Office XML schemas; contributors must understand schema-to-code tooling rather than editing generated classes directly
• Platform Abstraction via .NET Standard — NPOI targets .NET Standard 2.0/2.1 to run on Windows (.NET Framework), Linux (.NET Core), and macOS; understanding target framework differences prevents platform-specific bugs
• Cell Style Inheritance & Cascading — Excel formatting (fonts, borders, colors) uses indexed palette + inheritance; NPOI.SS.UserModel IStyle/ICellStyle APIs abstract this complexity but contributors must understand the underlying Excel style model
• Formula Parsing & Expression Trees — NPOI.SS.Formula subsystem parses Excel formula strings into expression trees for evaluation; contributors adding formula support need AST/parser knowledge

• ClosedXML/ClosedXML — Alternative .NET library for Excel .xlsx manipulation with focus on ease-of-use and LINQ support; direct competitor for spreadsheet scenarios
• apache/poi — Original Java implementation that NPOI was ported from; source of truth for Office format parsing logic and feature compatibility
• dotnet/runtime — Underlying .NET runtime; critical for cross-platform support (Windows/Linux) and XML serialization (System.Xml.Linq) used by NPOI
• nuke-build/nuke — NUKE build system used by NPOI (see .nuke/build.schema.json); defines build orchestration, CI/CD pipeline configuration
• DocumentFormat.OpenXml/Open-XML-SDK — Official Microsoft implementation of Office Open XML handling; NPOI offers lighter-weight alternative but less official/supported

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 OpenXmlFormats Drawing module

The OpenXmlFormats/Drawing directory contains 30+ complex classes (Chart, Shape, Picture, Table, etc.) but there are no visible test files in the repo structure. Given that this is a critical serialization/deserialization layer for Office formats, adding unit tests would significantly improve reliability and prevent regressions. This is high-value because drawing elements are commonly used in Excel and Word documents.

• [ ] Create test project structure (e.g., tests/OpenXmlFormats.Drawing.Tests/) mirroring OpenXmlFormats/Drawing folder structure
• [ ] Add unit tests for OpenXmlFormats/Drawing/Chart/*.cs classes (Chart, AreaChart, BarChart, etc.) covering serialization/deserialization
• [ ] Add unit tests for OpenXmlFormats/Drawing/Shape*.cs classes (ShapeProperties, ShapeGeometry, ShapeStyle, etc.)
• [ ] Add unit tests for OpenXmlFormats/Drawing/Table.cs and TableStyle.cs
• [ ] Integrate new test project into CI.yml and PR.yml workflows to run on each commit

Add GitHub Action workflow for code coverage reporting

The repo has CI.yml, PR.yml, opencode.yml, and static.yml workflows but none appear to generate or track code coverage metrics. Adding Codecov or Coverlet integration would help contributors understand test coverage gaps and prevent coverage regressions. This is especially important given the breadth of the OpenXmlFormats implementation.

• [ ] Add Coverlet package reference to Directory.Packages.props for code coverage collection
• [ ] Create new GitHub Action (coverage.yml) that runs on PR and main branch commits
• [ ] Configure the workflow to collect coverage from existing test projects using dotnet test /p:CollectCoverage=true
• [ ] Integrate Codecov upload step (or similar service) to track coverage metrics over time
• [ ] Add coverage badge to README.md showing current coverage percentage

Create API documentation for OpenXmlFormats namespace with XML comments

The OpenXmlFormats directory contains complex classes (CustomPropertiesDocument, DocumentPropertiesExtended, Bibliography, etc.) that lack visible XML documentation comments. This makes it difficult for contributors and users to understand the purpose of each class and which Office format specifications they implement. Adding comprehensive XML comments enables IntelliSense and auto-generated docs via DocFX.

• [ ] Add XML documentation comments (///) to all public classes in OpenXmlFormats/*.cs root files (e.g., CustomPropertiesDocument.cs, Bibliography.cs)
• [ ] Add XML documentation to OpenXmlFormats/Drawing/Chart/*.cs classes describing which chart types and properties they represent
• [ ] Add inline references to OOXML/Office Open XML specification sections (e.g., ECMA-376) where applicable
• [ ] Configure DocFX in Directory.Build.props to generate HTML documentation from XML comments
• [ ] Add generated docs link to README.md

• Add comprehensive unit tests for OpenXmlFormats/Drawing/Chart/*.cs classes—currently auto-generated schema classes lack explicit test coverage; write fixture-based tests to validate serialization round-trips for AreaChart.cs, BarChart.cs, and LineChart.cs
• Document HSSF vs. XSSF feature parity matrix in wiki with specific examples (e.g., 'cell named ranges supported in XSSF but not HSSF')—README mentions 'most features' but lacks concrete limitations table for users choosing format
• Implement missing formula function handlers in NPOI.SS.Formula—audit which Excel functions are unsupported (e.g., newer statistical functions in Excel 365) and add POC implementation for 3-5 high-demand functions with tests

The NPOI codebase demonstrates good security practices overall. No critical vulnerabilities were identified in the visible structure. The main concerns are: (1) telemetry tracking in README without explicit consent, (2) potential license confusion with dual licensing model, and (3) generic issue template guidance that could lead to information disclosure. The absence of exposed secrets, hardcoded credentials, or obvious injection points in the file structure is positive. Recommendations focus on privacy transparency, license clarity, and user guidance improvements. The project would benefit from security-focused CI/CD workflows and regular dependency auditing given its role as a widely-used Office document processing library.

• Medium · Tracking Pixel in README — README.md - traffic badge. The README contains an encoded tracking pixel that sends usage data to Segment.io. While the data appears benign (userId: 'tonyqus', event: 'NPOI Homepage'), this represents potential telemetry collection without explicit user consent and could be privacy concern for users who clone or view the repository. Fix: Remove the tracking pixel or provide clear documentation about what data is collected and obtain explicit consent. Consider using privacy-respecting analytics alternatives.
• Low · Multiple EULA/License Files Present — LICENSE, OSMFEULA.txt. The repository contains both Apache 2.0 LICENSE and OSMFEULA.txt. This dual licensing model could create confusion about which license applies to different components. OSMF (Open Source Motion Framework) EULA typically has different terms than Apache 2.0. Fix: Clearly document in README which components fall under which license. Consider consolidating licenses or using SPDX license expressions to clarify dual-license intent.
• Low · Public Issue Templates Disclosure — .github/ISSUE_TEMPLATE/. Public GitHub issue templates in .github/ISSUE_TEMPLATE may inadvertently guide users to disclose sensitive information. While templates themselves are not sensitive, the bug_report.md could encourage users to share versions, configurations, or file samples that might contain sensitive data. Fix: Add guidance in issue templates warning against sharing sensitive information, credentials, or proprietary documents. Include template instructions about redacting sensitive data.

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.