v1.4.0: fix ~85 bugs (author disambiguation, rankings, rate limits), add HTML/map/tree/CSV exports, FWCI, CLI, and test suite

Author: yueyueL

.github/workflows/tests.yml

@@ -0,0 +1,27 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ['3.9', '3.11', '3.12']
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+      - name: Install dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install -r requirements.txt pytest
+      - name: Run tests
+        env:
+          PYTEST_DISABLE_PLUGIN_AUTOLOAD: '1'
+        run: python -m pytest tests/ -v

.gitignore

@@ -0,0 +1,30 @@
+# User data — contains API keys, cached results, and settings. Never commit.
+.citationimpact/
+.CitationImpact/
+
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+build/
+dist/
+.eggs/
+
+# Tooling
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+
+# Environments
+.venv/
+venv/
+
+# Editors / OS
+.vscode/
+.idea/
+.DS_Store
+
+# Exported reports (generated output)
+impact_report_*.json

CHANGELOG.md

@@ -0,0 +1,141 @@
+# Changelog
+
+## 1.4.0 (2026-07-13)
+
+### New output formats
+- **CSV bundle** (`--format bundle`): writes `citing_papers.csv`, `authors.csv`
+  (with country + match confidence), `venues.csv`, and `timeline.csv` into one
+  directory for spreadsheet analysis.
+- **Citation tree**: interactive terminal tree (menu option 8, groupable by
+  year / venue / institution) and a plain-text export (`--format tree`).
+- **HTML report** (`--format html`): a single self-contained HTML file with
+  stat tiles, citation timeline chart, world map of citing institutions,
+  citation-intent chart with context quotes, scholar/venue tables, and a
+  collapsible citation tree. Works offline, light/dark aware.
+
+### International reach
+- Citing authors' institution **countries** are now captured from OpenAlex
+  (ISO codes on every author, a per-country breakdown in results, a
+  "cited across N countries" grant statement, country column in exports).
+
+### Reliability
+- Live end-to-end testing caught and fixed a crash: OpenAlex returns explicit
+  `null` for `summary_stats` / `last_known_institutions` / `affiliations` on
+  some records; all parsing sites are now null-safe (regression-tested).
+- `max_citations` is clamped to Semantic Scholar's 1000-limit in API mode
+  instead of failing with HTTP 400.
+- Full-diff regression audit confirmed and fixed 10 defects introduced during
+  the sprint, including: Google Scholar citation IDs leaking from one analysis
+  into the next; OpenAlex title lookups breaking on commas (filter injection);
+  author dedup creating "chimera" entries (one person's identity with another's
+  h-index); Rich-markup crashes on citation text containing bracket tokens
+  (e.g. `[/INST]`, `[sic]`); scripted `-o -` output polluted by progress
+  prints (now on stderr); explicit `--h-index-threshold 0` being ignored;
+  12-letter surnames misread as Google Scholar IDs.
+- Data-quality safeguards: correct Semantic Scholar request pacing with an API
+  key (was 40 req/s against a ~1 req/s allowance, causing silent mass
+  failures), `Retry-After` honored on 429s, per-run API-failure tracking with a
+  visible "data may be incomplete" banner in the UI and all report formats, and
+  degraded results are no longer written to the 7-day cache. The alarm is
+  proportional: a few transient failures produce a note, not the banner.
+- **Batch author fetching**: citing-author profiles are now fetched from
+  Semantic Scholar's batch endpoint (one request for up to 500 authors instead
+  of one per author), then enriched via OpenAlex as before — analyses make an
+  order of magnitude fewer requests and survive strict rate limits.
+- **Adaptive throttle**: consecutive rate-limit failures automatically slow
+  request pacing (up to 8×) and recover on success. OpenAlex now runs at half
+  its polite-pool allowance by default; set your email in Settings to join the
+  polite pool (dramatically more reliable than anonymous access).
+
+## 1.3.1 (2026-07-12)
+
+### Author disambiguation overhaul (fixes reported same-name mix-ups)
+Addresses the reported issue where authors sharing a name could be mistaken
+for each other. Author resolution is now **ID-first with evidence-verified
+fallbacks**:
+
+- Every resolved author profile carries a `match_confidence` provenance:
+  `id` (unique Semantic Scholar / Google Scholar identifier), `verified`
+  (name search corroborated by the candidate's publication list), or
+  `name` (unverified name-only match).
+- Name-keyed author-cache hits are now **gated**: a cached profile that
+  merely shares an author's name is only reused when its stored publications
+  contain the citing paper. Unverifiable name hits are rejected rather than
+  trusted.
+- **Browse Other Authors by name** now shows a disambiguation picker
+  (name, affiliation, h-index, paper count from Semantic Scholar author
+  search) instead of silently using the first same-named hit.
+- The UI marks each author with ✓ (ID-matched), ≈ (verified), or ? (name-only,
+  may be a different person), with a legend; the summary shows
+  "Author profiles: N ID-matched, N verified, N name-only", and the Markdown
+  export gains a Match column.
+- Exports now use the configured h-index threshold in their labels instead of
+  a hardcoded "≥ 20".
+
+## 1.3.0 (2026-07-12)
+
+### New features
+- **Field-normalized impact (FWCI)**: analyses now fetch the Field-Weighted
+  Citation Impact and field citation percentile from OpenAlex (1.0 = world
+  average for the same field/year), shown in the overview, grant summary,
+  impact statements, and exports. Degrades gracefully when unavailable.
+- **Self-citation detection**: every analysis now reports how many citations
+  are independent of the original authors (matched by Semantic Scholar author
+  ID, falling back to name compatibility) — the number grant reviewers ask for.
+- **"How Your Work Is Used"**: new drill-down (option 7) showing the citation
+  intent distribution (methodology / background / result) and sample in-text
+  context quotes from citing papers.
+- **Report exporter** (`citationimpact/export.py`): export analyses as
+  grant-ready **Markdown**, **LaTeX** (appendix-ready section), **CSV** (all
+  citing papers), **BibTeX**, or JSON — from the results screen (`e`) or the CLI.
+- **Non-interactive CLI** (`citationimpact/cli.py`): script the tool without
+  menus — `citation-impact analyze "Paper title" --format markdown -o report.md`,
+  `citation-impact cache list|clear`, `citation-impact --version`.
+  Running `./citation-impact` with no arguments still opens the interactive UI.
+- **Test suite**: 200+ pytest tests covering exporters, models, categorization,
+  rankings, caches, analyzer logic, clients, UI helpers, and the CLI.
+- **CI**: GitHub Actions workflow running the suite on Python 3.9–3.12.
+
+### Bug fixes (72 verified defects, found by multi-agent audit)
+Highlights — full details in git history:
+- **Institution misclassification (critical)**: substring matching classified
+  Princeton/Cincinnati as *Industry* (`'inc'`), and any "Department of …",
+  Newcastle, or NIST-like affiliation as *Government* (`'epa'`, `'cas'`,
+  `'nist'` substrings). Now word-boundary matched.
+- **Wrong university credit**: fuzzy matchers gave "National University" NUS's
+  Top-10 rank and matched arbitrary superstring venues; QS range ranks
+  (601-610 etc., 60% of the file) were silently dropped; ICORE junk strings
+  ("Unranked", "TBR") were surfaced as ranks.
+- **Dead features revived**: methodological citations (S2 returns lowercase
+  intents), Crossref citation-count/venue merging (key mismatch/unreachable
+  branch), S2 DOI enrichment (externalIds never requested), ORCID fallback
+  (wrong class name + list/dict mismatch), DBLP author publications
+  (nonexistent endpoint), GS-only papers yielding 0 citations in
+  comprehensive mode.
+- **Crashes fixed**: google_scholar mode signature mismatches, unified
+  search_paper on zero-score results, null citationCounts, ORCID null-name
+  records, QS range-rank parsing, None affiliations.
+- **Correctness**: author dedup no longer merges distinct authors (first-initial
+  guard) and no longer loses repeat citers' papers; publication-overlap cache
+  matching no longer attributes co-authors' profiles to each other; author-profile
+  cache no longer merges same-name researchers; grant statements no longer
+  conflate author counts with university counts and respect the configured
+  h-index threshold; citation URLs no longer dropped by an operator-precedence
+  bug; "recent citations" now really spans 2 years.
+- **Robustness**: config writes are atomic (API keys can't be destroyed by a
+  failed save); connection errors are retried; cache expiry handles unlink
+  races; UTF-8 enforced for profile files; shared client no longer reused
+  across data-source switches (stale-mode analyses); browse-author-by-name
+  works in API mode; Selenium clients are tracked and closed.
+
+### Packaging & hygiene
+- `setup.py` console entry point referenced a nonexistent module; now installs
+  working `citation-impact` / `citationimpact-ui` commands; version
+  single-sourced from `citationimpact/__init__.py` (was 0.1.0 vs 1.2.0).
+- Added `pyproject.toml`, `.gitignore` (the `.citationimpact/` folder holding
+  plaintext API keys was previously trackable), and untracked committed
+  `__pycache__` files.
+
+## 1.2.0
+
+- Prior release (see git history).

README.md

@@ -30,13 +30,18 @@ I built CitationImpact to answer these questions automatically. Instead of manua
 CitationImpact analyzes your research citations and generates **grant-ready impact statements**:
 
 - 📋 **Grant Impact Summary** – Copy-ready statements for proposals & tenure files
+- 🆔 **ID-first author matching** – Unique Semantic Scholar/Google Scholar IDs with publication-verified fallbacks; every author is marked ✓ ID-matched, ≈ verified, or ? name-only so you can trust the numbers
+- 🌍 **Field-normalized impact** – FWCI & citation percentile from OpenAlex ("cited 4.2× the world average for its field")
+- 🙋 **Self-citation detection** – Reports what % of citations are independent of the original authors
+- 💬 **How your work is used** – Citation intent breakdown (methodology/background/result) with in-text quotes
 - 🏆 **Highly-Cited Papers** – Papers with 100+ citations that cite YOUR work
 - 👥 **High-profile scholars** – Prominent researchers (by h-index & total citations) citing your work  
 - 🏛️ **Institution breakdown** – Universities (with QS/US News rankings), Industry, Government
 - 📚 **Venue quality** – Top-tier journals/conferences (CORE, CCF, h-index rankings)
 - 📈 **Citation velocity** – Track your impact over time with timeline visualization
 - 🔗 **Clickable links** – Every author and paper is linked to their profile
 - 💾 **Smart caching** – Never wait twice for the same analysis (user-controlled refresh)
+- 📤 **Grant-ready exports** – Markdown, LaTeX, CSV, BibTeX, JSON (interactive or via CLI)
 
 ---
 
@@ -56,6 +61,14 @@ pip install -r requirements.txt
 
 That's it! The interactive menu will guide you through the rest.
 
+Prefer scripting? There's a non-interactive mode too:
+
+```bash
+./citation-impact analyze "Your Paper Title" --format markdown -o report.md
+./citation-impact analyze "Your Paper Title" --format latex -o -   # print to stdout
+./citation-impact cache list
+```
+
 <p align="center">
   <img src="assets/Screenshot1-start.png" alt="Main Menu" width="700"/>
 </p>
@@ -91,9 +104,9 @@ That's it! The interactive menu will guide you through the rest.
 Want to analyze papers by someone else?
 
 1. Select **"3. 👤 Browse Other Authors"**
-2. Enter their **Semantic Scholar ID** or **Google Scholar ID**
-3. Pick a paper from the list
-4. Analyze it with one click
+2. Enter their **Semantic Scholar ID** or **Google Scholar ID** (most accurate), or just their name
+3. If several researchers share that name, pick the right one from the candidate list (shown with affiliation, h-index, and paper count)
+4. Pick a paper from the list and analyze it with one click
 
 **Pro tip:** Save your own author ID in Settings so "My Papers" works instantly!
 
@@ -198,6 +211,34 @@ Example output:
 - Explore citation contexts
 - **Adaptive tables** – automatically fit your terminal width
 
+### 💾 Export Formats
+Press `e` on any results screen (or use `--format` on the CLI) to export:
+
+| Format | Best for |
+|--------|----------|
+| **HTML** (`.html`) | Shareable one-file report: charts, **world map** of citing countries, citation tree — works offline, light/dark |
+| **Markdown** (`.md`) | Pasting into docs, GitHub, Notion |
+| **LaTeX** (`.tex`) | Grant appendices – drop straight into your proposal |
+| **CSV** (`.csv`) | All citing papers, one row each, for spreadsheets |
+| **CSV bundle** (`bundle`) | Complete data dump: papers, authors, venues, timeline as separate CSVs |
+| **BibTeX** (`.bib`) | Reference managers (Zotero, JabRef) |
+| **Tree** (`.txt`) | Plain-text citation tree grouped by year |
+| **JSON** (`.json`) | Further scripting and analysis |
+
+Reports are written to `.citationimpact/exports/` by default.
+
+### 🌳 Citation Tree
+Menu option **8** shows every citing paper as an expandable tree — group by
+**year**, **venue**, or **institution type** with one keypress, every title
+clickable.
+
+### 🛡️ Data-Quality Guarantees
+- If API requests fail mid-analysis (rate limits, network), the report says so
+  with a visible **"data may be incomplete"** banner — in the terminal, HTML,
+  Markdown, and LaTeX outputs — and the incomplete result is **not cached**.
+- Citation counts from different sources (Semantic Scholar vs OpenAlex) are
+  reconciled and flagged when they disagree by more than 10%.
+
 ---
 
 ## Configuration
@@ -246,12 +287,38 @@ Cache is stored in `.citationimpact/` in your project folder. You can view stati
 
 ---
 
+## Command-Line Mode (Scripting)
+
+Everything works without the interactive menu — great for scripts and cron jobs:
+
+```bash
+# Analyze a paper and write a grant-ready Markdown report
+./citation-impact analyze "Your Paper Title" --format markdown -o report.md
+
+# LaTeX section for a grant appendix, printed to stdout
+./citation-impact analyze "Your Paper Title" --format latex -o -
+
+# CSV of every citing paper / BibTeX of every citing paper
+./citation-impact analyze "Your Paper Title" -f csv -o citations.csv
+./citation-impact analyze "Your Paper Title" -f bibtex -o citations.bib
+
+# Override settings per run
+./citation-impact analyze "Your Paper Title" --max-citations 200 --data-source api --no-cache
+
+# Cache management
+./citation-impact cache list
+./citation-impact cache clear --days 30
+```
+
+Running `./citation-impact` with no arguments opens the interactive menu as always.
+
 ## Python API
 
-If you prefer scripting:
+If you prefer Python:
 
 ```python
 from citationimpact import analyze_paper_impact
+from citationimpact.export import export_report
 
 result = analyze_paper_impact(
     paper_title="Your Paper Title",
@@ -266,6 +333,10 @@ print(f"Top-tier venues: {result['venues']['top_tier_percentage']:.1f}%")
 
 for scholar in result['high_profile_scholars'][:5]:
     print(f"- {scholar['name']} (h={scholar['h_index']}) - {scholar['affiliation']}")
+
+# Export in any format: markdown, latex, csv, bibtex, json
+path = export_report(result, 'markdown')
+print(f"Report saved to {path}")
 ```
 
 ---
@@ -423,6 +494,8 @@ CitationImpact/
 │   │   └── _index.json         # Publication-based author matching index
 │   └── publications_cache/     # My Papers list (permanent until refresh)
 ├── citationimpact/             # Source code
+│   ├── cli.py                  # Non-interactive command-line interface
+│   ├── export.py               # Report exporters (Markdown/LaTeX/CSV/BibTeX/JSON)
 │   ├── core/                   # Analysis engine
 │   ├── clients/                # API clients
 │   │   ├── unified.py          # Semantic Scholar + OpenAlex
@@ -440,8 +513,22 @@ CitationImpact/
 ├── data/                       # Ranking datasets
 │   ├── university_rankings/    # QS, US News data
 │   └── venues_rankings/        # CORE, CCF, iCORE data
+├── tests/                      # Pytest suite (run: python -m pytest)
+```
+
+---
+
+## Development
+
+```bash
+pip install -r requirements.txt pytest
+
+# Run the test suite (plugin autoload disabled to avoid system plugin conflicts)
+PYTEST_DISABLE_PLUGIN_AUTOLOAD=1 python -m pytest
 ```
 
+Tests run automatically on GitHub Actions (Python 3.9–3.12) for every push and PR.
+
 ---
 
 ## Troubleshooting
@@ -544,8 +631,9 @@ Found a bug? Have an idea? Open an issue or PR!
 
 **Areas for contribution:**
 - Additional ranking sources (THE, ARWU, etc.)
-- Export formats (PDF, LaTeX, CSV)
+- More export formats (PDF, DOCX)
 - Web interface
+- Whole-career portfolio analysis (all papers at once)
 - Better citation context analysis
 
 ---

citation-impact

@@ -15,8 +15,8 @@ project_root = os.path.dirname(os.path.abspath(__file__))
 sys.path.insert(0, project_root)
 
 try:
-    from citationimpact.ui.app import main
-    main()
+    from citationimpact.cli import main
+    sys.exit(main())
 except ImportError as e:
     print("\n" + "="*70)
     print("ERROR: Required dependencies not installed!")

citationimpact/__init__.py

@@ -42,7 +42,7 @@
 # Config
 from .config import ConfigManager, get_config_manager
 
-__version__ = '1.2.0'
+__version__ = '1.4.0'
 __all__ = [
     # Main API
     'analyze_paper_impact',