@poleski/quality-tools 0.1.3

package/CHANGELOG.md

@@ -0,0 +1,13 @@
+# @poleski/quality-tools
+
+## 0.1.3
+
+### Patch Changes
+
+- c0b6623: Generalize CRAP coverage config, report output, workspace discovery, and mutation Stryker integration for non-CodeGraphy projects.
+
+## 0.1.1
+
+### Patch Changes
+
+- Extract the quality tools into a standalone package repo.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Joe Soboleski
+
+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,269 @@
+# @poleski/quality-tools
+
+Portable TypeScript quality checks for project structure, complexity,
+reachability, mutation, and test health.
+
+The tools are intentionally project-agnostic. They discover packages from
+`pnpm-workspace.yaml` or `package.json#workspaces`, accept explicit file/folder
+targets, and read project-specific behavior from `quality.config.json`.
+
+## Install
+
+```bash
+pnpm add -D @poleski/quality-tools
+pnpm exec quality-tools init
+```
+
+Before publish, use a local link from a host project:
+
+```bash
+pnpm add -D link:/absolute/path/to/quality-tools
+```
+
+## Quick Start
+
+```bash
+pnpm exec quality-tools organize .
+pnpm exec quality-tools boundaries . --strict
+pnpm exec quality-tools reachability . --strict
+pnpm exec quality-tools scrap ./tests
+pnpm exec quality-tools crap ./src
+pnpm exec quality-tools mutate .
+pnpm exec quality-tools mutate ./src/parser.ts --force
+pnpm exec quality-tools mutate -- --mutate ./src/parser.ts
+```
+
+Targets can be the repo root, a package shorthand, a package root, a directory,
+or a file. Package shorthand is resolved from workspace package names, not from
+hardcoded folder names. The starter config uses `src` as a conventional default,
+but the tools scope from the target path plus your configured include/exclude
+globs.
+
+## Reports
+
+All quality-tool artifacts use one report root:
+
+```json
+{
+  "reportsDir": "reports/quality-tools"
+}
+```
+
+Current outputs:
+
+- `reportsDir/organize/*.json` for organize baselines
+- `reportsDir/scrap/*.json` for scrap baselines
+- `reportsDir/crap/<target>/coverage-final.json` for CRAP coverage input
+- `reportsDir/mutation/mutation.json` and `mutation.html` from Stryker
+- `reportsDir/mutation/<target>/mutation.json` copied per mutation target
+
+CRAP reads the coverage report path you configure. The starter Vitest command
+writes that coverage under `reportsDir/crap/<target>/`.
+
+## Config
+
+Run `quality-tools init` to create a starter `quality.config.json`.
+
+```json
+{
+  "reportsDir": "reports/quality-tools",
+  "defaults": {
+    "crap": {
+      "coverage": {
+        "command": "pnpm",
+        "args": [
+          "exec",
+          "vitest",
+          "run",
+          "--coverage",
+          "--coverage.reportsDirectory",
+          "{repoRoot}/{reportsDir}/crap/{reportKey}"
+        ],
+        "coveragePath": "{repoRoot}/{reportsDir}/crap/{reportKey}/coverage-final.json"
+      },
+      "exclude": ["**/*.test.ts", "**/*.test.tsx", "**/*.d.ts"]
+    },
+    "mutation": {
+      "include": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["src/**/*.d.ts"]
+    },
+    "scrap": {
+      "include": ["tests/**/*.test.ts", "tests/**/*.test.tsx"],
+      "exclude": []
+    },
+    "boundaries": {
+      "include": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["src/**/*.d.ts", "**/*.test.ts", "**/*.test.tsx"],
+      "entrypoints": [],
+      "layers": []
+    },
+    "organize": {
+      "lowInfoNames": {
+        "banned": ["utils", "helpers", "misc", "common", "shared", "_shared", "lib", "index"],
+        "discouraged": ["types", "constants", "config", "base", "core"]
+      }
+    }
+  },
+  "packages": {}
+}
+```
+
+Package-specific config lives under `packages.<packageName>`. The package name
+is the unscoped manifest name by default, so `@scope/parser` is configured as
+`parser`.
+
+## CRAP
+
+CRAP calculates complexity plus coverage risk and fails when a function exceeds
+the threshold. The default threshold is `8`.
+
+```bash
+pnpm exec quality-tools crap ./src
+pnpm exec quality-tools crap parser --threshold 10
+```
+
+CRAP needs Istanbul `coverage-final.json`. Configure the command and report path
+for your project. Put generated coverage under `{reportsDir}` when possible so
+all artifacts stay together:
+
+```json
+{
+  "defaults": {
+    "crap": {
+      "coverage": {
+        "command": "pnpm",
+        "args": [
+          "exec",
+          "vitest",
+          "run",
+          "--coverage",
+          "--coverage.reportsDirectory",
+          "{repoRoot}/{reportsDir}/crap/{reportKey}"
+        ],
+        "coveragePath": "{repoRoot}/{reportsDir}/crap/{reportKey}/coverage-final.json"
+      }
+    }
+  },
+  "packages": {
+    "parser": {
+      "crap": {
+        "coverage": {
+          "command": "pnpm",
+          "args": [
+            "--filter",
+            "{packageJsonName}",
+            "exec",
+            "vitest",
+            "run",
+            "--coverage",
+            "--coverage.reportsDirectory",
+            "{repoRoot}/{reportsDir}/crap/{reportKey}"
+          ],
+          "coveragePath": "{repoRoot}/{reportsDir}/crap/{reportKey}/coverage-final.json"
+        }
+      }
+    }
+  }
+}
+```
+
+Supported template values in CRAP coverage command fields:
+
+- `{repoRoot}`
+- `{packageRoot}`
+- `{packageName}`
+- `{packageJsonName}`
+- `{reportKey}`
+- `{target}` or `{targetPath}`
+- `{reportsDir}`
+
+## Mutation
+
+Mutation runs Stryker against the selected source target. The CLI does not run
+typecheck first and does not assume any package is special.
+
+```bash
+pnpm exec quality-tools mutate .
+pnpm exec quality-tools mutate parser
+pnpm exec quality-tools mutate ./src/parser.ts --force
+pnpm exec quality-tools mutate -- --mutate ./src/parser.ts
+```
+
+`mutate` requires an explicit target. Use `.` for a repo-wide run, a package
+shorthand for a workspace package, or a file/folder path for a narrower run.
+Bare `quality-tools mutate` is intentionally invalid so host projects can own
+their own all-package wrappers. `--force` is passed through to Stryker when you
+need to ignore incremental mutation state.
+
+The CLI passes Stryker:
+
+- the Stryker config path
+- scoped mutate globs from `quality.config.json`
+- an incremental file path under `reportsDir/mutation/<target>/`
+- `QUALITY_TOOLS_REPORTS_DIR`, so the bundled base config writes to the shared
+  report root
+
+Long mutation runs print a progress heartbeat once per minute. The bundled base
+config also accepts these environment knobs:
+
+- `QUALITY_TOOLS_STRYKER_CONCURRENCY`, default `2`
+- `QUALITY_TOOLS_STRYKER_MAX_TEST_RUNNER_REUSE`, default `0`
+
+Use a project Stryker config when you need custom Vitest wiring:
+
+```js
+const base = require('@poleski/quality-tools/stryker.config.cjs');
+
+module.exports = {
+  ...base,
+  vitest: {
+    ...base.vitest,
+    configFile: 'vitest.config.ts'
+  }
+};
+```
+
+Then reference it in `quality.config.json`:
+
+```json
+{
+  "defaults": {
+    "mutation": {
+      "strykerConfig": "stryker.config.cjs",
+      "include": ["src/**/*.ts", "src/**/*.tsx"],
+      "exclude": ["src/**/*.d.ts"]
+    }
+  }
+}
+```
+
+If `strykerConfig` is omitted, the tool looks for `stryker.config.cjs`,
+`stryker.config.mjs`, `stryker.config.js`, or `stryker.conf.js` in the repo
+root, then falls back to the bundled base config.
+
+## Other Tools
+
+```bash
+pnpm exec quality-tools organize ./src
+pnpm exec quality-tools boundaries parser --strict
+pnpm exec quality-tools reachability parser --strict
+pnpm exec quality-tools scrap ./tests --strict
+```
+
+- `organize` checks directory size, depth, naming, barrels, and cohesion. Use
+  `--write-baseline` and `--compare <path>` for baseline workflows.
+- `boundaries` checks configured layers, entrypoints, dead surfaces, and dead
+  ends.
+- `reachability` reports dead surfaces and dead ends without boundary-layer
+  failures.
+- `scrap` reviews test files for split pressure, repeated setup, weak
+  assertions, validation issues, and refactor recommendations.
+
+## Development
+
+```bash
+pnpm run test
+pnpm run lint
+pnpm run typecheck
+pnpm run build
+```