@mifort-solutions/qmetrix 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Alex Kolonitsky
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# QMetriX
+
+> `@mifort-solutions/qmetrix` — build & quality tooling, extracted from `ai.mifort.com`'s `dev/scripts/`.
+
+QMetriX is a set of plain-ESM Node scripts that compute quality signals over a
+**consuming repository**: coverage merge & reporting, a quality dashboard, an image
+budget check / optimizer, a structural-duplication audit, a security scan, an
+e2e-server guard, and a single-file codebase bundler.
+
+It is **dev tooling, not a library** — you install it as a `devDependency` and invoke its
+`bin` executables from your project's `package.json` scripts. The scripts read and write
+the **consuming repo's** tree (`src/`, `content/`, `public/`, `dist/reports/*`,
+`package.json`, `node_modules`, git history).
+
+## The cwd contract (important)
+
+Every QMetriX bin anchors the project root on **`process.cwd()`** — i.e. the directory the
+verb runs from. **Run every bin from your repository root** (which is what `npm run …` does
+by default). Running a bin from a subdirectory will make its `src/`, `dist/`, `package.json`
+reads target the wrong tree.
+
+## Requirements
+
+- **Node `22.x`** (closed range — the package's `engines` pins the same major as the host app).
+- A few bins shell out to system tools that are not npm dependencies:
+  `qmetrix-security-scan` uses `curl` / `tar` / the CodeQL CLI; `qmetrix-quality-dashboard`
+  expects a built Storybook under `dist/site/storybook` when run for a full dashboard.
+
+## Install
+
+```bash
+npm install --save-dev @mifort-solutions/qmetrix
+```
+
+## Bins
+
+| Bin | What it does |
+| --- | --- |
+| `qmetrix-check-images` | Fail the build when committed images exceed the byte/pixel budget (`sharp`). |
+| `qmetrix-optimize-images` | Resize / re-encode committed assets (`sharp`). |
+| `qmetrix-audit-structure` | Structural (AST-shape) copy-paste audit via `jsinspect-plus` → `dist/reports/jsinspect.json`. Advisory (exits 0). |
+| `qmetrix-security-scan` | Local SAST/SCA (Snyk + CodeQL) → SARIF under `dist/reports/`. |
+| `qmetrix-quality-dashboard` | Build the quality dashboard HTML from `dist/reports/*` + the repo tree. |
+| `qmetrix-bundle-codebase` | Bundle the codebase into one self-contained HTML file. |
+| `qmetrix-e2e-server-guard` | Guard the e2e port against a stale `next start` / poisoned prerender cache. |
+| `qmetrix-coverage-clean` | Clean per-suite / global coverage scratch under `dist/reports/coverage`. |
+| `qmetrix-coverage-report-suite` | Build a per-suite coverage report from raw V8 / istanbul data. |
+| `qmetrix-coverage-report-global` | Merge per-suite coverage into a global line-union `lcov.info`. |
+| `qmetrix-coverage-next-start` | Start Next.js in-process with V8 coverage enabled (used by Playwright). |
+
+Arguments pass through verbatim, e.g.:
+
+```bash
+qmetrix-coverage-clean e2e
+qmetrix-e2e-server-guard --pre-build
+qmetrix-coverage-report-suite storybook
+qmetrix-quality-dashboard --no-coverage
+qmetrix-optimize-images public/images --format webp
+```
+
+## Example wiring (`package.json`)
+
+```jsonc
+{
+  "scripts": {
+    "images:check": "qmetrix-check-images",
+    "audit:structure": "qmetrix-audit-structure",
+    "coverage:global": "qmetrix-coverage-clean global && qmetrix-coverage-report-global"
+  }
+}
+```
+
+## License
+
+MIT.

package/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@mifort-solutions/qmetrix",
+  "version": "1.0.0",
+  "description": "QMetriX — build & quality tooling (coverage merge, quality dashboard, image budget, security scan, structural duplication audit, e2e server guard, codebase bundler). Operates on the consuming repo via its cwd.",
+  "type": "module",
+  "license": "MIT",
+  "author": "Alex Kolonitsky <alex.kolonitsky@gmail.com>",
+  "homepage": "https://github.com/AlexKolonitskyMifort/qmetrix#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexKolonitskyMifort/qmetrix.git"
+  },
+  "bugs": {
+    "url": "https://github.com/AlexKolonitskyMifort/qmetrix/issues"
+  },
+  "keywords": [
+    "quality",
+    "coverage",
+    "dashboard",
+    "tooling",
+    "code-quality",
+    "ci"
+  ],
+  "bin": {
+    "qmetrix-audit-structure": "src/audit-structure.mjs",
+    "qmetrix-bundle-codebase": "src/bundle-codebase.mjs",
+    "qmetrix-check-images": "src/check-images.mjs",
+    "qmetrix-optimize-images": "src/optimize-images.mjs",
+    "qmetrix-quality-dashboard": "src/quality-dashboard.mjs",
+    "qmetrix-security-scan": "src/security-scan.mjs",
+    "qmetrix-e2e-server-guard": "src/e2e-server-guard.mjs",
+    "qmetrix-coverage-clean": "src/coverage/clean.mjs",
+    "qmetrix-coverage-report-suite": "src/coverage/report-suite.mjs",
+    "qmetrix-coverage-report-global": "src/coverage/report-global.mjs",
+    "qmetrix-coverage-next-start": "src/coverage/next-start-cov.mjs"
+  },
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "jsinspect-plus": "^3.1.3",
+    "monocart-coverage-reports": "^2.12.12",
+    "sharp": "^0.35.0"
+  },
+  "engines": {
+    "node": "22.x"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/audit-structure.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+/**
+ * Structural copy-paste audit — finds renamed / restructured duplication that the
+ * token-based detector (`npm run cpd`, jscpd) misses.
+ *
+ * jscpd matches token *values*, so the moment identifiers or literals change it
+ * stops seeing the clone. jsinspect-plus walks the AST and matches node *shape*,
+ * so two blocks with the same structure but different variable names still flag.
+ * Threshold / ignore live in `.config/.jsinspectrc`; identifier matching is turned
+ * off here on the CLI (`-I`) because jsinspect ignores that key from the config
+ * file (see the note in .jsinspectrc). Literals stay on as anchors.
+ *
+ * This is **advisory**: structural detectors are noisy by nature, so a finding is
+ * a review prompt, not a build failure. It always exits 0 unless `--strict` is
+ * passed. Part of the periodic `audit` phase (see `npm run audit`), not the
+ * per-push `verify` gate.
+ *
+ * Usage:
+ *   node dev/scripts/audit-structure.mjs [paths...] [--strict]
+ *   npm run audit:structure
+ *
+ * Writes a machine-readable report to dist/reports/jsinspect.json.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { mkdirSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { createRequire } from 'node:module';
+
+// Anchored on the consuming repo's cwd — every verb runs from the app root.
+const ROOT = process.cwd();
+
+const argv = process.argv.slice(2);
+const strict = argv.includes('--strict');
+const targets = argv.filter((a) => !a.startsWith('--'));
+const paths = targets.length ? targets : ['src'];
+
+// Resolve jsinspect-plus relative to THIS package (hoist-proof): works whether the
+// dep hoists to the app root or nests under node_modules/@mifort-solutions/qmetrix/node_modules.
+const BIN = path.join(
+  path.dirname(createRequire(import.meta.url).resolve('jsinspect-plus/package.json')),
+  'bin',
+  'jsinspect',
+);
+const CONFIG = path.join('.config', '.jsinspectrc');
+const REPORT = path.join('dist', 'reports', 'jsinspect.json');
+
+const posix = (p) => p.replace(/^\.[\\/]/, '').replace(/\\/g, '/');
+
+/* ── Run jsinspect-plus via its bundled CLI (cross-platform: node + bin.js) ── */
+const { stdout, stderr, status, error } = spawnSync(
+  process.execPath,
+  [BIN, '-c', CONFIG, '-I', '-r', 'json', ...paths],
+  { cwd: ROOT, encoding: 'utf8', maxBuffer: 32 * 1024 * 1024 },
+);
+
+if (error) {
+  console.error(`audit:structure — failed to launch jsinspect-plus: ${error.message}`);
+  process.exit(strict ? 1 : 0);
+}
+
+// jsinspect prints per-file parser failures to stderr but keeps going — surface them.
+const parseErrors = (stderr || '').trim();
+if (parseErrors) {
+  console.warn('audit:structure — some files could not be parsed:');
+  console.warn(parseErrors);
+}
+
+let matches;
+try {
+  matches = JSON.parse(stdout || '[]');
+} catch {
+  console.error('audit:structure — could not parse jsinspect output (exit', status, ')');
+  console.error(stdout);
+  process.exit(strict ? 1 : 0);
+}
+
+/* ── Persist the artifact (dashboard / history can pick this up later) ── */
+mkdirSync(path.join(ROOT, 'dist', 'reports'), { recursive: true });
+writeFileSync(path.join(ROOT, REPORT), JSON.stringify(matches, null, 2));
+
+/* ── Human summary, worst (most lines duplicated) first ── */
+const linesOf = (m) => m.instances.reduce((n, i) => n + (i.lines[1] - i.lines[0] + 1), 0);
+const ranked = [...matches].sort((a, b) => linesOf(b) - linesOf(a));
+
+console.log(
+  `\nStructural duplication audit (jsinspect-plus, AST shape) — ${matches.length} clone group(s)\n`,
+);
+
+if (matches.length === 0) {
+  console.log('No structural clones above the configured threshold. ✓\n');
+} else {
+  ranked.forEach((m, i) => {
+    const span = m.instances[0].lines[1] - m.instances[0].lines[0] + 1;
+    const locs = m.instances.map((inst) => `${posix(inst.path)}:${inst.lines[0]}-${inst.lines[1]}`);
+    console.log(`#${i + 1}  ${m.instances.length}× (~${span} lines each)`);
+    locs.forEach((loc) => console.log(`     ${loc}`));
+  });
+  console.log(`\nReport: ${posix(REPORT)}`);
+  console.log('Advisory — these are candidates for extraction, not build failures.\n');
+}
+
+process.exit(strict && matches.length ? 5 : 0);