@blundergoat/gruff-ts 0.1.0

package/docs/CONFIGURATION.md

@@ -0,0 +1,220 @@
+# Configuration
+
+`gruff-ts` can run without config. A config file is useful when adopting the
+tool in a real project with generated files, local naming conventions, or rule
+thresholds that need tuning.
+
+## Discovery Order
+
+`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 path:
+
+```bash
+gruff-ts analyse . --config .gruff-ts.yaml
+```
+
+Skip config for a run:
+
+```bash
+gruff-ts analyse . --no-config
+```
+
+## Shape
+
+```yaml
+paths:
+  ignore:
+    - "generated/**"
+
+allowlists:
+  acceptedAbbreviations:
+    - api
+    - cli
+  secretPreviews: []
+  bannedGenericNames: [process, handle, doit, run, execute, manage]
+  booleanPrefixes: [is, has, can, should, does, did, was, will, may, in, scan, supports, requires]
+  hungarianPrefixes: [str, obj, arr, bool, int, num]
+  placeholderNames: [foo, bar, baz, tmp, temp, thing, stuff, data, value, item]
+  abbreviationDenylist: [ctx, pkg, opts, fn, idx, cb]
+  negativeBooleanAllowed: [nostore, nofollow, noreferrer, noscript, noindex]
+  knownAcronyms: [url, http, https, id, xml, json, html, css, api, sql, db, io, ui, uuid, ip, tcp, udp, ast, cli, npm]
+
+rules:
+  rule.id:
+    enabled: true
+    threshold: 10
+    severity: warning
+```
+
+## Ignored Paths
+
+Recursive directory scans respect root and nested `.gitignore` files before
+adding supported source and config files to a run. `paths.ignore` is an extra
+project policy layer for paths that should remain out of normal scans even when
+they are not ignored by Git.
+
+`paths.ignore` accepts exact paths, prefix-style paths, and simple glob
+patterns. Examples:
+
+```yaml
+paths:
+  ignore:
+    - "generated/**"
+    - "fixtures/vendor/**"
+    - "src/generated-client.ts"
+```
+
+Default ignored directories are matched by first path segment:
+
+```text
+.git, .hg, .svn, .idea, .vscode, build, cache, coverage, dist,
+generated, node_modules, target, tmp, vendor
+```
+
+Use `--include-ignored` when you intentionally want to scan default ignored
+directories and Git-ignored paths. Configured `paths.ignore` entries still
+apply.
+
+## Allowlists
+
+`allowlists.acceptedAbbreviations` lowers naming-rule noise for project-specific
+short terms:
+
+```yaml
+allowlists:
+  acceptedAbbreviations:
+    - api
+    - cli
+    - env
+```
+
+`allowlists.secretPreviews` accepts redacted secret previews that are known false
+positives:
+
+```yaml
+allowlists:
+  secretPreviews:
+    - "abcd...wxyz (redacted, 32 chars)"
+```
+
+Prefer fixing false positives with a narrow config entry instead of disabling an
+entire sensitive-data rule.
+
+Naming allowlists tune the 0.1.0 naming pack without changing rule ids or
+fingerprints:
+
+| Key | Used by | Default behavior |
+| --- | --- | --- |
+| `acceptedAbbreviations` | `naming.short-variable` | Adds short names that should not be flagged. |
+| `bannedGenericNames` | `naming.generic-function` | Replaces the built-in generic function-name denylist. |
+| `booleanPrefixes` | `naming.boolean-prefix` | Replaces the accepted boolean-name prefixes such as `is`, `has`, `should`, `may`, `supports`, and `requires`. |
+| `hungarianPrefixes` | `naming.hungarian-notation` | Replaces type-style prefixes to flag. |
+| `placeholderNames` | `naming.identifier-quality`, `naming.generic-parameter` | Replaces placeholder words; numbered suffix checks stay active. |
+| `abbreviationDenylist` | `naming.abbreviation` | Replaces the opt-in abbreviation denylist. |
+| `negativeBooleanAllowed` | `naming.negative-boolean` | Replaces domain terms allowed to start with `no`. |
+| `knownAcronyms` | `naming.acronym-case` | Replaces acronyms checked for mixed casing. |
+
+For replace-style allowlists, use an empty list (`[]`) when you intentionally
+want no entries.
+
+## Rule Controls
+
+Disable a rule:
+
+```yaml
+rules:
+  docs.missing-public-doc:
+    enabled: false
+```
+
+Set one threshold and one emitted severity for a metric rule:
+
+```yaml
+rules:
+  complexity.cyclomatic:
+    threshold: 10
+    severity: warning
+  size.file-length:
+    threshold: 400
+    severity: error
+```
+
+Rules with extra tuning knobs use `options` for those knobs while the primary
+metric still uses `threshold` and `severity`:
+
+```yaml
+rules:
+  design.large-module-concentration:
+    threshold: 55
+    severity: advisory
+    options:
+      minFiles: 4
+      minLines: 80
+```
+
+List supported thresholds and options:
+
+```bash
+gruff-ts list-rules
+gruff-ts list-rules --format=json
+```
+
+## Example Project Config
+
+```yaml
+paths:
+  ignore:
+    - "generated/**"
+    - "fixtures/**"
+
+allowlists:
+  acceptedAbbreviations:
+    - api
+    - cli
+    - env
+    - id
+  secretPreviews: []
+
+rules:
+  complexity.cognitive:
+    threshold: 15
+    severity: warning
+  complexity.cyclomatic:
+    threshold: 10
+    severity: warning
+  design.deep-relative-import:
+    threshold: 2
+    severity: advisory
+  sensitive-data.high-entropy-string:
+    threshold: 32
+    severity: error
+  size.function-length:
+    threshold: 30
+    severity: warning
+  test-quality.setup-bloat:
+    threshold: 12
+    severity: advisory
+```
+
+## Adoption Defaults
+
+Two noisy-by-nature rules are present in the public catalogue but disabled by
+default in this repo config:
+
+```yaml
+rules:
+  docs.todo-density:
+    enabled: false
+  naming.abbreviation:
+    enabled: false
+```
+
+`docs.todo-without-tracking` remains enabled because it checks whether a TODO
+has owner, issue, date, ADR, or task context instead of counting raw TODO
+markers.

package/docs/RELEASING.md

@@ -0,0 +1,103 @@
+# Releasing
+
+This checklist prepares the public `@blundergoat/gruff-ts@0.1.0` release and
+subsequent `0.1.x` patch releases.
+
+## Bump The Version
+
+`scripts/bump-version.sh <semver>` updates `package.json` and
+`src/constants.ts` together so the CLI `--version` output and the published
+`@blundergoat/gruff-ts` package version cannot drift apart. For the initial
+`0.1.0` release, the version should already be `0.1.0`; use `--check` instead
+of bumping unless the release version changes.
+
+```bash
+scripts/bump-version.sh --check
+scripts/bump-version.sh 0.1.1
+scripts/bump-version.sh --check
+```
+
+The script edits files in place and does not commit or tag. After running it,
+update `CHANGELOG.md` and run `npm run check`.
+
+## Before Publishing
+
+- [ ] `scripts/bump-version.sh --check` reports the intended version.
+- [ ] `CHANGELOG.md` has an entry for the new version with today's date.
+- [ ] `README.md`, `CONTRIBUTING.md`, `SECURITY.md`, and docs under `docs/`
+      reflect any user-visible changes.
+- [ ] `.goat-flow/tasks/0.1/` has no unresolved release blockers beyond
+      explicitly accepted `human-verification-pending` milestones.
+- [ ] `LICENSE` is present and `package.json` `license` field matches.
+- [ ] `npm run check` passes.
+- [ ] `scripts/preflight-checks.sh` passes (runs `npm run check`, a full
+      `gruff-ts` self-scan, and `shellcheck` on `scripts/*.sh` when
+      `shellcheck` is installed).
+- [ ] `npm pack --dry-run` shows only publishable runtime, docs, scripts, and
+      metadata files.
+- [ ] Local smoke scan succeeds:
+
+```bash
+./bin/gruff-ts
+./bin/gruff-ts analyse fixtures/sample.ts --fail-on=none
+./bin/gruff-ts summary fixtures/sample.ts --fail-on=none
+./bin/gruff-ts report fixtures/sample.ts --output /tmp/gruff-ts-report.html
+./bin/gruff-ts list-rules
+```
+
+## Package Review
+
+Preview `@blundergoat/gruff-ts` package contents:
+
+```bash
+npm pack --dry-run
+```
+
+The package should include:
+
+- `bin/gruff-ts`
+- `src/` (all runtime `.ts` files; `src/**/*.test.ts` files are excluded by
+  `.npmignore`)
+- `scripts/` (`bump-version.sh`, `check.sh`, `preflight-checks.sh`,
+  `npm-publish.sh`, `start-dev.sh`, `test-performance.sh`)
+- `fixtures/sample.ts`
+- `README.md`
+- `CHANGELOG.md`
+- `CONTRIBUTING.md`
+- `SECURITY.md`
+- `LICENSE`
+- `docs/`
+- `package.json`
+- `tsconfig.json`
+
+The package must exclude:
+
+- `node_modules/`
+- `coverage/`
+- `.agents/`, `.claude/`, `.codex/`, `.github/`, and `.goat-flow/`
+- `AGENTS.md` and `CLAUDE.md`
+- `.gruff-ts.yaml` (this repo's local config)
+- env and secret files (`.env`, `.env.*` except `.env.example`)
+- local scratchpad or log artifacts
+- `src/**/*.test.ts`
+
+## Publish
+
+```bash
+bash scripts/npm-publish.sh
+```
+
+The script verifies npm auth, checks version lockstep, runs
+`scripts/preflight-checks.sh`, prints an `npm publish --dry-run` summary, and
+prompts before publishing.
+
+## After Publishing
+
+- [ ] Install `@blundergoat/gruff-ts` in a temporary project.
+- [ ] Run `gruff-ts --help`.
+- [ ] Run `gruff-ts analyse . --fail-on=none`.
+- [ ] Run `gruff-ts summary . --fail-on=none`.
+- [ ] Run `gruff-ts list-rules`.
+- [ ] Verify `README.md` install instructions from a clean checkout.
+- [ ] Tag the release in git (`git tag v0.1.0 && git push --tags`) and create
+      or update public release notes from `CHANGELOG.md`.

package/docs/REPORTS_AND_CI.md

@@ -0,0 +1,156 @@
+# Reports And CI
+
+This guide covers output formats, exit codes, baselines, GitHub annotations, and
+the local dashboard.
+
+## Exit Codes
+
+`analyse` exits with:
+
+- `0` when the scan completed and no finding met `--fail-on`.
+- `1` when at least one finding met `--fail-on`.
+- `2` when diagnostics were produced, such as missing inputs or parse/config
+  diagnostics.
+
+Examples:
+
+```bash
+gruff-ts analyse . --fail-on=none
+gruff-ts analyse . --fail-on=error
+gruff-ts analyse . --fail-on=warning
+```
+
+## Machine Output
+
+Full JSON report:
+
+```bash
+gruff-ts analyse . --format=json --fail-on=none > gruff-report.json
+```
+
+Hotspot summary:
+
+```bash
+gruff-ts analyse . --format=hotspot --fail-on=none > gruff-hotspots.json
+```
+
+Human scan digest:
+
+```bash
+gruff-ts summary . --fail-on=none
+```
+
+The summary output includes the scanned path, elapsed duration, total findings,
+per-pillar counts, top rules, and top file offenders.
+
+Schema strings:
+
+- `gruff.analysis.v1` for full analysis reports.
+- `gruff.baseline.v1` for baselines.
+- `gruff.hotspot.v1` for hotspot output.
+
+## GitHub Actions
+
+Use GitHub annotation output in a workflow step:
+
+```bash
+gruff-ts analyse . --format=github --fail-on=warning
+```
+
+Changed-file modes:
+
+```bash
+gruff-ts analyse . --diff=working-tree --format=github --fail-on=warning
+gruff-ts analyse . --diff=staged --format=github --fail-on=warning
+gruff-ts analyse . --diff=origin/main --format=github --fail-on=warning
+```
+
+`--diff` filters findings to changed files after analysis.
+
+For SARIF consumers, write SARIF output from `analyse` and upload the generated
+file with your platform's code-scanning upload step:
+
+```bash
+gruff-ts analyse . --format=sarif --fail-on=none > gruff.sarif
+```
+
+For a strict security-oriented gate, bypass baselines and fail on error-severity
+findings:
+
+```bash
+gruff-ts analyse . --no-baseline --fail-on=error
+```
+
+This is useful when an adoption baseline exists for general quality debt but
+security and sensitive-data errors should still break CI.
+
+## Baselines
+
+Generate an adoption baseline:
+
+```bash
+gruff-ts analyse . --generate-baseline gruff-baseline.json --fail-on=none
+```
+
+Apply it in CI:
+
+```bash
+gruff-ts analyse . --baseline gruff-baseline.json --fail-on=warning
+```
+
+Skip automatic baseline discovery:
+
+```bash
+gruff-ts analyse . --no-baseline --fail-on=none
+```
+
+Review baseline diffs carefully. A baseline suppresses matching fingerprints, so
+unexpected additions can hide findings.
+
+`report` intentionally renders raw scan results and does not accept a
+`--baseline` option. Use `analyse` for baseline-aware machine output.
+
+## HTML Reports
+
+Write a dark self-contained report:
+
+```bash
+gruff-ts report . --output gruff-report.html
+```
+
+Write report JSON:
+
+```bash
+gruff-ts report . --format=json --output gruff-report.json
+```
+
+`report` defaults to `--fail-on none`, making it suitable for local inspection
+and scheduled reporting.
+
+## Dashboard
+
+Start the dashboard:
+
+```bash
+gruff-ts dashboard --host 127.0.0.1 --port 8767 --project-root .
+```
+
+The dashboard serves:
+
+- `/` - iframe shell and controls panel.
+- `/health` - plain `ok`.
+- `/scan?projectRoot=<path>&path=<path>` - report HTML for the selected scan.
+
+Keep the dashboard on loopback unless the network is trusted. The scan endpoint
+accepts filesystem paths through request parameters.
+
+## Score History
+
+Append score history to a JSON file:
+
+```bash
+gruff-ts analyse . --history-file .gruff-history.json --fail-on=none
+```
+
+History files are local artifacts. Commit them only if your project explicitly
+wants trend data in version control.

package/fixtures/sample.ts

@@ -0,0 +1,21 @@
+export class SampleAnalyzer {
+  public name = "demo";
+  private secretUrl = "mysql://demo:password123@example.test/app";
+
+  public process(a: boolean, b: string[], c: string, d: string, e: string, f: string): void {
+    if (a) {
+      for (const item of b) {
+        if (item === c) {
+          eval(item);
+        }
+      }
+    }
+
+    const apiKey = "AKIA1111111111111111";
+    console.log(apiKey, this.secretUrl, d, e, f);
+  }
+}
+
+test("sleeps without assertion", async () => {
+  await new Promise((resolve) => setTimeout(resolve, 1));
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@blundergoat/gruff-ts",
+  "version": "0.1.0",
+  "description": "Static analyzer for TypeScript and JavaScript projects - 121 rules across 11 quality pillars, SARIF output, baselines, and a local dashboard.",
+  "license": "MIT",
+  "author": "Matthew Hansen (https://www.blundergoat.com/about)",
+  "homepage": "https://github.com/blundergoat/gruff-ts#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/blundergoat/gruff-ts.git"
+  },
+  "bugs": {
+    "url": "https://github.com/blundergoat/gruff-ts/issues"
+  },
+  "keywords": [
+    "typescript",
+    "javascript",
+    "static-analysis",
+    "code-quality",
+    "linter",
+    "analyzer",
+    "cli",
+    "sarif",
+    "baseline",
+    "fingerprint",
+    "complexity",
+    "dead-code",
+    "security",
+    "naming",
+    "dashboard",
+    "ci",
+    "github-actions",
+    "nodejs"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "type": "module",
+  "bin": {
+    "gruff-ts": "bin/gruff-ts"
+  },
+  "scripts": {
+    "check": "tsc --noEmit && npm test",
+    "test": "node --import tsx --test src/**/*.test.ts",
+    "start-dev": "tsx src/cli.ts dashboard"
+  },
+  "dependencies": {
+    "commander": "^14.0.2",
+    "tsx": "^4.21.0"
+  },
+  "devDependencies": {
+    "@blundergoat/goat-flow": "^1.6.4",
+    "@types/node": "^25.0.0",
+    "typescript": "^5.9.3"
+  }
+}

package/scripts/bump-version.sh

@@ -0,0 +1,145 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# Bump gruff-ts to a new semver in package.json and src/constants.ts in one step.
+# The CLI surfaces VERSION from src/constants.ts; package.json drives `npm publish`.
+# Keeping them in lockstep is a release invariant.
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/bump-version.sh <new-version>
+  scripts/bump-version.sh --check
+
+Arguments:
+  <new-version>   Target semver, e.g. 0.1.1, 0.2.0, 1.0.0-rc.1.
+
+Options:
+  --check         Verify package.json and src/constants.ts already agree.
+  --help, -h      Show this help.
+
+Notes:
+  Edits files in place. Does not commit or tag. Run `npm run check` afterwards.
+USAGE
+}
+
+die() {
+  printf 'bump-version: %s\n' "$*" >&2
+  exit 1
+}
+
+repo_root() {
+  local script_dir
+  script_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+  CDPATH='' cd -- "$script_dir/.." && pwd
+}
+
+read_package_version() {
+  awk -F'"' '/^[[:space:]]*"version"[[:space:]]*:/ { print $4; exit }' package.json
+}
+
+read_constants_version() {
+  awk -F'"' '/^const VERSION = "/ { print $2; exit }' src/constants.ts
+}
+
+write_package_version() {
+  local next_version="$1"
+  awk -v target="$next_version" '
+    BEGIN { done = 0 }
+    /^[[:space:]]*"version"[[:space:]]*:/ && !done {
+      sub(/"version"[[:space:]]*:[[:space:]]*"[^"]+"/, "\"version\": \"" target "\"")
+      done = 1
+    }
+    { print }
+  ' package.json > package.json.tmp
+  mv package.json.tmp package.json
+}
+
+write_constants_version() {
+  local next_version="$1"
+  awk -v target="$next_version" '
+    BEGIN { done = 0 }
+    /^const VERSION = "/ && !done {
+      print "const VERSION = \"" target "\";"
+      done = 1
+      next
+    }
+    { print }
+  ' src/constants.ts > src/constants.ts.tmp
+  mv src/constants.ts.tmp src/constants.ts
+}
+
+validate_semver() {
+  local value="$1"
+  # Standard semver: MAJOR.MINOR.PATCH with optional prerelease/build metadata.
+  local pattern='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-[0-9A-Za-z.-]+)?(\+[0-9A-Za-z.-]+)?$'
+  [[ "$value" =~ $pattern ]] || die "not a valid semver: $value"
+}
+
+main() {
+  if [[ "$#" -eq 0 ]]; then
+    usage >&2
+    exit 2
+  fi
+
+  cd "$(repo_root)"
+  [[ -f package.json ]] || die "package.json not found"
+  [[ -f src/constants.ts ]] || die "src/constants.ts not found"
+
+  case "$1" in
+    -h|--help)
+      usage
+      exit 0
+      ;;
+    --check)
+      local pkg const_
+      pkg="$(read_package_version)" || die "failed to read package.json version"
+      const_="$(read_constants_version)" || die "failed to read src/constants.ts VERSION"
+      [[ -n "$pkg" ]] || die "package.json has no \"version\" field"
+      [[ -n "$const_" ]] || die "src/constants.ts has no VERSION constant"
+      if [[ "$pkg" != "$const_" ]]; then
+        printf 'package.json (%s) and src/constants.ts (%s) disagree\n' "$pkg" "$const_" >&2
+        exit 1
+      fi
+      printf 'package.json and src/constants.ts agree on %s\n' "$pkg"
+      exit 0
+      ;;
+  esac
+
+  local next="$1"
+  validate_semver "$next"
+
+  local current
+  current="$(read_package_version)" || die "failed to read package.json version"
+  [[ -n "$current" ]] || die "package.json has no \"version\" field"
+
+  local current_const
+  current_const="$(read_constants_version)" || die "failed to read src/constants.ts VERSION"
+  [[ -n "$current_const" ]] || die "src/constants.ts has no VERSION constant"
+
+  if [[ "$current" != "$current_const" ]]; then
+    die "current versions diverge: package.json=$current src/constants.ts=$current_const (resolve manually first)"
+  fi
+
+  if [[ "$current" == "$next" ]]; then
+    printf 'already at %s; nothing to do\n' "$next"
+    exit 0
+  fi
+
+  write_package_version "$next"
+  write_constants_version "$next"
+
+  local check_pkg check_const
+  check_pkg="$(read_package_version)"
+  check_const="$(read_constants_version)"
+  [[ "$check_pkg" == "$next" ]] || die "package.json did not update cleanly (read back: ${check_pkg:-empty})"
+  [[ "$check_const" == "$next" ]] || die "src/constants.ts did not update cleanly (read back: ${check_const:-empty})"
+
+  printf 'bumped %s -> %s\n' "$current" "$next"
+  printf '  package.json\n'
+  printf '  src/constants.ts\n'
+  # shellcheck disable=SC2016
+  printf 'next: update CHANGELOG.md and run `npm run check`\n'
+}
+
+main "$@"

package/scripts/check.sh

@@ -0,0 +1,4 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+npm run check