[EVOL]: update documentation

Author: helabenkhalfallah

README.md

@@ -24,6 +24,8 @@ The system computes:
 ## 📥 Installation
 
 ```bash
+pnpm install -D code-health-meter
+yarn install -D code-health-meter
 npm install -D code-health-meter
 ```
 
@@ -34,12 +36,23 @@ npm install -D code-health-meter
 
 ---
 
+## ⚡ Quick Start
+
+```bash
+npx code-health-meter --srcDir "./tests/mock-project" --format json
+```
+
+✅ Generates `CodeComplexityReport.json`, `CodeModularityReport.json`, and `jscpd-report.json` under `tests/output/`.
+
+---
+
 ## 🚦 CLI Usage
 
 Run the tool with:
 
 ```bash
 npx code-health-meter   --srcDir "./tests/mock-project"   --outputDir "./tests/output"   --format html
+pnpm code-health-meter  --srcDir "./tests/mock-project"   --outputDir "./tests/output"   --format html
 ```
 
 Supported formats: `html`, `json`, or both.
@@ -53,22 +66,22 @@ To replicate the analysis presented in the paper:
 ```bash
 git clone https://github.com/helabenkhalfallah/code-health-meter.git
 cd code-health-meter
-npm install
-npm run scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --format html,json
+pnpm install
+pnpm scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --format html
 ```
 
 ### Output:
 
-📂 `tests/mock-json-scan/`  
-- `code-complexity-audit/CodeComplexityReport.json`  
-- `code-modularity-audit/CodeModularityReport.json`  
-- `code-modularity-audit/CodeModularityReport.svg`  
+📂 `tests/mock-json-scan/`
+- `code-complexity-audit/CodeComplexityReport.json`
+- `code-modularity-audit/CodeModularityReport.json`
+- `code-modularity-audit/CodeModularityReport.svg`
 - `code-duplication-audit/jscpd-report.json`
 
-📂 `tests/mock-html-scan/`  
-- `code-complexity-audit/CodeComplexityReport.html`  
-- `code-modularity-audit/CodeModularityReport.html`  
-- `code-duplication-audit/html/index.html`  
+📂 `tests/mock-html-scan/`
+- `code-complexity-audit/CodeComplexityReport.html`
+- `code-modularity-audit/CodeModularityReport.html`
+- `code-duplication-audit/html/index.html`
 - Additional styled UI in `styles/` and `js/`
 
 > Note on Scale and Reproducibility: The included tests/mock-project is a simplified version intended for demonstration and functional validation of the Code Health Meter (CHM) framework. The original system evaluated in the TOSEM paper comprises approximately 14,000 lines of JavaScript/TypeScript code across 221 modules. Due to size and licensing constraints, that full system is not distributed as part of this artifact. However, the provided mock-project, along with the structured output reports, fully reproduces the CHM analysis pipeline, including complexity metrics, duplication detection, and graph-based modularity assessments.
@@ -85,6 +98,99 @@ npm run scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --form
 
 ---
 
+## 🧩 Reusable APIs (Programmatic)
+
+> **Analyzed entries vs raw files**: per-metric builders operate on **analyzed entries** produced by a single `inspectDirectory()` pass (not on raw file paths). The term _entries_ is used below to make this explicit.
+
+### Complexity — per-metric builders
+
+```js
+// src/kernel/complexity/CodeComplexityMetrics.js
+import {
+  buildMaintainabilityReports,  // MI
+  buildSLOCReports,             // SLOC
+  buildCyclomaticReports,       // CC
+  buildHalsteadMetricReports    // Halstead
+} from "./src/kernel/complexity/CodeComplexityMetrics.js";
+
+// entries: array produced by a single inspectDirectory() pass
+const reports = [
+  ...buildMaintainabilityReports(entries),
+  ...buildSLOCReports(entries),
+  ...buildCyclomaticReports(entries),
+  ...buildHalsteadMetricReports(entries),
+];
+```
+
+**Full complexity report (composer):**
+
+```js
+// src/kernel/complexity/CodeComplexityBuilder.js
+import { buildFullComplexityReport } from "./src/kernel/complexity/CodeComplexityBuilder.js";
+
+const { summary, auditReports } = buildFullComplexityReport({
+  entries,                              // from inspectDirectory()
+  metricIds: ["mi","sloc","cyclo","hal"],
+  summaryBase,                          // aggregates you already computed
+  buildAuditStats,                      // categorization helper
+});
+```
+
+**Producing analyzed entries:**
+
+```js
+// src/kernel/complexity/CodeComplexityUtils.js
+import { inspectDirectory } from "./src/kernel/complexity/CodeComplexityUtils.js";
+
+const { summary, files: entries } = inspectDirectory({
+  srcDir: "./tests/mock-project",
+  options: {/* parser / analyzer options */}
+});
+```
+
+### Modularity — graph metrics
+
+```js
+// src/kernel/modularity/CodeModularityUtils.js, CodeModularityMetrics.js
+import {
+  buildDirectoryTree,     // Madge: obj() + svg()
+  buildLouvainGraph,      // Graphology graph (directed)
+} from "./src/kernel/modularity/CodeModularityUtils.js";
+import {
+  detectCommunities,      // Louvain communities + modularity
+  readDensity,
+  readDegreeCentralities
+} from "./src/kernel/modularity/CodeModularityMetrics.js";
+
+const { tree, treeVisualization } = await buildDirectoryTree(".");
+const graph = await buildLouvainGraph(tree, treeVisualization);
+
+const { modularity, communities } = detectCommunities(graph);
+const { density } = readDensity(graph);
+const { degreeCentrality, inDegreeCentrality, outDegreeCentrality } = readDegreeCentralities(graph);
+```
+
+### Duplication — CLI + JSON output
+
+The duplication auditor uses **jscpd** and writes JSON/HTML to `code-duplication-audit/`. Programmatic consumption can read and parse `jscpd-report.json`:
+
+```js
+import fs from "fs";
+
+const dup = JSON.parse(
+  fs.readFileSync("./tests/output/code-duplication-audit/jscpd-report.json", "utf8")
+);
+
+console.log("clones:", dup.total?.clones || dup.statistics?.total?.clones);
+```
+
+#### Duplication — Fixed Reproducibility
+
+The duplication module now correctly detects cloned code.  
+✅ In the `tests/mock-project`, CHM identifies **1 clone of 6 lines**, matching the expected test results.
+
+---
+
 ## 📚 Citation
 
 ```bibtex
@@ -99,22 +205,38 @@ npm run scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --form
 
 ---
 
+## 🔍 Notes on Determinism & Reproducibility
+
+- The dependency graph is **directed** by default; centralities are computed on this directed graph.
+- Louvain community detection is provided by Graphology; results are stable for a given codebase and toolchain.
+- CHM favors a **single-pass** pipeline for complexity (compute once, reuse entries across metrics).
+
+---
+
 ## 🤝 Contributing
 
 ```bash
 git clone https://github.com/helabenkhalfallah/code-health-meter.git
 cd code-health-meter
-npm install
+pnpm install
 ```
 
 Run:
 
 ```bash
-npm run scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --format html,json
+pnpm scan --srcDir "./tests/mock-project" --outputDir "./tests/output" --format html,json
 ```
 
 ---
 
+## 📝 Response to Reviewers (TOSEM 2025 RCR)
+
+- **Functional Badge**: Fixed duplication detection reproducibility (1 clone of 6 lines detected in `tests/mock-project`).
+- **Reusable Badge**: Exposed Cyclomatic Complexity and Halstead metrics as reusable functions. Documented rationale for metrics embedded in higher-level modules.
+- **Documentation**: Expanded test instructions, clarified programmatic APIs, and detailed reproducibility notes.
+
+---
+
 ## 📜 License
 
 Licensed under the MIT License. See the [LICENSE](./LICENSE) file.

src/kernel/complexity/CodeComplexityAuditor.js

@@ -3,100 +3,23 @@ import { isAcceptedFileType, isExcludedFile } from '../../commons/AuditUtils.js'
 import { buildAuditStats, buildFullComplexityReport } from './CodeComplexityBuilder.js';
 import { inspectDirectory } from './CodeComplexityUtils.js';
 
-/**
- * Code Complexity Auditor — builds a full report while allowing per-metric reuse.
- *
- * Pipeline:
- *  1) inspectDirectory(): one-pass analysis (escomplex, SLOC, MI aggregates, per-file data).
- *  2) Filter auditable files (extensions/excludes).
- *  3) Compose per-metric reports using small, standalone metric builders.
- *  4) Merge stats into the summary (keeps original MI/SLOC totals/averages).
- *
- * Reviewers can import individual metrics (via CodeComplexityMetrics) without using this auditor.
- * This module preserves the original full-report behavior for CLI/HTML/JSON outputs.
- *
- * @module CodeComplexityAuditor
- * @see CodeComplexityBuilder#buildFullComplexityReport
- * @see CodeComplexityUtils#inspectDirectory
- */
+/** @typedef {import('./CodeComplexityMetrics.js').AnalyzedFileEntry} AnalyzedFileEntry */
+/** @typedef {import('./CodeComplexityMetrics.js').MetricId} MetricId */
 
 /**
- * String identifiers for per-file metrics available in the composer.
- * @typedef {'mi'|'sloc'|'cyclo'|'hal'} MetricId
- */
-
-/**
- * A single analyzed file entry produced upstream by inspectDirectory().
- * @typedef {Object} FileComplexityItem
- * @property {string} file
- * @property {number} fileMaintainability
- * @property {{ cyclomatic?: number, halstead?: Record<string, any> }} fileComplexity
- * @property {{ physical?: number, logical?: number }} fileSLOC
- */
-
-/**
- * A single formatted metric report entry (as produced by formatters in CodeComplexityConfig).
- * @typedef {Object} MetricReport
- * @property {string} title
- * @property {string} file
- * @property {number} [score]
- * @property {number} [scorePercent]
- * @property {string} [scoreUnit]
- */
-
-/**
- * Options for startComplexityAudit.
- * @typedef {Object} ComplexityAuditOptions
- * @property {{ ids?: MetricId[] }} [metrics] - Which per-metric builders to run.
- *   @default { ids: ['mi','sloc','cyclo','hal'] }
- * @property {Object} [inspect] - Options forwarded to inspectDirectory (parser, etc.).
- */
-
-/**
- * Result of the complexity audit.
- * @typedef {Object} ComplexityAuditResult
- * @property {Object} summary - Combined summary (original aggregates + categorized stats).
- * @property {MetricReport[]} auditReports - Concatenated per-metric reports for all files.
- */
-
-/**
- * Start Code Complexity Audit (full report), while internally using per-metric builders.
- * Keeps the single-pass performance characteristics and exposes fine-grained metrics via
- * CodeComplexityMetrics.* for reusable consumption.
- *
- * Notes:
- * - Files are filtered by `isAcceptedFileType` / `isExcludedFile`, then sorted ascending
- *   by `fileMaintainability`.
- * - On failure or when no files are found, this returns `{}` (not `null`) to preserve prior API.
+ * Start Code Complexity Audit (full report), using per-metric builders internally.
+ * Returns `{}` on failure to preserve prior API behavior.
  *
  * @async
  * @param {string} directory - Root directory to analyze.
- * @param {ComplexityAuditOptions|Object} options - Audit options. If you already used a flat
- *   options bag, keep doing so; this function reads `options.metrics?.ids` when present and
- *   forwards the rest to `inspectDirectory`.
- * @returns {Promise<ComplexityAuditResult|{}>} Full report `{ summary, auditReports }` or `{}` on failure.
- *
- * @example
- * // Full report with all metrics (default set)
- * const res = await startComplexityAudit('.', { inspect: { // escomplex opts } });
- *
- * @example
- * // Only MI + Cyclomatic
- * const res2 = await startComplexityAudit('.', { metrics: { ids: ['mi','cyclo'] } });
- *
- * @example
- * // Forward inspect options (e.g., TypeScript + JSX)
- * const res3 = await startComplexityAudit('.', {
- *   inspect: { complexity: { // babel/typhon options } }
- * });
+ * @param {Object} options   - Options (forwarded to `inspectDirectory` if needed).
+ * @returns {Promise<{summary:Object, auditReports:Object[]} | {}>}
  */
 export const startComplexityAudit = async (directory, options) => {
     try {
         AppLogger.info(`[CodeComplexityAuditor - startAudit] directory:  ${directory}`);
-
         if (!directory?.length) return {};
 
-        // Support legacy: some callers pass all options directly; accept both {inspect} or flat
         const inspectOpts = options?.inspect ?? options;
 
         const { summary, files } = inspectDirectory({
@@ -111,8 +34,8 @@ export const startComplexityAudit = async (directory, options) => {
 
         if (!files?.length) return {};
 
-        /** @type {FileComplexityItem[]} */
-        const auditableFiles = files
+        /** @type {AnalyzedFileEntry[]} */
+        const auditableEntries = files
             .filter((item) => {
                 const fileName = item.file;
                 return isAcceptedFileType(fileName) && !isExcludedFile(fileName);
@@ -123,7 +46,7 @@ export const startComplexityAudit = async (directory, options) => {
         const metricIds = options?.metrics?.ids ?? ['mi', 'sloc', 'cyclo', 'hal'];
 
         const { summary: combinedSummary, auditReports } = buildFullComplexityReport({
-            files: auditableFiles,
+            entries: auditableEntries,
             metricIds,
             summaryBase: summary,
             buildAuditStats,