fallow-code-scan 0.1.0

package/README.md

@@ -0,0 +1,35 @@
+# Code Scan
+
+Local web dashboard for Fallow code analysis reports.
+
+## Usage
+
+Run it from the root of the project you want to analyze:
+
+```sh
+npx fallow-code-scan
+```
+
+Open the printed local URL, then press **Refresh** to run a scan.
+
+By default Code Scan listens on `127.0.0.1:5179`. Override it with environment
+variables when needed:
+
+```sh
+HOST=0.0.0.0 PORT=5180 npx fallow-code-scan
+```
+
+## What It Shows
+
+- Blocking Findings from Fallow checks
+- Refactoring Suggestions from maintainability analysis
+- Code Health metrics and lowest maintainability files
+- Copyable text reports for sharing findings
+
+## Requirements
+
+- Node.js 18 or newer
+- A JavaScript or TypeScript project supported by Fallow
+
+Fallow is installed as a package dependency, so users do not need to install it
+separately.

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "fallow-code-scan",
+  "version": "0.1.0",
+  "description": "Local web dashboard for Fallow code analysis reports.",
+  "main": "src/server.js",
+  "bin": {
+    "code-scan": "src/start.js",
+    "fallow-code-scan": "src/start.js"
+  },
+  "files": [
+    "public",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "dev": "node src/start.js",
+    "test": "node --test test/*.test.js",
+    "pack:dry": "npm pack --dry-run"
+  },
+  "keywords": [
+    "fallow",
+    "code-analysis",
+    "dashboard",
+    "maintainability",
+    "dead-code"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "fallow": "2.91.0",
+    "lucide": "1.21.0"
+  }
+}

package/public/app-copy.js

@@ -0,0 +1,31 @@
+{
+  async function writeText(text) {
+    if (copyWithTextarea(text)) return;
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      await navigator.clipboard.writeText(text);
+      return;
+    }
+    throw new Error("Copy is not available in this browser.");
+  }
+
+  function copyWithTextarea(text) {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.setAttribute("readonly", "");
+    textarea.className = "copy-buffer";
+    document.body.appendChild(textarea);
+    textarea.focus();
+    textarea.select();
+    textarea.setSelectionRange(0, textarea.value.length);
+
+    try {
+      return document.execCommand("copy");
+    } finally {
+      textarea.remove();
+    }
+  }
+
+  window.codeScanCopy = {
+    writeText
+  };
+}

package/public/app-findings.js

@@ -0,0 +1,54 @@
+{
+  function renderSection(section, escapeHtml) {
+    const node = document.createElement("details");
+    node.className = "finding-group-static";
+    node.open = true;
+    node.innerHTML = `
+      <summary>
+        <i class="finding-chevron chevron-open" data-lucide="chevron-down" aria-hidden="true"></i>
+        <i class="finding-chevron chevron-closed" data-lucide="chevron-right" aria-hidden="true"></i>
+        <i class="finding-type-icon" data-lucide="${typeIcon(section.id)}" aria-hidden="true"></i>
+        <h3>${escapeHtml(section.label)}</h3>
+      </summary>
+      <ul>${recordsHtml(section.records, escapeHtml)}</ul>
+    `;
+    return node;
+  }
+
+  function recordsHtml(records, escapeHtml) {
+    const html = records.map((record) => `
+      <li class="finding-record">
+        <div>
+          <span class="item-title">${escapeHtml(record.title)}</span>
+          <span class="item-detail">${escapeHtml(record.detail)}</span>
+        </div>
+      </li>
+    `).join("");
+    return html || "<li><span>No samples included.</span></li>";
+  }
+
+  function typeIcon(sectionId) {
+    const icons = {
+      boundary_violations: "shield-alert",
+      circular_dependencies: "refresh-ccw",
+      complexity_findings: "gauge",
+      duplicate_exports: "copy-x",
+      duplicated_code: "files",
+      re_export_cycles: "repeat-2",
+      stale_suppressions: "message-square-warning",
+      unlisted_dependencies: "package-plus",
+      unresolved_imports: "import",
+      unused_class_members: "square-minus",
+      unused_dependencies: "package-minus",
+      unused_enum_members: "list-minus",
+      unused_exports: "package-x",
+      unused_files: "file-x-2",
+      unused_types: "braces"
+    };
+    return icons[sectionId] || "circle-x";
+  }
+
+  window.codeScanFindings = {
+    renderSection
+  };
+}

package/public/app-format.js

@@ -0,0 +1,148 @@
+{
+  const STATUS_LABELS = {
+    failed: "Failed",
+    idle: "Idle",
+    ready: "Ready",
+    running: "Scanning"
+  };
+
+  function effortTone(effort) {
+    if (effort === "high") return "critical";
+    if (effort === "medium") return "warn";
+    if (effort === "low") return "good";
+    return "neutral";
+  }
+
+  function formatNumber(value) {
+    return new Intl.NumberFormat().format(Number(value) || 0);
+  }
+
+  function formatRecommendation(recommendation) {
+    return String(recommendation || "")
+      .replace(/\((\d+) LOC\)/g, "($1 lines of code)")
+      .replace(/(\d+) dependents amplify every change/g, "$1 files depend on it")
+      .replace(/fan-in/g, "incoming references")
+      .replace(/fan-out/g, "outgoing dependencies");
+  }
+
+  function thresholdTone(value, goodMax, warnMax) {
+    const number = Number(value);
+    if (number <= goodMax) return "good";
+    if (number <= warnMax) return "warn";
+    return "critical";
+  }
+
+  function formatReportText(report) {
+    const lines = [
+      "Code Scan",
+      `Generated: ${report.generatedAt}`,
+      `Status: ${report.status}`,
+      `Blocking findings: ${report.hardFindings.count}`,
+      `Refactoring suggestions: ${report.health.targets.length}`,
+      "",
+      "Blocking findings"
+    ];
+
+    appendCheckSections(lines, report.hardFindings.sections);
+    appendTargets(lines, report.health.targets, true);
+    return `${lines.join("\n")}\n`;
+  }
+
+  function formatBlockingFindingsText(report) {
+    const lines = ["Blocking findings"];
+    appendCheckSections(lines, report.hardFindings.sections);
+    return `${lines.join("\n")}\n`;
+  }
+
+  function formatRiskSignalsText(report) {
+    const health = report.health;
+    const lines = [
+      "Risk signals",
+      `Functions over complexity limit: ${formatNumber(health.summary.functionsAboveThreshold)}`,
+      `90th percentile function complexity: ${formatNumber(health.vitalSigns.p90Cyclomatic)}`,
+      `Files with high coupling: ${health.vitalSigns.couplingHighPercent}% of scored files`
+    ];
+    return `${lines.join("\n")}\n`;
+  }
+
+  function formatRefactoringSuggestionsText(report) {
+    const lines = ["Refactoring suggestions"];
+    appendTargets(lines, report.health.targets, false);
+    return `${lines.join("\n")}\n`;
+  }
+
+  function statusText(payload) {
+    if (payload.running) return "Scanning";
+    return statusLabel(payload.state);
+  }
+
+  function runSummaryText(payload) {
+    if (!payload.report) return "No scan has run yet.";
+    const generatedAt = formatDate(payload.report.generatedAt || payload.finishedAt);
+    const seconds = Math.max(0.1, payload.report.durationMs / 1000).toFixed(1);
+    return `${generatedAt} · ${seconds} seconds · Fallow ${payload.report.version || "unknown"}`;
+  }
+
+  function runSummaryHtml(payload) {
+    if (!payload.report) return "No scan has run yet.";
+    const generatedAt = formatDate(payload.report.generatedAt || payload.finishedAt);
+    const seconds = Math.max(0.1, payload.report.durationMs / 1000).toFixed(1);
+    const version = payload.report.version || "unknown";
+    return `
+      <span class="run-summary-item"><i data-lucide="clock"></i>${generatedAt} · ${seconds} seconds</span>
+      <span class="run-summary-item"><i data-lucide="git-commit"></i>Fallow ${version}</span>
+    `;
+  }
+
+  function statusLabel(state) {
+    return STATUS_LABELS[state] || STATUS_LABELS.idle;
+  }
+
+  function formatDate(value) {
+    if (!value) return "No timestamp";
+    return new Intl.DateTimeFormat(undefined, {
+      dateStyle: "medium",
+      timeStyle: "medium"
+    }).format(new Date(value));
+  }
+
+  function appendCheckSections(lines, sections) {
+    if (sections.length === 0) {
+      lines.push("- None");
+      return;
+    }
+
+    sections.forEach((section) => {
+      lines.push(`- ${section.label}: ${section.count}`);
+      section.records.forEach((record) => {
+        lines.push(`  - ${record.title}${record.detail ? ` (${record.detail})` : ""}`);
+      });
+    });
+  }
+
+  function appendTargets(lines, targets, includeHeading) {
+    if (includeHeading) lines.push("", "Refactoring suggestions");
+    if (targets.length === 0) {
+      lines.push("- None");
+      return;
+    }
+
+    targets.forEach((target) => {
+      lines.push(`- ${target.path}: ${formatRecommendation(target.recommendation)}`);
+    });
+  }
+
+  window.codeScanFormat = {
+    effortTone,
+    formatBlockingFindingsText,
+    formatNumber,
+    formatRecommendation,
+    formatRefactoringSuggestionsText,
+    formatRiskSignalsText,
+    formatReportText,
+    runSummaryHtml,
+    runSummaryText,
+    statusText,
+    thresholdTone
+  };
+}

package/public/app-icons.js

@@ -0,0 +1,32 @@
+{
+  function metricIconHtml(id) {
+    const icons = {
+      "blocking-findings": "circle-x",
+      maintainability: "bar-chart-3",
+      "refactoring-suggestions": "scissors"
+    };
+    const icon = icons[id];
+    return icon
+      ? `<i class="metric-icon" data-lucide="${icon}" aria-hidden="true"></i>`
+      : "";
+  }
+
+  function refresh(root = document) {
+    if (!window.lucide) return;
+    window.lucide.createIcons({
+      attrs: { "stroke-width": 2 },
+      icons: window.lucide.icons,
+      root
+    });
+  }
+
+  function setButtonLabel(button, label) {
+    button.querySelector(".button-label").textContent = label;
+  }
+
+  window.codeScanIcons = {
+    metricIconHtml,
+    refresh,
+    setButtonLabel
+  };
+}