Types/revisit

.github/workflows/main.yaml

@@ -7,90 +7,90 @@ on:
 jobs:
   test:
     runs-on: ubuntu-latest
-    
+
     strategy:
       matrix:
         node-version: [20.19.0, 21.x]
-    
+
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      
-    - name: Setup Node.js ${{ matrix.node-version }}
-      uses: actions/setup-node@v4
-      with:
-        node-version: ${{ matrix.node-version }}
-        cache: 'npm'
-        
-    - name: Install dependencies
-      run: npm ci
-      
-    - name: Build project
-      run: npm run build
-      
-    - name: Run tests
-      run: npm test
-      
-    - name: Run tests with coverage
-      run: npm run test:coverage
-      
-    - name: Publish Test Report
-      uses: ctrf-io/github-test-reporter@v1
-      with:
-        report-path: './ctrf/*.json'
-        summary-report: true
-        github-report: true
-        failed-report: true
-        flaky-report: true
-        insights-report: true
-        fail-rate-report: true
-        flaky-rate-report: true
-        slowest-report: true
-        previous-results-report: true
-        upload-artifact: true
-        artifact-name: ctrf-test-report-${{ matrix.node-version }}
-
-      env:
-        GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      if: always()
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build project
+        run: npm run build
+
+      - name: Run tests
+        run: npm test
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Publish Test Report
+        uses: ctrf-io/github-test-reporter@v1
+        with:
+          report-path: "./ctrf/*.json"
+          summary-report: true
+          github-report: true
+          failed-report: true
+          flaky-report: true
+          insights-report: true
+          fail-rate-report: true
+          flaky-rate-report: true
+          slowest-report: true
+          previous-results-report: true
+          upload-artifact: true
+          artifact-name: ctrf-test-report-${{ matrix.node-version }}
+
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        if: always()
 
   lint:
     runs-on: ubuntu-latest
-    
+
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20.19.0'
-        cache: 'npm'
-        
-    - name: Install dependencies
-      run: npm ci
-      
-    - name: Type check
-      run: npx tsc --noEmit
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.19.0"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Type check
+        run: npx tsc --noEmit
 
   security:
     runs-on: ubuntu-latest
-    
+
     steps:
-    - name: Checkout code
-      uses: actions/checkout@v4
-      
-    - name: Setup Node.js
-      uses: actions/setup-node@v4
-      with:
-        node-version: '20.19.0'
-        cache: 'npm'
-        
-    - name: Install dependencies
-      run: npm ci
-      
-    - name: Run security audit
-      run: npm audit --audit-level=moderate
-      
-    - name: Check for known vulnerabilities
-      run: npx audit-ci --moderate
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.19.0"
+          cache: "npm"
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run security audit
+        run: npm audit --audit-level=moderate
+
+      - name: Check for known vulnerabilities
+        run: npx audit-ci --moderate

.gitignore

@@ -3,5 +3,5 @@ final
 scripts
 coverage
 dist
-docs
-node_modules
+node_modules
+ctrf

.prettierignore

@@ -0,0 +1,10 @@
+dist/
+node_modules/
+coverage/
+templates/
+reports/
+community-reports/
+.github/
+.exlintrc.js
+README.md
+docs/

.prettierrc

@@ -0,0 +1,10 @@
+{
+  "semi": false,
+  "singleQuote": true,
+  "trailingComma": "es5",
+  "tabWidth": 2,
+  "useTabs": false,
+  "printWidth": 80,
+  "bracketSpacing": true,
+  "arrowParens": "avoid"
+}

README.md

@@ -27,188 +27,28 @@ Explore more <a href="https://www.ctrf.io/integrations">integrations</a>
 ## Installation
 
 ```sh
-npm install ctrf@0.0.13-next.0
+npm install ctrf
 ```
 
+## API reference
+
+See [API reference](./docs) for more details.
+
 ## TypeScript Types
 
 The library exports comprehensive TypeScript types for working with CTRF reports:
 
 ```typescript
-import type { Report, Test, Insights } from 'ctrf';
+import type { Report, Test, Insights } from "ctrf";
 
 function analyzeReport(report: Report): void {
   const flakyTests = report.results.tests.filter((test: Test) => test.flaky);
   const insights = report.insights as Insights;
-  
+
   console.log(`Flaky rate: ${insights?.flakyRate.current}`);
 }
 ```
 
-## API Reference
-
-### Reading Reports
-
-#### `readSingleReport(filePath: string): Report`
-
-Reads and parses a single CTRF report file from a specified file path.
-
-**Parameters:**
-- `filePath` - Path to the JSON file containing the CTRF report
-
-**Returns:** The parsed `Report` object
-
-**Throws:** Error if the file does not exist, is not valid JSON, or does not conform to the CTRF report structure
-
-**Example:**
-```typescript
-import { readSingleReport } from 'ctrf';
-
-const report = readSingleReport('./test-results.json');
-console.log(`Found ${report.results.summary.tests} tests`);
-```
-
-#### `readReportsFromDirectory(directoryPath: string): Report[]`
-
-Reads all CTRF report files from a given directory.
-
-**Parameters:**
-- `directoryPath` - Path to the directory containing JSON files
-
-**Returns:** Array of parsed `Report` objects
-
-**Throws:** Error if the directory does not exist or no valid CTRF reports are found
-
-**Example:**
-```typescript
-import { readReportsFromDirectory } from 'ctrf';
-
-const reports = readReportsFromDirectory('./test-reports/');
-console.log(`Loaded ${reports.length} reports`);
-```
-
-#### `readReportsFromGlobPattern(pattern: string): Report[]`
-
-Reads all CTRF report files matching a glob pattern.
-
-**Parameters:**
-- `pattern` - The glob pattern to match files (e.g., `ctrf/*.json`)
-
-**Returns:** Array of parsed `Report` objects
-
-**Throws:** Error if no valid CTRF reports are found
-
-**Example:**
-```typescript
-import { readReportsFromGlobPattern } from 'ctrf';
-
-const reports = readReportsFromGlobPattern('reports/**/*.json');
-console.log(`Found ${reports.length} reports matching pattern`);
-```
-
-### Merging Reports
-
-#### `mergeReports(reports: Report[]): Report`
-
-Merges multiple CTRF reports into a single report. Combines test results, summaries, and metadata from all input reports.
-
-**Parameters:**
-- `reports` - Array of CTRF report objects to be merged
-
-**Returns:** The merged CTRF report object
-
-**Throws:** Error if no reports are provided for merging
-
-**Example:**
-```typescript
-import { mergeReports, readReportsFromDirectory } from 'ctrf';
-
-const reports = readReportsFromDirectory('./test-reports/');
-const mergedReport = mergeReports(reports);
-console.log(`Merged ${reports.length} reports into one`);
-```
-
-### Report Enrichment & Insights
-
-#### `enrichReportWithInsights(currentReport: Report, previousReports?: Report[], baseline?: number | string): Report`
-
-Enriches a CTRF report with comprehensive insights by analyzing current and historical test data. Calculates metrics like flaky rates, failure rates, and performance trends.
-
-**Parameters:**
-- `currentReport` - The current CTRF report to enrich
-- `previousReports` - Array of historical CTRF reports (ordered newest to oldest, optional)
-- `baseline` - Optional baseline specification:
-  - `undefined`: Use most recent previous report (default)
-  - `number`: Use report at this index in previousReports array (0 = most recent)
-  - `string`: Use report with specific timestamp ID
-
-**Returns:** The current report enriched with insights
-
-**Example:**
-```typescript
-import { enrichReportWithInsights, readSingleReport } from 'ctrf';
-
-const currentReport = readSingleReport('./current-report.json');
-const previousReports = readReportsFromDirectory('./historical-reports/');
-
-const enrichedReport = enrichReportWithInsights(currentReport, previousReports);
-console.log(`Flaky rate: ${enrichedReport.insights?.flakyRate.current}`);
-```
-
-### Storing Previous Results
-
-#### `storePreviousResults(currentReport: Report, previousReports: Report[]): Report`
-
-Stores previous test run results in the current report's metadata. Extracts key metrics from historical reports for trend analysis.
-
-**Parameters:**
-- `currentReport` - The current CTRF report to enrich with previous results
-- `previousReports` - Array of previous CTRF reports to extract metrics from
-
-**Returns:** The current report with previousResults populated in the `extra` field
-
-**Example:**
-```typescript
-import { storePreviousResults, readSingleReport } from 'ctrf';
-
-const currentReport = readSingleReport('./current-report.json');
-const previousReports = readReportsFromDirectory('./historical-reports/');
-
-const reportWithHistory = storePreviousResults(currentReport, previousReports);
-console.log(`Stored ${reportWithHistory.extra?.previousResults?.length} previous results`);
-```
-
-### Utility Functions
-
-#### `isTestFlaky(test: Test): boolean`
-
-Determines if a test is flaky based on its retries and status.
-
-**Parameters:**
-- `test` - The CTRF test to evaluate
-
-**Returns:** `true` if the test is considered flaky, otherwise `false`
-
-#### `formatAsPercentage(ratio: number, decimals?: number): string`
-
-Formats a ratio (0-1) as a percentage string for display.
-
-**Parameters:**
-- `ratio` - The ratio to format (0-1)
-- `decimals` - Number of decimal places (default: 2)
-
-**Returns:** Formatted percentage string (e.g., "25.50%")
-
-#### `formatInsightsMetricAsPercentage(metric: InsightsMetric, decimals?: number): object`
-
-Formats an InsightsMetric as percentage strings for display.
-
-**Parameters:**
-- `metric` - The insights metric to format
-- `decimals` - Number of decimal places (default: 2)
-
-**Returns:** Object with formatted percentage strings for current, previous, and change values
-
 ## What is CTRF?
 
 CTRF is a universal JSON test report schema that addresses the lack of a standardized format for JSON test reports.