ai-localize-reporting 2.0.1 → 2.0.4

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "ai-localize-reporting",
-  "version": "2.0.1",
-  "description": "Localization scan reporting: JSON, HTML, CLI summary",
+  "version": "2.0.4",
+  "description": "Localization scan reporting: JSON, HTML analytics dashboard and CLI summary",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md"
+  ],
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -12,8 +17,23 @@
       "require": "./dist/index.js"
     }
   },
+  "keywords": [
+    "i18n",
+    "localization",
+    "l10n",
+    "internationalization",
+    "ai-localize",
+    "reporting",
+    "html-report",
+    "cli",
+    "dashboard",
+    "translation-coverage"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "dependencies": {
-    "ai-localize-shared": "2.0.1"
+    "ai-localize-shared": "2.0.4"
   },
   "devDependencies": {
     "tsup": "^8.0.1",

package/src/cli-reporter.ts

@@ -1,29 +0,0 @@
-import type { Report } from "ai-localize-shared";
-
-export function printCliSummary(report: Report): void {
-  const lines = [
-    "",
-    "╔════════════════════════════════════════════════════╗",
-    "║          ai-localize-core  Report Summary      ║",
-    "╚════════════════════════════════════════════════════╝",
-    "",
-    `  Framework        : ${report.framework}`,
-    `  Timestamp        : ${report.timestamp}`,
-    `  Duration         : ${report.duration}ms`,
-    "",
-    "  ─── Localization ────────────────────────────────",
-    `  Files Scanned : ${report.filesScanned}`,
-    `  Hardcoded Texts  : ${report.hardcodedTexts}`,
-    `  Keys Generated   : ${report.localeKeysGenerated}`,
-    `  Missing Trans.   : ${report.missingTranslations}`,
-    `  Unused Keys      : ${report.unusedKeys}`,
-    "",
-    "  ─── Assets / CDN ────────────────────────────────",
-    `  Total Assets     : ${report.assets.totalAssets}`,
-    `  Uploaded Assets  : ${report.assets.uploadedAssets}`,
-    `  Replaced URLs    : ${report.assets.replacedUrls}`,
-    `Legacy CDN URLs  : ${report.assets.legacyCdnUrls}`,
-    "",
-  ];
-  console.log(lines.join('\n'));
-}

package/src/html-reporter.ts

@@ -1,336 +0,0 @@
-import type { Report } from "ai-localize-shared";
-import * as fs from "fs";
-import * as path from "path";
-import { ensureDir } from "ai-localize-shared";
-
-/**
- * Generates a comprehensive, self-contained HTML report file.
- *
- * @param report     - The report data object built by `buildReport()`
- * @param outputPath - Full path to the output HTML file
- *   e.g. `.ai-localize-reports/report.html`
- */
-export function generateHtmlReport(report: Report, outputPath: string): void {
-  ensureDir(path.dirname(outputPath));
-  const html = buildHtml(report);
-  fs.writeFileSync(outputPath, html, "utf-8");
-}
-
-// ─── Helpers ─────────────────────────────────────────────────────────────────
-
-/** Escapes a string for safe insertion into HTML. */
-function esc(s: string): string {
-  return s
-    .replace(/&/g, "&")
-    .replace(/</g, "<")
-    .replace(/>/g, ">")
-    .replace(/"/g, "&#34;");
-}
-
-type BadgeColor = "blue" | "red" | "green" | "orange" | "grey";
-
-function badge(text: string, color: BadgeColor): string {
-  return '<span class="badge badge-' + color + '">' + esc(text) + "</span>";
-}
-
-function sectionHeader(title: string, legend: string): string {
-  return (
-    '\n<div class="section-header">\n' +
-    "  <h2>" + title + "</h2>\n" +
-    '  <p class="legend">' + legend + "</p>\n" +
-    "</div>"
-  );
-}
-
-// ─── HTML builder ─────────────────────────────────────────────────────────────
-
-function buildHtml(report: Report): string {
-  const {
-    timestamp,
-    framework,
- duration,
- filesScanned,
-    hardcodedTexts,
-    localeKeysGenerated,
-    unusedKeys,
-    missingTranslations,
-    assets,
-    details,
-  } = report;
-
-  const scanDate = new Date(timestamp).toLocaleString();
-
-  // ── Hardcoded Texts ───────────────────────────────────────────────────────
-  const hardcodedRows = details.detectedTexts
-    .slice(0, 200)
-    .map(
-      (t) =>
-        "<tr>" +
-        "<td><code class=\"path\">" + esc(t.filePath.split("/").slice(-3).join("/")) + "</code></td>" +
-     '<td class="center">' + t.line + "</td>" +
-'<td class="text-cell">' + esc(t.text.slice(0, 80)) + (t.text.length > 80 ? "&#8230;" : "") + "</td>" +
-        '<td><code class="key">' + esc(t.suggestedKey) + "</code></td>" +
-        "<td>" + badge(t.context, "blue") + "</td>" +
-        "</tr>"
-    )
- .join("\n");
-
-  const hardcodedOverflow =
-    details.detectedTexts.length > 200
-      ? '<tr><td colspan="5" class="overflow-row">&#8230;and ' +
-        (details.detectedTexts.length - 200) +
-" more — run <code>ai-localize scan --output results.json</code> for the full list</td></tr>"
-      : "";
-
-  const hardcodedSection =
-  details.detectedTexts.length > 0
-      ? sectionHeader(
-          "&#128269; Hardcoded Texts Found (" + details.detectedTexts.length + ")",
-          "These are raw text strings discovered in your source files that are <strong>not yet wrapped</strong> in a translation call. " +
-         "Each row shows the file, line number, the text itself, the suggested locale key that would be generated, and the AST context. " +
- "Run <code>ai-localize extract</code> to generate locale files and " +
-       "<code>ai-localize full-migrate</code> to wrap them automatically."
-        ) +
-        "\n<table>\n" +
-     "<thead><tr><th>File (last 3 segments)</th><th>Line</th><th>Text</th><th>Suggested Key</th><th>Context</th></tr></thead>\n" +
-        "<tbody>" + hardcodedRows + hardcodedOverflow + "</tbody>\n</table>"
-      : sectionHeader(
-        "&#9989; Hardcoded Texts Found (0)",
-          "No hardcoded text was detected. All user-visible strings appear to be wrapped in translation calls already."
-        );
-
-  // ── Missing Translations ───────────────────────────────────────────────────
-  const missingRows = details.missingKeys
-    .map(
-      (e) =>
-        "<tr>" +
-        '<td><code class="key">' + esc(e.key) + "</code></td>" +
-        "<td>" + (e.language ? badge(e.language, "red") : "—") + "</td>" +
-        "<td>" + (e.filePath ? '<code class="path">' + esc(e.filePath) + "</code>" : "—") + "</td>" +
-  "<td>" + esc(e.message) + "</td>" +
-        "</tr>"
-    )
-    .join("\n");
-
-  const missingSection =
-    details.missingKeys.length > 0
-      ? sectionHeader(
-   "&#10060; Missing Translations (" + details.missingKeys.length + ")",
-          "These locale keys exist in the <strong>default language</strong> file but are <strong>absent</strong> in one or more target language files. " +
-     "A missing translation means your app will fall back to the default language (or show a blank / raw key) for users of that language. " +
-      "Ask your translators to fill in these entries. " +
-            "Running <code>ai-localize extract</code> now seeds all target language files with the source value so nothing is blank."
-        ) +
-        "\n<table>\n" +
-        "<thead><tr><th>Key</th><th>Missing In Language</th><th>Locale File</th><th>Details</th></tr></thead>\n" +
-        "<tbody>" + missingRows + "</tbody>\n</table>"
-      : sectionHeader(
-     "&#9989; Missing Translations (0)",
-   "All keys present in the default language are also present in every target language file."
-        );
-
-  // ── Unused Keys ────────────────────────────────────────────────────────────
-  const unusedRows = details.unusedKeysList
-    .map((key) => "<tr><td><code class=\"key\">" + esc(key) + "</code></td></tr>")
-    .join("\n");
-
-  const unusedSection =
-    details.unusedKeysList.length > 0
-      ? sectionHeader(
-     "&#128465;&#65039; Unused Keys (" + details.unusedKeysList.length + ")",
-          "These translation keys exist in your locale JSON files but are <strong>not referenced anywhere</strong> in the scanned source code. " +
-            "They are likely left over from removed features or renamed components. " +
-      "Unused keys bloat your locale bundles and can confuse translators. " +
-            "Run <code>ai-localize cleanup</code> to remove them (review the list carefully first)."
-        ) +
-  "\n<table>\n" +
-        "<thead><tr><th>Unused Key</th></tr></thead>\n" +
-        "<tbody>" + unusedRows + "</tbody>\n</table>"
-      : sectionHeader(
-          "&#9989; Unused Keys (0)",
-          "No unused translation keys detected. Your locale files are clean."
-  );
-
-  // ── Assets ─────────────────────────────────────────────────────────────────
-  const assetRows = details.assets
-    .map(
-      (a) =>
-        "<tr>" +
-        "<td><code class=\"path\">" + esc(a.localPath.split("/").slice(-3).join("/")) + "</code></td>" +
-        '<td><code class="key">' + esc(a.s3Key) + "</code></td>" +
-    "<td><code>" + esc(a.cloudfrontUrl) + "</code></td>" +
- '<td class="center">' + (a.size / 1024).toFixed(1) + " KB</td>" +
-        "<td>" + badge(a.contentType, "grey") + "</td>" +
-    "</tr>"
-    )
-    .join("\n");
-
-  const assetsSectionTitle =
-    "&#128230; Assets (" +
-    assets.totalAssets + " found &#183; " +
-    assets.uploadedAssets + " uploaded &#183; " +
-    assets.replacedUrls + " URLs replaced &#183; " +
-    assets.legacyCdnUrls + " legacy CDN URLs)";
-
-  const assetsLegend =
-    "<strong>Total assets</strong> = all static asset references found in source (images, fonts, CSS, JS). " +
-    "<strong>Uploaded</strong> = files pushed to S3/CloudFront in this run. " +
-    "<strong>Replaced URLs</strong> = legacy CDN references rewritten to the new CloudFront URL in source files. " +
-    "<strong>Legacy CDN URLs</strong> = old CDN references still present in source that have not yet been replaced — " +
-    "run <code>ai-localize replace-cdn</code> to fix them.";
-
-  const assetsSection =
-    sectionHeader(assetsSectionTitle, assetsLegend) +
-    (details.assets.length > 0
-      ? "\n<table>\n" +
-        "<thead><tr><th>Local Path</th><th>S3 Key</th><th>CloudFront URL</th><th>Size</th><th>Content Type</th></tr></thead>\n" +
-        "<tbody>" + assetRows + "</tbody>\n</table>"
-      : '\n<p class="empty-state">No assets were uploaded in this run. ' +
-        "Use <code>ai-localize upload-assets</code> to push static assets to S3/CloudFront.</p>");
-
-  // ── Hardcoded vs Keys Generated explainer ─────────────────────────────────
-  const diff = Math.abs(hardcodedTexts - localeKeysGenerated);
-  const diffExplainer =
-    hardcodedTexts !== localeKeysGenerated
-      ? '<div class="info-box">' +
-        "<strong>&#8505;&#65039; Why do Hardcoded Texts (" + hardcodedTexts + ") and Keys Generated (" + localeKeysGenerated + ") differ?</strong><br>" +
-        "<ul>" +
-        "<li><strong>Hardcoded Texts</strong> = total raw string occurrences across all files (same string in 5 files = 5).</li>" +
-        "<li><strong>Keys Generated</strong> = number of <em>unique</em> locale keys after deduplication. Identical strings share one key.</li>" +
-     "<li>The difference (" + diff + ") = duplicate strings consolidated into shared keys.</li>" +
-        "</ul>" +
-        "</div>"
-      : '<div class="info-box success-box">' +
-        "<strong>&#9989; Hardcoded Texts and Keys Generated match (" + hardcodedTexts + ").</strong> " +
-        "Every detected string maps to a unique locale key." +
-        "</div>";
-
-  // ── Summary cards ──────────────────────────────────────────────────────────
-  const statCard = (
-  num: number | string,
-    label: string,
-    hint: string,
-    colorClass: string
-  ): string =>
-    '<div class="stat-card">' +
-    '<div class="num ' + colorClass + '">' + num + "</div>" +
-    '<div class="lbl">' + label + "</div>" +
-    '<div class="hint">' + hint + "</div>" +
-    "</div>";
-
-  const summaryCards =
-    '<div class="stats">' +
-    statCard(filesScanned, "Files Scanned", "Source files inspected by AST scanner", "num-neutral") +
-    statCard(hardcodedTexts, "Hardcoded Texts", "Raw strings not yet wrapped in t()", hardcodedTexts > 0 ? "num-warn" : "num-ok") +
-    statCard(localeKeysGenerated, "Keys Generated", "Unique locale keys (deduplicated)", "num-ok") +
-    statCard(missingTranslations, "Missing Translations", "Keys absent in target languages", missingTranslations > 0 ? "num-err" : "num-ok") +
- statCard(unusedKeys, "Unused Keys", "Keys in locale files not used in code", unusedKeys > 0 ? "num-warn" : "num-ok") +
-    statCard(assets.totalAssets, "Assets Found", "Static asset references in source", "num-neutral") +
-    statCard(assets.uploadedAssets, "Assets Uploaded", "Pushed to S3/CloudFront", "num-ok") +
-    statCard(assets.legacyCdnUrls, "Legacy CDN URLs", "Old CDN refs not yet replaced", assets.legacyCdnUrls > 0 ? "num-warn" : "num-ok") +
-    "</div>";
-
-  // ── Full document ──────────────────────────────────────────────────────────
-  return "<!DOCTYPE html>\n" +
-    '<html lang="en">\n' +
-    "<head>\n" +
-    '<meta charset="UTF-8">\n' +
-    '<meta name="viewport" content="width=device-width, initial-scale=1.0">\n' +
-    "<title>ai-localize Report &#8212; " + scanDate + "</title>\n" +
-    "<style>\n" + CSS + "\n</style>\n" +
-    "</head>\n" +
-    "<body>\n" +
-    "<h1>&#127760; ai-localize Report <small>&#8212; " + esc(framework) + "</small></h1>\n" +
-    '<p class="meta">' +
-    "<strong>Generated:</strong> " + scanDate +
-    " &nbsp;|&nbsp; <strong>Duration:</strong> " + duration + "ms" +
-    " &nbsp;|&nbsp; <strong>Files Scanned:</strong> " + filesScanned +
-    "</p>\n" +
-    summaryCards + "\n" +
-    diffExplainer + "\n" +
-    hardcodedSection + "\n" +
-    missingSection + "\n" +
-    unusedSection + "\n" +
-    assetsSection + "\n" +
-    '<footer>Generated by <strong>ai-localize-core</strong> &#8212; deterministic, offline-capable i18n tooling</footer>\n' +
-    "</body>\n</html>";
-}
-
-// ─── Stylesheet ───────────────────────────────────────────────────────────────
-
-const CSS = `
-  *, *::before, *::after { box-sizing: border-box; }
-  body {
-    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
-    max-width: 1280px; margin: 0 auto; padding: 32px 24px;
-    background: #f0f2f5; color: #1a1a2e; line-height: 1.6;
-  }
-  h1 { font-size: 2rem; color: #0f3460; margin-bottom: 4px; }
-  h1 small { font-size: 1rem; font-weight: 400; color: #666; }
-  h2 { font-size: 1.2rem; color: #16213e; margin: 0 0 6px; }
-  .meta { color: #666; font-size: 0.9rem; margin-bottom: 32px; }
-  .meta strong { color: #333; }
-  .stats {
-    display: grid;
- grid-template-columns: repeat(auto-fit, minmax(155px, 1fr));
-    gap: 14px; margin-bottom: 32px;
-  }
-  .stat-card {
-    background: white; border-radius: 10px; padding: 18px 14px;
-    box-shadow: 0 2px 8px rgba(0,0,0,0.08); text-align: center;
-  }
-  .stat-card .num { font-size: 2rem; font-weight: 700; line-height: 1; }
-  .stat-card .lbl { color: #444; font-size: 0.82rem; margin-top: 6px; font-weight: 600; }
-  .stat-card .hint { color: #999; font-size: 0.75rem; margin-top: 3px; font-style: italic; }
-  .num-neutral { color: #0f3460; }
-  .num-ok  { color: #38a169; }
-  .num-warn { color: #d69e2e; }
-  .num-err  { color: #e53e3e; }
-  .section-header { margin: 40px 0 12px; }
-  .legend {
-    font-size: 0.875rem; color: #555;
-    background: #f8f9ff; border-left: 4px solid #0f3460;
-padding: 10px 14px; border-radius: 0 6px 6px 0; margin: 8px 0 14px;
-  }
-.legend code { background: #e8ebff; padding: 1px 5px; border-radius: 3px; font-size: 0.85em; }
-  table {
-    width: 100%; border-collapse: collapse; background: white;
-    border-radius: 10px; overflow: hidden;
-    box-shadow: 0 2px 8px rgba(0,0,0,0.08); margin-bottom: 8px;
-  }
-  th {
-    background: #0f3460; color: white; padding: 11px 14px;
-    text-align: left; font-size: 0.84rem; font-weight: 600;
-  }
-  td { padding: 9px 14px; border-bottom: 1px solid #f0f0f0; font-size: 0.84rem; vertical-align: top; }
-  tr:last-child td { border-bottom: none; }
-  tr:hover td { background: #f8f9ff; }
-  .center { text-align: center; }
-  .text-cell { max-width: 260px; word-break: break-word; }
-  code.path { color: #555; font-size: 0.81rem; }
-  code.key  { color: #0f3460; font-size: 0.81rem; }
-  .overflow-row { text-align: center; color: #888; font-style: italic; padding: 12px; }
-  .badge {
-    display: inline-block; padding: 2px 8px; border-radius: 10px;
-    font-size: 0.75rem; font-weight: 600; white-space: nowrap;
-  }
-  .badge-blue   { background: #ebf4ff; color: #2b6cb0; }
-  .badge-red    { background: #fff5f5; color: #c53030; }
-  .badge-green  { background: #f0fff4; color: #276749; }
-  .badge-orange { background: #fffaf0; color: #c05621; }
-  .badge-grey   { background: #f7f7f7; color: #555; }
-  .info-box {
-    background: #ebf8ff; border-left: 4px solid #3182ce;
-    padding: 14px 18px; border-radius: 0 8px 8px 0;
-    margin: 0 0 28px; font-size: 0.9rem;
-  }
-  .info-box ul { margin: 8px 0 0 18px; padding: 0; }
-  .info-box li { margin-bottom: 4px; }
-  .success-box { background: #f0fff4; border-left-color: #38a169; }
-  .empty-state { color: #888; font-style: italic; font-size: 0.88rem; padding: 8px 0; }
-  footer {
-margin-top: 48px; padding-top: 16px;
-    border-top: 1px solid #ddd; color: #aaa;
-    font-size: 0.8rem; text-align: center;
-  }
-`;

package/src/index.ts

@@ -1,3 +0,0 @@
-export * from "./report-builder.js";
-export * from "./html-reporter.js";
-export * from "./cli-reporter.js";

package/src/report-builder.ts

@@ -1,35 +0,0 @@
-import type { ScanResult, ValidationResult, Report, CloudFrontAsset } from "ai-localize-shared";
-
-export interface ReportInput {
-  scanResult: ScanResult;
-  validationResult?: ValidationResult;
-  uploadedAssets?: CloudFrontAsset[];
-  replacedUrls?: number;
-}
-
-export function buildReport(input: ReportInput): Report {
-  const { scanResult, validationResult, uploadedAssets = [], replacedUrls = 0 } = input;
-  return {
-    timestamp: new Date().toISOString(),
-    duration: scanResult.duration,
- framework: scanResult.framework,
-    filesScanned: scanResult.scannedFiles,
-    hardcodedTexts: scanResult.detectedTexts.length,
-    localeKeysGenerated: new Set(scanResult.detectedTexts.map((d) => d.suggestedKey)).size,
-    unusedKeys: validationResult?.warnings.filter((w) => w.type === "unused-key").length || 0,
-    missingTranslations: validationResult?.errors.filter((e) => e.type === "missing-key").length || 0,
-    languages: [],
-  assets: {
-      totalAssets: scanResult.assets.length,
-      uploadedAssets: uploadedAssets.length,
-      replacedUrls,
-      legacyCdnUrls: scanResult.legacyCdnUrls.length,
-    },
- details: {
-   detectedTexts: scanResult.detectedTexts,
-    missingKeys: validationResult?.errors.filter((e) => e.type === "missing-key") || [],
-      unusedKeysList: validationResult?.warnings.filter((w) => w.type === "unused-key").map((w) => w.key) || [],
-      assets: uploadedAssets,
- },
-  };
-}

package/tsconfig.json

@@ -1,6 +0,0 @@
-{
-  "extends": "../../tsconfig.base.json",
-  "compilerOptions": { "outDir": "./dist", "rootDir": "./src" },
-  "include": ["src/**/*"],
-  "exclude": ["node_modules", "dist"]
-}