@foss.global/codefeed 1.6.5 → 1.8.0

package/dist_ts/interfaces/index.d.ts

@@ -1,3 +1,5 @@
+import type { ICodefeedCommitResult } from '@foss.global/interfaces';
+export type { ICodefeedCommitResult } from '@foss.global/interfaces';
 export interface IRepositoryOwner {
     login: string;
 }
@@ -17,6 +19,7 @@ export interface ICommit {
     commit: ICommitDetail;
 }
 export interface ITag {
+    name?: string;
     commit?: {
         sha?: string;
     };
@@ -24,15 +27,30 @@ export interface ITag {
 export interface IRepoSearchResponse {
     data: IRepository[];
 }
-export interface ICommitResult {
-    baseUrl: string;
-    org: string;
-    repo: string;
-    timestamp: string;
-    hash: string;
-    commitMessage: string;
-    tagged: boolean;
-    publishedOnNpm: boolean;
-    prettyAgoTime: string;
-    changelog: string | undefined;
+export interface ICommitResult extends ICodefeedCommitResult {
+}
+export interface ICodeFeedTagInfo {
+    shas: Set<string>;
+    map: Map<string, string>;
+}
+export interface ICodeFeedProvider {
+    listOrganizations(): Promise<string[]>;
+    listRepositoriesForOrg(org: string): Promise<IRepository[]>;
+    getLatestCommitForRepo(owner: string, repo: string): Promise<ICommit | undefined>;
+    listCommitsForRepo(owner: string, repo: string, sinceTimestamp?: string): Promise<ICommit[]>;
+    listTagsForRepo(owner: string, repo: string): Promise<ICodeFeedTagInfo>;
+    readChangelogForRepo(owner: string, repo: string): Promise<string>;
+}
+export interface ICodeFeedOptions {
+    enableCache?: boolean;
+    cacheWindowMs?: number;
+    enableNpmCheck?: boolean;
+    taggedOnly?: boolean;
+    orgAllowlist?: string[];
+    orgDenylist?: string[];
+    repoAllowlist?: string[];
+    repoDenylist?: string[];
+    untilTimestamp?: string;
+    verbose?: boolean;
+    provider?: ICodeFeedProvider;
 }

package/dist_ts/plugins.d.ts

@@ -0,0 +1,7 @@
+import * as interfaces from './interfaces/index.js';
+export { interfaces, };
+import * as smarttime from '@push.rocks/smarttime';
+import * as lik from '@push.rocks/lik';
+export type TNpmRegistry = import('@push.rocks/smartnpm').NpmRegistry;
+export declare const getSmartnpm: () => Promise<typeof import("@push.rocks/smartnpm")>;
+export { smarttime, lik, };

package/dist_ts/plugins.js

@@ -0,0 +1,9 @@
+// module
+import * as interfaces from './interfaces/index.js';
+export { interfaces, };
+// @push.rocks
+import * as smarttime from '@push.rocks/smarttime';
+import * as lik from '@push.rocks/lik';
+export const getSmartnpm = async () => import('@push.rocks/smartnpm');
+export { smarttime, lik, };
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoicGx1Z2lucy5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL3BsdWdpbnMudHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUEsU0FBUztBQUNULE9BQU8sS0FBSyxVQUFVLE1BQU0sdUJBQXVCLENBQUM7QUFFcEQsT0FBTyxFQUNMLFVBQVUsR0FDWCxDQUFBO0FBRUQsY0FBYztBQUNkLE9BQU8sS0FBSyxTQUFTLE1BQU0sdUJBQXVCLENBQUM7QUFDbkQsT0FBTyxLQUFLLEdBQUcsTUFBTSxpQkFBaUIsQ0FBQztBQUl2QyxNQUFNLENBQUMsTUFBTSxXQUFXLEdBQUcsS0FBSyxJQUFJLEVBQUUsQ0FBQyxNQUFNLENBQUMsc0JBQXNCLENBQUMsQ0FBQztBQUV0RSxPQUFPLEVBQ0wsU0FBUyxFQUNULEdBQUcsR0FDSixDQUFBIn0=

package/license.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Task Venture Capital GmbH
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foss.global/codefeed",
-  "version": "1.6.5",
+  "version": "1.8.0",
   "private": false,
   "description": "The @foss.global/codefeed module is designed for generating feeds from Gitea repositories, enhancing development workflows by processing commit data and repository activities.",
   "exports": {
@@ -11,18 +11,19 @@
   "author": "Task Venture Capital GmbH",
   "license": "MIT",
   "devDependencies": {
-    "@git.zone/tsbuild": "^2.1.25",
-    "@git.zone/tsbundle": "^2.0.5",
-    "@git.zone/tsrun": "^1.2.46",
-    "@git.zone/tstest": "^1.0.44",
-    "@push.rocks/tapbundle": "^5.0.15",
-    "@types/node": "^22.10.2"
+    "@git.zone/tsbuild": "^4.4.2",
+    "@git.zone/tsbundle": "^2.11.0",
+    "@git.zone/tsrun": "^2.0.4",
+    "@git.zone/tstest": "^3.6.6",
+    "@types/node": "^26.0.0"
   },
   "dependencies": {
-    "@push.rocks/qenv": "^6.1.0",
-    "@push.rocks/smartnpm": "^2.0.4",
+    "@foss.global/interfaces": "^0.2.0",
+    "@push.rocks/lik": "^6.2.2",
+    "@push.rocks/qenv": "^6.1.3",
+    "@push.rocks/smartnpm": "^2.0.6",
     "@push.rocks/smarttime": "^4.1.1",
-    "@push.rocks/smartxml": "^1.0.8"
+    "@push.rocks/smartxml": "^1.1.1"
   },
   "repository": {
     "type": "git",
@@ -41,8 +42,9 @@
     "dist_ts_web/**/*",
     "assets/**/*",
     "cli.js",
-    "npmextra.json",
-    "readme.md"
+    ".smartconfig.json",
+    "readme.md",
+    "license.md"
   ],
   "keywords": [
     "codefeed",
@@ -58,7 +60,7 @@
     "version control"
   ],
   "scripts": {
-    "test": "(tstest test/ --web)",
+    "test": "(tstest test/ --verbose)",
     "build": "(tsbuild tsfolders --web --allowimplicitany)",
     "buildDocs": "(tsdoc)"
   }

package/readme.md

@@ -1,130 +1,126 @@
-```markdown
 # @foss.global/codefeed
 
-A module for creating feeds for code development.
+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
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
 
-To install the `@foss.global/codefeed` package, you can run the following npm command in your project directory:
+## Install
 
 ```bash
-npm install @foss.global/codefeed
+pnpm add @foss.global/codefeed
 ```
 
-Ensure that you have a compatible version of Node.js installed and that your project is set up to support ECMAScript modules. The `@foss.global/codefeed` module uses ESM syntax.
-
-## Usage
-
-The `@foss.global/codefeed` package is designed to help developers generate feeds for code developments, specifically targeting Gitea repositories. It fetches and processes commit data, changelogs, and repository activities for further analysis or visualization. Here, we'll delve into how you can utilize the different features of the `CodeFeed` class.
+Requires Node.js 18+ (global fetch/Request/Response) and ESM.
 
-### Setting Up CodeFeed
+## Quick Start
 
-To get started, import the `CodeFeed` class from the module:
-
-```typescript
+```ts
 import { CodeFeed } from '@foss.global/codefeed';
-```
-
-Then, create an instance of `CodeFeed`. You'll need the base URL of your Gitea instance and optionally an API token if your repositories require authentication:
 
-```typescript
-const codeFeed = new CodeFeed('https://your-gitea-instance-url.com', 'your-api-token');
+// 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);
 ```
 
-The constructor can also accept a `lastRunTimestamp` which indicates the last time a sync was performed. If not provided, it defaults to 24 hours prior to the current time.
-
-### Fetching Commits
-
-One of the core functionalities of CodeFeed is fetching commits from a Gitea instance. By calling `fetchAllCommitsFromInstance`, you can retrieve commits across multiple repositories:
-
-```typescript
-(async () => {
-  try {
-    const commits = await codeFeed.fetchAllCommitsFromInstance();
-    console.log(commits);
-  } catch (error) {
-    console.error('An error occurred while fetching commits:', error);
-  }
-})();
+### 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();
 ```
 
-This method scans all organizations and repositories, filters commits tagged within the last 24 hours, and enriches them with metadata like changelogs or npm publication status.
+Advanced callers can provide a custom `ICodeFeedProvider` through the constructor options. The default provider keeps the existing Gitea HTTP behavior, while the provider contract lets adapters supply organizations, repositories, commits, tags, and changelog content from another backend.
+
+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
+}
+```
 
-Each commit object in the resulting array conforms to the `ICommitResult` interface, containing details such as:
-- `baseUrl`
-- `org`
-- `repo`
-- `timestamp`
-- `hash`
-- `commitMessage`
-- `tagged` (boolean)
-- `publishedOnNpm` (boolean)
-- `prettyAgoTime` (human-readable relative time)
-- `changelog` (text from the `changelog.md` associated with a commit)
+The canonical public result contract is exported as `ICodefeedCommitResult` from `@foss.global/interfaces`. `@foss.global/codefeed/interfaces` keeps `ICommitResult` as a package-local alias for that contract.
 
-### Understanding the Data Fetch Process
+## Features
 
-#### Fetching Organizations
+- 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`
 
-The `fetchAllOrganizations` method collects all organizations within the Gitea instance:
+## Environment
 
-```typescript
-const organizations = await codeFeed.fetchAllOrganizations();
-console.log('Organizations:', organizations);
-```
+- Gitea base URL and an optional token with read access
+- Node.js 18+ (global fetch)
 
-This method interacts with the Gitea API to pull organization names, aiding further requests that require organization context.
+## Testing
 
-#### Fetching Repositories
+The repo contains:
+- An opt-in integration test using a `GITEA_TOKEN` from `.nogit/` via `@push.rocks/qenv`.
+- A mocked pagination test that does not require network.
 
-Repositories under these organizations can be retrieved using `fetchAllRepositories`:
+Run tests:
 
-```typescript
-const repositories = await codeFeed.fetchAllRepositories();
-console.log('Repositories:', repositories);
+```bash
+pnpm test
 ```
 
-Here, filtering by organization can help narrow down the scope further when dealing with large instances.
-
-#### Fetching Tags and Commits
+For the integration test, set `CODEFEED_RUN_LIVE=true` and ensure `GITEA_TOKEN` is provided, e.g. via `.nogit/` as used by `test/test.live.node.ts`.
 
-To handle repository-specific details, use:
+## Notes
 
-- `fetchTags(owner: string, repo: string)`: Appropriately handles paginated tag data within a repository.
-  
-- `fetchRecentCommitsForRepo(owner: string, repo: string)`: Gathers commit data specific to the past 24 hours for a given repository.
+- 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.
 
-```typescript
-const tags = await codeFeed.fetchTags('orgName', 'repoName');
-const recentCommits = await codeFeed.fetchRecentCommitsForRepo('orgName', 'repoName');
+## License and Legal Information
 
-console.log('Tags:', tags);
-console.log('Recent Commits:', recentCommits);
-```
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
 
-### Changelog Integration
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
 
-Loading changelog content from a repository is integrated into the flow with `loadChangelogFromRepo`. This can be accessed when processing specific commits:
+### Trademarks
 
-```typescript
-await codeFeed.loadChangelogFromRepo('org', 'repo');
-const changelog = codeFeed.getChangelogForVersion('1.0.0');
-console.log('Changelog for version 1.0.0:', changelog);
-```
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
 
-### Reacting to Repository Activity
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
 
-The method `hasNewActivity` checks for recent changes within an organization or a repository. This is particularly useful for setting up alerting systems or continuous integration triggers:
+### Company Information
 
-```typescript
-const hasActivity = await codeFeed.hasNewActivity({ orgName: 'orgName', repoName: 'repoName' });
-console.log('New activity detected:', hasActivity);
-```
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
 
-### Conclusion
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
 
-The `@foss.global/codefeed` module provides robust capabilities for extracting and managing feed data related to code developments in Gitea environments. Through systematic setup and leveraging API-driven methods, it becomes a valuable tool for developers aiming to keep track of software progress and changes efficiently. The integration hooks like changelog and npm verification further enrich its utility, offering consolidated insights into each commit's journey from codebase to published package.
-
-Explore integrating these capabilities into your development workflows to enhance tracking, deployment pipelines, or analytics systems within your projects. Remember to always handle API tokens securely and adhere to best practices when managing access to repository resources. Stay updated on any changes or enhancements to this module for further feature exposures or bug fixes. Happy coding!
-```
-undefined
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@foss.global/codefeed',
-  version: '1.6.5',
+  version: '1.8.0',
   description: 'The @foss.global/codefeed module is designed for generating feeds from Gitea repositories, enhancing development workflows by processing commit data and repository activities.'
 }