ai-localize-reporting 2.0.4 → 2.0.6

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # ai-localize-reporting
 
+## 2.0.6
+
+### Patch Changes
+
+- Add per-package README.md files so each package displays documentation on npmjs.com
+- Update README version badge to 2.0.6
+
+## 2.0.5
+
+### Patch Changes
+
+- **Bug fix — `report` crashed with `RangeError: Invalid count value`**: The CLI reporter
+  computed translation coverage as `(totalUniqueKeys - missingKeys.length) / totalUniqueKeys * 100`.
+  Because `missingKeys` are recorded per-language (e.g. 5 unique keys × 2 target languages = 10
+  entries), coverage went negative when all keys were untranslated, causing `String.prototype.repeat()`
+  to throw. Three fixes applied to `printCliSummary()`:
+  - Coverage now counts **distinct** missing key names (`new Set(missingKeys.map(mk => mk.key)).size`)
+    instead of raw array length, giving the correct per-key missing count.
+  - `coveragePct` is clamped to `[0, 100]` with `Math.max(0, Math.min(100, …))`.
+  - `progressBar()`, `miniBar()`, and the `renderTable()` center-align branch all guard
+    `filled`, `empty`, and padding values with `Math.max(0, …)` to prevent negative repeats.
+  (`packages/reporting/src/cli-reporter.ts`)
+
+## 2.0.4
+
+### Patch Changes
+
+- Updated dependencies
+  - ai-localize-shared@2.0.4
+
 ## 2.0.3
 
 ### Patch Changes

package/README.md

@@ -0,0 +1,77 @@
+# ai-localize-reporting
+
+> HTML analytics dashboard + rich CLI terminal reporter for the [ai-localize-core](https://github.com/ai-localize/ai-localize-core) platform.
+
+[![npm version](https://img.shields.io/npm/v/ai-localize-reporting.svg)](https://www.npmjs.com/package/ai-localize-reporting)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
+---
+
+## What it does
+
+- **`buildReport()`** — assembles a `Report` object from scan + validation results
+- **`generateHtmlReport()`** — writes a self-contained, interactive HTML analytics dashboard
+- **`printCliSummary()`** — prints a rich structured terminal summary with ANSI colour, bar charts, and tables
+
+## Installation
+
+```bash
+npm install ai-localize-reporting
+```
+
+## Usage
+
+```ts
+import { buildReport, generateHtmlReport, printCliSummary } from 'ai-localize-reporting';
+
+const report = buildReport({
+  scanResult,
+  validationResult,
+  uploadedAssets,   // optional
+  replacedUrls,     // optional
+});
+
+// Write HTML dashboard
+generateHtmlReport(report, './.reports/report.html');
+
+// Print terminal summary
+printCliSummary(report);
+```
+
+## HTML report features
+
+- **Sticky sidebar navigation** with active section highlighting and alert indicators
+- **Light / dark theme** — system preference, `localStorage`, `Cmd+D` / `Ctrl+D` shortcut
+- **9 stat cards** — top-border colour coding (ok / warn / error / info)
+- **SVG donut chart** — translation coverage % (no external dependencies)
+- **Bar charts** — keys by namespace, texts by AST context
+- **Interactive tables** — search, sort, CSV/JSON export, pagination (50 rows/page)
+- **AI Insights** (100% deterministic) — duplicate text detection, translation inconsistency, unused keys, namespace cleanup hints
+- **Export panel** — full report JSON, summary CSV, print/PDF
+- **Responsive + accessible** — ARIA roles, keyboard navigation, mobile sidebar
+
+## CLI terminal summary features
+
+- **Zero new dependencies** — all ANSI codes inlined; `NO_COLOR` env var respected
+- **Full-width banner** with centred title
+- **9 stat lines** with status dots (green/yellow/red) and contextual hints
+- **Coverage progress bar** (24-block, colour-coded)
+- **Top-files bar chart**, missing-translations ranking, namespace distribution, AST context distribution
+- **AI Insights block** and recommended next steps
+- **Responsive width** — reads `process.stdout.columns`, caps at 120 chars
+
+## Coverage calculation (v2.0.5+)
+
+Coverage % is computed using **distinct missing key names** (not raw per-language count), so it correctly reflects the fraction of unique keys that have been translated:
+
+```
+coverage = (totalUniqueKeys - distinctMissingKeys) / totalUniqueKeys × 100
+```
+
+---
+
+## Part of ai-localize-core
+
+Install the CLI for the complete toolset: `npm install -g ai-localize-cli`
+
+MIT © ai-localize-core contributors

package/dist/index.js

@@ -1697,17 +1697,18 @@ function badge2(text, ok) {
   return ok ? c("bgGreen", c("black", ` ${text} `)) : c("bgRed", c("white", ` ${text} `));
 }
 function miniBar(value, max, width = 20, color = "cyan") {
-  const filled = max > 0 ? Math.round(value / max * width) : 0;
+  const filled = max > 0 ? Math.max(0, Math.min(width, Math.round(value / max * width))) : 0;
   const empty = width - filled;
   const bar = c(color, "\u2588".repeat(filled)) + dim("\u2591".repeat(empty));
   return "[" + bar + "]";
 }
 function progressBar(pct, width = 24) {
-  const filled = Math.round(pct / 100 * width);
+  const safePct = Math.max(0, Math.min(100, pct));
+  const filled = Math.max(0, Math.min(width, Math.round(safePct / 100 * width)));
   const empty = width - filled;
   let color = "brightGreen";
-  if (pct < 50) color = "brightRed";
-  else if (pct < 80) color = "brightYellow";
+  if (safePct < 50) color = "brightRed";
+  else if (safePct < 80) color = "brightYellow";
   const bar = c(color, "\u2588".repeat(filled)) + dim("\u2591".repeat(empty));
   return "[" + bar + "]";
 }
@@ -1738,8 +1739,10 @@ function renderTable(columns, rows) {
       if (isHeader) s = bold(strip(s));
       if (col?.align === "right") s = padStart(s, w);
       else if (col?.align === "center") {
-        const p = Math.floor((w - visLen(s)) / 2);
-        s = " ".repeat(p) + s + " ".repeat(w - visLen(s) - p);
+        const visibleLen = visLen(s);
+        const p = Math.max(0, Math.floor((w - visibleLen) / 2));
+        const q = Math.max(0, w - visibleLen - p);
+        s = " ".repeat(p) + s + " ".repeat(q);
       } else {
         s = padEnd(s, w);
       }
@@ -1760,7 +1763,8 @@ function renderTable(columns, rows) {
 function computeCliInsights(report) {
   const { details } = report;
   const totalUniqueKeys = new Set(details.detectedTexts.map((d) => d.suggestedKey)).size;
-  const coveragePct = totalUniqueKeys > 0 ? Math.round((totalUniqueKeys - details.missingKeys.length) / totalUniqueKeys * 100) : 100;
+  const missingUniqueKeys = new Set(details.missingKeys.map((mk) => mk.key)).size;
+  const coveragePct = totalUniqueKeys > 0 ? Math.max(0, Math.min(100, Math.round((totalUniqueKeys - missingUniqueKeys) / totalUniqueKeys * 100))) : 100;
   const textMap = /* @__PURE__ */ new Map();
   for (const dt of details.detectedTexts) {
     const t = dt.text.trim();

package/dist/index.mjs

@@ -1659,17 +1659,18 @@ function badge2(text, ok) {
   return ok ? c("bgGreen", c("black", ` ${text} `)) : c("bgRed", c("white", ` ${text} `));
 }
 function miniBar(value, max, width = 20, color = "cyan") {
-  const filled = max > 0 ? Math.round(value / max * width) : 0;
+  const filled = max > 0 ? Math.max(0, Math.min(width, Math.round(value / max * width))) : 0;
   const empty = width - filled;
   const bar = c(color, "\u2588".repeat(filled)) + dim("\u2591".repeat(empty));
   return "[" + bar + "]";
 }
 function progressBar(pct, width = 24) {
-  const filled = Math.round(pct / 100 * width);
+  const safePct = Math.max(0, Math.min(100, pct));
+  const filled = Math.max(0, Math.min(width, Math.round(safePct / 100 * width)));
   const empty = width - filled;
   let color = "brightGreen";
-  if (pct < 50) color = "brightRed";
-  else if (pct < 80) color = "brightYellow";
+  if (safePct < 50) color = "brightRed";
+  else if (safePct < 80) color = "brightYellow";
   const bar = c(color, "\u2588".repeat(filled)) + dim("\u2591".repeat(empty));
   return "[" + bar + "]";
 }
@@ -1700,8 +1701,10 @@ function renderTable(columns, rows) {
       if (isHeader) s = bold(strip(s));
       if (col?.align === "right") s = padStart(s, w);
       else if (col?.align === "center") {
-        const p = Math.floor((w - visLen(s)) / 2);
-        s = " ".repeat(p) + s + " ".repeat(w - visLen(s) - p);
+        const visibleLen = visLen(s);
+        const p = Math.max(0, Math.floor((w - visibleLen) / 2));
+        const q = Math.max(0, w - visibleLen - p);
+        s = " ".repeat(p) + s + " ".repeat(q);
       } else {
         s = padEnd(s, w);
       }
@@ -1722,7 +1725,8 @@ function renderTable(columns, rows) {
 function computeCliInsights(report) {
   const { details } = report;
   const totalUniqueKeys = new Set(details.detectedTexts.map((d) => d.suggestedKey)).size;
-  const coveragePct = totalUniqueKeys > 0 ? Math.round((totalUniqueKeys - details.missingKeys.length) / totalUniqueKeys * 100) : 100;
+  const missingUniqueKeys = new Set(details.missingKeys.map((mk) => mk.key)).size;
+  const coveragePct = totalUniqueKeys > 0 ? Math.max(0, Math.min(100, Math.round((totalUniqueKeys - missingUniqueKeys) / totalUniqueKeys * 100))) : 100;
   const textMap = /* @__PURE__ */ new Map();
   for (const dt of details.detectedTexts) {
     const t = dt.text.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ai-localize-reporting",
-  "version": "2.0.4",
+  "version": "2.0.6",
   "description": "Localization scan reporting: JSON, HTML analytics dashboard and CLI summary",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -33,7 +33,7 @@
     "node": ">=18.0.0"
   },
   "dependencies": {
-    "ai-localize-shared": "2.0.4"
+    "ai-localize-shared": "2.0.6"
   },
   "devDependencies": {
     "tsup": "^8.0.1",