# @foss.global/codefeed

a module to create codefeeds

# readme.md for @foss.global/codefeed

Generate an activity feed from a Gitea instance. Scans orgs and repos, retrieves commits since a configurable timestamp, enriches with tags, optional npm publish detection, and CHANGELOG snippets.

## Install

```bash
pnpm add @foss.global/codefeed
# or
npm i @foss.global/codefeed
```

Requires Node.js 18+ (global fetch/Request/Response) and ESM.

## Quick Start

```ts
import { CodeFeed } from '@foss.global/codefeed';

// Fetch commits since one week ago (default), no caching
const feed = new CodeFeed('https://code.example.com', 'gitea_token');
const commits = await feed.fetchAllCommitsFromInstance();
console.log(commits);
```

### With options

```ts
const thirtyDays = 30 * 24 * 60 * 60 * 1000;
const since = new Date(Date.now() - thirtyDays).toISOString();

const feed = new CodeFeed('https://code.example.com', 'gitea_token', since, {
  enableCache: true,          // keep results in memory
  cacheWindowMs: thirtyDays,  // trim cache to this window
  enableNpmCheck: true,       // check npm for published versions
  taggedOnly: false,          // return all commits (or only tagged)
  orgAllowlist: ['myorg'],    // only scan these orgs
  orgDenylist: ['archive'],   // skip these orgs
  repoAllowlist: ['myorg/app1', 'myorg/app2'], // only these repos
  repoDenylist: ['myorg/old-repo'],            // skip these repos
  untilTimestamp: new Date().toISOString(),    // optional upper bound
  verbose: true,               // print a short metrics summary
});

const commits = await feed.fetchAllCommitsFromInstance();
```

Each returned item follows this shape:

```ts
interface ICommitResult {
  baseUrl: string;
  org: string;
  repo: string;
  timestamp: string;        // ISO date
  hash: string;             // commit SHA
  commitMessage: string;
  tagged: boolean;          // commit is pointed to by a tag
  publishedOnNpm: boolean;  // only when npm check enabled and tag matches
  prettyAgoTime: string;    // human-readable diff
  changelog: string | undefined; // snippet for matching tag version
}
```

## Features

- Pagination for orgs, repos, commits, and tags (no missing pages)
- Retries with exponential backoff for 429/5xx and network errors
- CHANGELOG discovery with case variants (`CHANGELOG.md`, `changelog.md`, `docs/CHANGELOG.md`)
- Tag-to-version mapping based on tag names (`vX.Y.Z` → `X.Y.Z`)
- Optional npm publish detection via `@org/repo` package versions
- In-memory caching with window trimming and stable sorting
- Allow/deny filters for orgs and repos, optional time upper bound
- One-line metrics summary when `verbose: true`

## Environment

- Gitea base URL and an optional token with read access
- Node.js 18+ (global fetch)

## Testing

The repo contains:
- An integration test using a `GITEA_TOKEN` from `.nogit/` via `@push.rocks/qenv`.
- A mocked pagination test that does not require network.

Run tests:

```bash
pnpm test
```

For the integration test, ensure `GITEA_TOKEN` is provided (e.g., via `.nogit/` as used in `test/test.ts`).

## Notes

- When `taggedOnly` is enabled, the feed includes only commits associated with tags.
- `publishedOnNpm` is computed by matching the tag-derived version against the npm registry for `@org/repo`.
- For very large instances, consider using allowlists/denylists and enabling caching for incremental runs.

# changelog.md for @foss.global/codefeed

## 2025-09-14 - 1.7.2 - fix(core)
Stabilize pagination, tag mapping, changelog parsing, and HTTP retry/backoff; add tests and caching improvements

- Handle paginated orgs, repos, commits, and tags to avoid missing pages.
- Map tags to commit SHAs and extract version strings from tag names for changelog lookup and optional npm publish detection.
- Discover and parse repository CHANGELOG files from multiple candidate paths to extract per-version entries.
- Implement retries with exponential backoff for 429/5xx and network errors in fetchFunction.
- Add in-memory caching with window trimming, stable sorting, and optional tagged-only filtering.
- Include tests: mocked pagination & tag mapping test and integration test scaffolding using @push.rocks/tapbundle.

## 2025-04-25 - 1.7.1 - fix(CodeFeed)
Improve commit fetching concurrency and add tagged-only commit filtering along with updated documentation and tests

- Updated readme examples to clarify default and options usage, including caching and tagged-only filtering
- Increased non-exclusive concurrency from 5 to 20 in fetchAllCommitsFromInstance
- Added tagged-only filtering logic for both cached and non-cached commit results
- Modified tests to enable tagged-only mode and require npm check

## 2025-04-25 - 1.7.0 - feat(core)
Enhance commit fetching with caching, concurrency improvements, and dependency upgrades

- Updated development dependencies (@git.zone/tsbuild, @git.zone/tsbundle, @git.zone/tstest, @push.rocks/tapbundle, @types/node) and dependency versions
- Introduced optional caching options (enableCache, cacheWindowMs, enableNpmCheck) in the CodeFeed constructor to optimize commit retrieval
- Refactored commit fetching to use AsyncExecutionStack for controlled concurrency and improved performance
- Removed deprecated ts/codefeed.plugins.ts in favor of a consolidated plugins.ts module

## 2024-12-16 - 1.6.5 - fix(CodeFeed)
Fixed timestamp initialization and commit fetching timeframe

- Updated the lastRunTimestamp initialization default period from 24 hours to 7 days in CodeFeed constructor.
- Modified commit fetching logic to consider commits from the last 7 days instead of 24 hours in fetchRecentCommitsForRepo.

## 2024-12-14 - 1.6.4 - fix(core)
Refactor fetch logic to use a unified fetchFunction for API calls

- Consolidated API request logic in the CodeFeed class to use fetchFunction for improved maintainability.

## 2024-12-14 - 1.6.3 - fix(codefeed)
Refactor and fix formatting issues in the CodeFeed module

- Refactored various method format and spacing.
- Fixed error handling formatting for readability.
- Improved consistency in JSON handling for API responses.

## 2024-12-14 - 1.6.2 - fix(core)
Fix sorting order of tagged commits by timestamp

- Fixed the sorting order of commits to be by timestamp in descending order after filtering for tagged commits.

## 2024-12-14 - 1.6.1 - fix(docs)
Updated project metadata and expanded documentation for installation and usage.

- Updated description and keywords in package.json and npmextra.json.
- Significant expansion of the README.md with detailed installation, usage, and feature instructions.

## 2024-12-14 - 1.6.0 - feat(core)
Add changelog fetching and parsing functionality

- Implemented loadChangelogFromRepo to directly load the changelog from a Gitea repository.
- Introduced parsing functionality to extract specific version details from the loaded changelog.
- Updated CodeFeed class to utilize the changelog for version verification and commit processing.

## 2024-12-14 - 1.5.3 - fix(core)
Fix filtering logic for returning only tagged commits

- Ensure `allCommits` is filtered to only include commits with 'tagged' status before returning.

## 2024-12-14 - 1.5.2 - fix(core)
Ensure stability of core functionalities.


## 2024-12-14 - 1.5.1 - fix(core)
Refine logging format in CodeFeed class

- Modified console log format in fetchAllCommitsFromInstance method for better readability.

## 2024-12-14 - 1.5.0 - feat(core)
Refactor TypeScript interfaces and improve module exports

- Moved TypeScript interfaces to a dedicated file (ts/interfaces/index.ts).
- Updated import/export structure to improve code readability and maintainability.
- Enhanced the package.json to utilize a module exports field for better resolution.

## 2024-12-13 - 1.4.1 - fix(core)
Corrected log formatting for commit information output in CodeFeed

- Fixed formatting issue in commit log output within the CodeFeed class to ensure proper display of timestamps.

## 2024-12-13 - 1.4.0 - feat(CodeFeed)
Enhance commit results with human-readable time

- Integrated smarttime plugin to calculate and format timestamps into human-readable time.
- Updated dependencies in package.json to include smarttime and adjusted versions for existing packages.
- Improved fetchAllCommitsFromInstance method to display formatted time ago information for each commit.

## 2024-12-13 - 1.3.0 - feat(core)
Export CommitResult interface for external use.

- Changed CommitResult from a local interface to an exported interface, allowing for external usage and integration.

## 2024-12-13 - 1.2.1 - fix(core)
No changes detected


## 2024-12-13 - 1.2.0 - feat(core)
Add organization-level activity fetching and RSS parsing

- Integrated smartxml package for XML parsing.
- Implemented fetching of all organizations within a Gitea instance.
- Added functionality to check new activities in organization RSS feeds.
- Enhanced fetching logic to include repository commits and tags.

## 2024-12-13 - 1.1.0 - feat(core)
Add tracking of commits published on npm

- Introduced a check for published commits on npm using smartnpm.
- Enhanced fetchAllCommitsFromInstance to include 'publishedOnNpm' status in results.

## 2024-12-13 - 1.0.2 - fix(core)
Improve error handling in fetchRecentCommitsForRepo method

- Refined the console error message for better clarity.
- Updated the fetchRecentCommitsForRepo method to stop fetching when encountering a commit older than 24 hours.

## 2024-12-13 - 1.0.1 - initial release
Initial release of the project