@blundergoat/gruff-ts 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+## [0.1.0] - 2026-05-23
+
+Initial public release of the `@blundergoat/gruff-ts` npm package.
+
+- TypeScript/JavaScript code quality scanner: 121 rules across 11 pillars
+  (complexity, dead-code, design, documentation, modernisation, naming,
+  security, sensitive-data, size, test-quality, waste).
+- CLI commands: `analyse`, `summary`, `report`, `list-rules`, `dashboard`,
+  `completion`.
+- Output formats: `text`, `json`, `html`, `markdown`, `github`, `hotspot`,
+  `sarif`. Stable schemas: `gruff.analysis.v1`, `gruff.baseline.v1`,
+  `gruff.hotspot.v1`.
+- Baselines via stable per-finding fingerprints, `--diff` for changed-file
+  scans, local dashboard on `127.0.0.1:8767`. Released under MIT.

package/CONTRIBUTING.md

@@ -0,0 +1,87 @@
+# Contributing
+
+Thanks for taking the time to improve `gruff-ts`.
+
+## Development Setup
+
+```bash
+npm install
+npm run check
+```
+
+Useful local commands:
+
+```bash
+npm test
+./bin/gruff-ts analyse . --fail-on=none
+./bin/gruff-ts list-rules
+npm run start-dev
+```
+
+CI runs the same core gate with `npm run check`, then runs
+`./bin/gruff-ts analyse . --fail-on=advisory`.
+
+## Project Shape
+
+The runtime lives under `src/`:
+
+- `src/cli.ts` - thin bootstrap and public re-export shell.
+- `src/cli-program.ts` - Commander program wiring and option normalization.
+- `src/analyser.ts` - scan orchestration and per-file/project rule fanout.
+- `src/discovery.ts` - source-file discovery and `.gitignore` handling.
+- `src/rules.ts` - canonical rule descriptor catalogue.
+- `src/blocks.ts`, `src/line-rules.ts`, `src/class-rules.ts`,
+  `src/dead-code-rules.ts`, `src/doc-rules.ts`, `src/comment-rules.ts`,
+  `src/context-doc-rules.ts`, `src/fixture-purpose-rules.ts`,
+  `src/test-block-rules.ts`, `src/security-flow-rules.ts`,
+  `src/github-actions-rules.ts`, and `src/safety-rules.ts` - focused rule
+  packs.
+- `src/sensitive-data-rules.ts` - sensitive-data rule descriptors and
+  detectors.
+- `src/project-config-rules.ts` - package and tsconfig rule descriptors.
+- `src/baseline.ts`, `src/config.ts`, `src/dashboard.ts`, `src/findings.ts`,
+  `src/rule-list.ts`, `src/scoring.ts`, `src/source-text.ts`,
+  `src/text-scans.ts`, `src/report-renderers.ts`, `src/constants.ts`,
+  `src/types.ts` - shared helpers, contracts, and renderers.
+- `src/*.test.ts` - Node test runner coverage for scanner behavior, rule
+  packs, fixtures, reports, and CLI surfaces.
+
+Keep changes small and local. Do not add runtime dependencies beyond
+`commander` and `tsx` unless that direction is explicitly accepted first.
+
+## Rules For Rule Changes
+
+When adding or changing a rule:
+
+- Add or update a `RuleDescriptor`.
+- Include focused noisy and clean fixtures.
+- Preserve the public `Finding` shape.
+- Preserve fingerprint inputs unless a breaking schema change is planned.
+- Add config threshold coverage when the rule has thresholds.
+- Run `npm run check`.
+
+Every finding must keep a stable `fingerprint`. Baselines depend on it.
+
+## Documentation Changes
+
+Update docs when behavior changes:
+
+- `README.md` for user-facing workflow changes.
+- `CHANGELOG.md` for release-visible changes.
+- `docs/CONFIGURATION.md` for config shape or threshold changes.
+- `docs/REPORTS_AND_CI.md` for output, CI, dashboard, or baseline changes.
+- `docs/RELEASING.md` for release process changes.
+
+## Pull Request Checklist
+
+- [ ] Tests or fixtures cover the behavior change.
+- [ ] `npm run check` passes.
+- [ ] Public schemas are unchanged, or the breaking change is documented.
+- [ ] Baseline/fingerprint behavior is unchanged, or the migration path is
+      documented.
+- [ ] Docs and changelog are updated when user-visible behavior changes.
+
+## Security Issues
+
+Do not open a public issue containing secrets, exploit payloads, or private
+repository details. Follow [SECURITY.md](SECURITY.md).

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Hansen
+
+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,303 @@
+# gruff-ts
+
+`gruff-ts` is a static analyzer for TypeScript and JavaScript projects. The
+dependency-light Node.js CLI scans source, tests, package metadata, and
+common config files, then reports quality findings across 11 pillars with
+stable fingerprints for baselines and repeatable machine output.
+
+The 0.1.0 release ships 121 rules across 11 pillars,
+JSON/HTML/Markdown/GitHub/SARIF/hotspot output, baseline support, changed-file
+filtering, local score history, a rule catalogue, and a dark local dashboard.
+Scanned file types include TypeScript, JavaScript, CSS, JSON, YAML, TOML, INI,
+XML, and `.env*`.
+
+## Install
+
+Install the scoped npm package; it exposes the `gruff-ts` CLI command:
+
+```bash
+npm install --save-dev @blundergoat/gruff-ts
+npx gruff-ts analyse . --fail-on=none
+```
+
+From this checkout:
+
+```bash
+npm install
+./bin/gruff-ts analyse . --fail-on=none
+```
+
+## Quick Start
+
+Run an exploratory scan without failing the shell on findings:
+
+```bash
+gruff-ts analyse . --fail-on=none
+```
+
+Scan specific paths:
+
+```bash
+gruff-ts analyse src fixtures/sample.ts --fail-on=none
+```
+
+Generate a static HTML report:
+
+```bash
+gruff-ts report . --output gruff-report.html
+```
+
+Start the local dashboard:
+
+```bash
+gruff-ts dashboard
+```
+
+The dashboard binds to `127.0.0.1:8767` by default.
+
+## What It Checks
+
+Findings are grouped into 11 public pillars:
+
+- `size`
+- `complexity`
+- `dead-code`
+- `waste`
+- `naming`
+- `documentation`
+- `modernisation`
+- `security`
+- `sensitive-data`
+- `test-quality`
+- `design`
+
+Inspect the exact rule ids, severities, confidence levels, remediation text,
+threshold values, and options:
+
+```bash
+gruff-ts list-rules
+gruff-ts list-rules --format=json
+```
+
+## Commands
+
+| Command | Purpose |
+| --- | --- |
+| `analyse [paths...]` | Run the scanner and print findings. |
+| `summary [paths...]` | Print per-pillar counts, top rules, and top file offenders without per-finding output. |
+| `report [paths...]` | Render an HTML or JSON report, optionally to a file. |
+| `list-rules` | Print rule catalogue metadata. |
+| `dashboard` | Serve the local HTTP dashboard. |
+| `completion [shell]` | Print a shell completion script for `bash`, `zsh`, or `fish`. |
+| `list` | Print the Symfony-style command catalogue. |
+
+Useful help commands:
+
+```bash
+gruff-ts --help
+gruff-ts list
+gruff-ts analyse --help
+gruff-ts summary --help
+gruff-ts report --help
+gruff-ts dashboard --help
+```
+
+Global console options match the `gruff` PHP CLI surface: `--silent`,
+`--quiet`, `--ansi` / `--no-ansi`, `--no-interaction`, and `-v` / `-vv` /
+`-vvv`. The command menu uses the same ANSI colour treatment as `gruff` when
+stdout is a TTY; `--ansi` forces colour and `--no-ansi` disables it.
+
+## Output Formats
+
+`analyse` supports:
+
+| Format | Use case |
+| --- | --- |
+| `text` | Human terminal output. |
+| `json` | Full machine-readable `gruff.analysis.v1` report. |
+| `html` | Self-contained dark inspection report. |
+| `markdown` | Short Markdown summary. |
+| `github` | GitHub Actions annotation commands. |
+| `hotspot` | Compact `gruff.hotspot.v1` top-offender payload. |
+| `sarif` | SARIF 2.1.0 code-scanning output. |
+
+Examples:
+
+```bash
+gruff-ts analyse . --format=json --fail-on=none
+gruff-ts analyse . --format=github --fail-on=warning
+gruff-ts analyse . --format=hotspot --fail-on=none
+gruff-ts analyse . --format=sarif --fail-on=none > gruff.sarif
+```
+
+`report` supports `html` and `json`:
+
+```bash
+gruff-ts report . --format=json --output gruff-report.json
+```
+
+## CI
+
+`analyse` defaults to `--fail-on error`.
+
+```bash
+# Exploratory scan: never fail because of findings.
+gruff-ts analyse . --fail-on=none
+
+# CI gate only on error findings.
+gruff-ts analyse . --fail-on=error
+
+# Stricter CI gate on warnings and errors.
+gruff-ts analyse . --fail-on=warning
+```
+
+Exit codes:
+
+- `0`: scan completed and no finding met `--fail-on`.
+- `1`: scan completed and at least one finding met `--fail-on`.
+- `2`: scan produced diagnostics such as missing inputs or parse/config errors.
+
+Changed-file scans:
+
+```bash
+gruff-ts analyse . --diff=working-tree --format=github --fail-on=warning
+gruff-ts analyse . --diff=staged --format=json --fail-on=none
+```
+
+`--diff` accepts `working-tree`, `staged`, `unstaged`, or a base ref.
+
+Security-focused CI can run without baseline suppression so new error-severity
+security or sensitive-data findings cannot be hidden by an adoption baseline:
+
+```bash
+gruff-ts analyse . --no-baseline --fail-on=error
+```
+
+## Baselines And History
+
+Baselines suppress existing findings by stable fingerprint so teams can adopt
+the tool without fixing every current issue first.
+
+```bash
+gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none
+gruff-ts analyse . --baseline gruff-baseline.json --fail-on=warning
+gruff-ts analyse . --no-baseline --fail-on=none
+```
+
+Baseline files use `schemaVersion: "gruff.baseline.v1"`.
+
+`report` is intended for raw inspection output and does not accept
+`--baseline`; use `analyse` when you need baseline suppression in CI.
+
+Append local score history:
+
+```bash
+gruff-ts analyse . --history-file .gruff-history.json --fail-on=none
+```
+
+## Configuration
+
+`analyse` auto-loads the first supported config file it finds in the project root:
+
+1. `.gruff-ts.yaml`
+2. `.gruff.json`
+3. `.gruff.yaml`
+4. `.gruff.yml`
+
+Use an explicit config or skip config loading:
+
+```bash
+gruff-ts analyse . --config .gruff-ts.yaml
+gruff-ts analyse . --no-config
+```
+
+Recursive scans respect root and nested `.gitignore` files. Use
+`--include-ignored` to include default and Git-ignored paths for a run;
+`paths.ignore` entries still apply as project policy.
+
+Minimal YAML example:
+
+```yaml
+paths:
+  ignore:
+    - "generated/**"
+
+allowlists:
+  acceptedAbbreviations:
+    - api
+    - cli
+  secretPreviews: []
+
+rules:
+  complexity.cyclomatic:
+    threshold: 10
+    severity: warning
+  size.file-length:
+    threshold: 400
+    severity: warning
+```
+
+See [Configuration](docs/CONFIGURATION.md) for the full config shape and
+examples.
+
+## Dashboard
+
+Start the local dashboard:
+
+```bash
+gruff-ts dashboard --host 127.0.0.1 --port 8767 --project-root .
+```
+
+The dashboard serves a local iframe report and a compact controls panel. Keep
+the default loopback bind unless the network is trusted. The `/scan` endpoint
+analyses filesystem paths from request parameters, so the bind address is the
+main safety boundary.
+
+## Safety And Limitations
+
+- Secret-like findings include redacted previews; raw secret values should not
+  appear in findings or rendered output.
+- The scanner is heuristic. It is not a TypeScript compiler, type checker, or
+  full JavaScript parser.
+- Rule confidence is included in the rule catalogue and each finding. Treat low
+  and medium confidence findings as review prompts.
+- Baselines suppress matching fingerprints. Review baseline diffs carefully so
+  new findings are not hidden by accident.
+
+## Documentation
+
+- [Changelog](CHANGELOG.md)
+- [Configuration](docs/CONFIGURATION.md)
+- [Reports and CI](docs/REPORTS_AND_CI.md)
+- [Contributing](CONTRIBUTING.md)
+- [Security](SECURITY.md)
+- [Release checklist](docs/RELEASING.md)
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+npm run start-dev
+./bin/gruff-ts analyse . --fail-on=none
+```
+
+Source lives under `src/`: `src/cli.ts` is the thin bootstrap,
+`src/cli-program.ts` owns Commander wiring, `src/analyser.ts` orchestrates the
+scan, `src/rules.ts` holds the descriptor catalogue, and focused sibling
+modules own rule packs and renderers. Tests live in focused `src/*.test.ts`
+files.
+
+To bump the released version, run `scripts/bump-version.sh <new-version>` - it
+updates `package.json` and `src/constants.ts` in lockstep so the CLI
+`--version` output stays consistent with the published `@blundergoat/gruff-ts`
+package.
+
+## Author
+
+Built by [Matthew Hansen](https://www.blundergoat.com/about).
+
+## License
+
+[MIT](LICENSE)

package/SECURITY.md

@@ -0,0 +1,45 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+| --- | --- |
+| 0.1.x | Yes |
+
+## Reporting A Vulnerability
+
+Do not file a public issue with exploit details, secrets, tokens, private source
+paths, or sensitive scan output.
+
+Use the project's private vulnerability reporting channel if one is enabled on
+the public repository. If private reporting is not available yet, contact the
+maintainer through the preferred private channel before posting details
+publicly.
+
+Please include:
+
+- A short description of the issue.
+- A minimal reproduction when possible.
+- Affected command or output format.
+- Whether sensitive data is exposed in findings, reports, dashboard output, or
+  logs.
+- Whether a baseline, SARIF upload, GitHub annotation output, or dashboard scan
+  endpoint is involved.
+
+## Security Boundaries
+
+- The dashboard is a local developer tool. It binds to `127.0.0.1` by default.
+  Binding it to `0.0.0.0` can expose filesystem scanning to the network.
+- Sensitive-data rules should render redacted previews only.
+- HTML output is generated without a template engine; new interpolated fields
+  must be escaped.
+- The scanner is heuristic and is not a vulnerability scanner or dependency
+  advisory database.
+- Baselines suppress matching fingerprints. For security-focused CI, prefer
+  `gruff-ts analyse . --no-baseline --fail-on=error`.
+
+## Disclosure Expectations
+
+The maintainer should acknowledge valid private reports, assess impact, and
+coordinate a fix before public disclosure. Public advisories should include the
+affected versions, fixed version, and mitigation.

package/bin/gruff-ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env sh
+set -eu
+
+PRG="$0"
+while [ -h "$PRG" ]; do
+	SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$PRG")" && pwd)"
+	PRG="$(readlink "$PRG")"
+	case "$PRG" in
+		/*) ;;
+		*) PRG="$SCRIPT_DIR/$PRG" ;;
+	esac
+done
+
+SCRIPT_DIR="$(CDPATH= cd -- "$(dirname -- "$PRG")" && pwd)"
+PACKAGE_DIR="$SCRIPT_DIR/.."
+
+if [ -f "$PACKAGE_DIR/node_modules/tsx/dist/loader.mjs" ]; then
+	TSX_LOADER="$PACKAGE_DIR/node_modules/tsx/dist/loader.mjs"
+elif [ -f "$PACKAGE_DIR/../tsx/dist/loader.mjs" ]; then
+	TSX_LOADER="$PACKAGE_DIR/../tsx/dist/loader.mjs"
+else
+	TSX_LOADER="tsx"
+fi
+
+exec node --import "$TSX_LOADER" "$PACKAGE_DIR/src/cli.ts" "$@"