@blundergoat/gruff-ts 0.1.0 → 0.1.1

package/docs/output-formats.md

@@ -0,0 +1,65 @@
+# Output Formats
+
+`gruff-ts analyse --format <format>` renders the same analysis data for
+different consumers. The combined legacy page remains at
+[Reports And CI](reports-and-ci.md).
+
+## Text
+
+Use `text` for local terminal scans:
+
+```sh
+./bin/gruff-ts analyse src --format text --fail-on=warning
+```
+
+## JSON
+
+Use `json` for automation. JSON reports use `gruff.analysis.v1`.
+
+```sh
+./bin/gruff-ts analyse src --format=json --fail-on=none > gruff-ts.json
+```
+
+## HTML
+
+Use `html` for archived human review or dashboard scan output:
+
+```sh
+./bin/gruff-ts report src --format=html --output gruff-ts.html
+```
+
+## Markdown
+
+Use `markdown` for pull request comments and release notes.
+
+## GitHub
+
+Use `github` inside GitHub Actions to emit workflow annotations.
+
+## Hotspot
+
+Use `hotspot` for compact score and offender analysis.
+
+## SARIF
+
+Use `sarif` for GitHub code scanning or other SARIF consumers:
+
+```sh
+./bin/gruff-ts analyse src --format=sarif --fail-on=none > gruff-ts.sarif
+```
+
+## Summary
+
+`summary` has its own compact text/JSON contract:
+
+```sh
+./bin/gruff-ts summary src --format=json --top=5 --fail-on=none
+```
+
+TypeScript keeps the existing `summary` analysis flags such as `--diff`,
+`--baseline`, and `--generate-baseline` as extensions.
+
+## Exit Codes
+
+`analyse` exits `1` when at least one finding meets `--fail-on`. Use
+`--fail-on none` for report-only jobs.

package/docs/{RELEASING.md → releasing.md}

@@ -5,11 +5,11 @@ 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.
+`scripts/bump-version.sh <semver>` updates `package.json`,
+`package-lock.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
@@ -30,9 +30,10 @@ update `CHANGELOG.md` and run `npm run check`.
       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).
+- [ ] `scripts/preflight-checks.sh` passes (checks version lockstep and npm
+      publication status, runs `npm audit --audit-level=moderate`,
+      `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:
@@ -58,8 +59,9 @@ 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`)
+- `scripts/` (`bump-version.sh`, `check.sh`, `dependency-install.sh`,
+  `dependency-update.sh`, `preflight-checks.sh`, `npm-publish.sh`,
+  `start-dev.sh`, `test-performance.sh`)
 - `fixtures/sample.ts`
 - `README.md`
 - `CHANGELOG.md`

package/docs/rules.md

@@ -0,0 +1,177 @@
+# Rules
+
+`gruff-ts` exposes 119 rules across 11 pillars. This list is generated from the
+public rule catalogue used by `gruff-ts list-rules`; severity, confidence,
+thresholds, and option names are the defaults before project config overrides.
+
+Use the CLI when you need machine-readable metadata:
+
+```bash
+gruff-ts list-rules --format=json
+```
+
+## Pillar Counts
+
+- complexity: 3
+- dead-code: 1
+- design: 6
+- documentation: 17
+- maintainability: 14
+- modernisation: 14
+- naming: 10
+- security: 27
+- sensitive-data: 8
+- size: 4
+- test-quality: 15
+
+## Complexity
+
+- `complexity.cognitive` (warning; high confidence; threshold 15): Flags functions with high combined branch and nesting complexity.
+- `complexity.cyclomatic` (warning; high confidence; threshold 15): Flags functions with many independent branch paths.
+- `complexity.npath` (warning; medium confidence; threshold 200): Flags functions with high approximate NPath complexity.
+
+## Dead Code
+
+- `dead-code.unused-private-method` (advisory; low confidence): Flags private methods without an apparent same-file call site.
+
+## Design
+
+- `design.circular-import` (warning; medium confidence): Flags simple relative import cycles inside the discovered source set.
+- `design.deep-relative-import` (advisory; medium confidence; threshold 2): Flags relative imports that climb too many parent directories.
+- `design.god-function` (warning; high confidence): Flags functions that are both long and complex.
+- `design.large-module-concentration` (advisory; medium confidence; threshold 55; options: minFiles, minLines): Flags a production module that dominates project source lines.
+- `design.package-bin-missing` (warning; high confidence): Flags package bin entries that point at missing files.
+- `design.package-bin-not-executable` (warning; high confidence): Flags package bin targets that are not executable.
+
+## Documentation
+
+- `docs.fixture-purpose-missing` (advisory; medium confidence): Flags large or scanner-relevant fixtures without a nearby purpose comment.
+- `docs.magic-threshold-without-rationale` (advisory; medium confidence): Flags threshold-like numeric values without a nearby rationale comment.
+- `docs.missing-error-behavior-doc` (advisory; medium confidence): Flags commented functions whose error behavior is not described.
+- `docs.missing-file-overview` (advisory; medium confidence): Flags source files without a top-of-file purpose comment.
+- `docs.missing-function-doc` (advisory; medium confidence): Flags functions without a leading maintainer comment.
+- `docs.missing-interface-doc` (advisory; medium confidence): Flags interfaces without a leading maintainer comment.
+- `docs.missing-invariant-doc` (advisory; medium confidence): Flags commented declarations that own schema, fingerprint, baseline, or determinism contracts without saying so.
+- `docs.missing-param-tag` (advisory; medium confidence): Flags documented exports with parameters missing @param tags.
+- `docs.missing-public-doc` (advisory; medium confidence): Flags exported class, type, and enum APIs without a nearby doc comment.
+- `docs.missing-return-tag` (advisory; medium confidence): Flags documented non-void exports without @returns.
+- `docs.missing-side-effect-doc` (advisory; medium confidence): Flags commented functions that perform observable side effects without naming them.
+- `docs.missing-why-for-complex-code` (advisory; medium confidence): Flags comments on complex functions that do not explain why the shape exists.
+- `docs.stale-comment` (advisory; medium confidence): Flags comments that reference missing files, unknown rules, stale CLI flags, or the wrong declaration.
+- `docs.stale-param-tag` (advisory; medium confidence): Flags @param tags for parameters no longer in the signature.
+- `docs.suppression-without-rationale` (advisory; medium confidence): Flags lint, formatter, coverage, or tool suppressions without a maintainer rationale.
+- `docs.todo-without-tracking` (advisory; high confidence): Flags TODO, FIXME, HACK, and XXX comments without tracking context.
+- `docs.useless-docblock` (advisory; medium confidence): Flags comments or docblocks that only restate the symbol name.
+
+## Modernisation
+
+- `modernisation.date-now-candidate` (advisory; high confidence): Flags verbose current-time expressions that can use Date.now().
+- `modernisation.double-cast` (warning; medium confidence): Flags casts through unknown or any into another type.
+- `modernisation.loose-equality` (advisory; medium confidence): Flags loose equality comparisons that may coerce values.
+- `modernisation.non-null-assertion` (warning; medium confidence): Flags non-null assertions that bypass null checks.
+- `modernisation.nullish-coalescing-candidate` (advisory; medium confidence): Flags || fallbacks that may erase valid falsy values.
+- `modernisation.object-spread-candidate` (advisory; medium confidence): Flags Object.assign({}, ...) cloning that can use object spread.
+- `modernisation.optional-chaining-candidate` (advisory; medium confidence): Flags repeated guard-and-property access patterns.
+- `modernisation.public-property` (advisory; high confidence): Flags public class properties that expose representation.
+- `modernisation.readonly-property-candidate` (advisory; medium confidence): Flags class properties that appear readonly-worthy.
+- `modernisation.ts-comment-without-rationale` (warning; medium confidence): Flags TypeScript suppression comments without a rationale.
+- `modernisation.tsconfig-exact-optional-disabled` (warning; high confidence): Flags tsconfig files without exactOptionalPropertyTypes enabled.
+- `modernisation.tsconfig-index-safety-disabled` (warning; high confidence): Flags tsconfig files without noUncheckedIndexedAccess enabled.
+- `modernisation.tsconfig-strict-disabled` (warning; high confidence): Flags tsconfig files without strict mode enabled.
+- `modernisation.var-declaration` (advisory; high confidence): Flags var declarations.
+
+## Naming
+
+- `naming.acronym-case` (advisory; medium confidence): Flags mixed casings of a known acronym in one file.
+- `naming.boolean-prefix` (advisory; medium confidence): Flags boolean names without intent-revealing prefixes on declarations, function parameters (typed `: boolean` or with `= true|false` default), and interface/type-literal fields.
+- `naming.class-file-mismatch` (advisory; medium confidence): Flags exported classes whose name differs from the file name.
+- `naming.generic-function` (advisory; high confidence): Flags generic function names that hide intent.
+- `naming.generic-parameter` (advisory; medium confidence; options: minCyclomatic, minLineCount, minParameters): Flags placeholder parameter names in multi-parameter, long, exported, or complex functions.
+- `naming.hungarian-notation` (advisory; medium confidence): Flags identifiers named after storage type prefixes.
+- `naming.identifier-quality` (advisory; medium confidence): Flags placeholder or numbered identifiers on declarations, function parameters, and destructured locals.
+- `naming.inconsistent-casing` (advisory; medium confidence): Flags the same canonical identifier appearing in two different surface forms (for example CONSTANT_CASE and camelCase) in one file.
+- `naming.negative-boolean` (advisory; medium confidence): Flags boolean identifiers framed as a negation on declarations, parameters, and interface fields.
+- `naming.short-variable` (advisory; medium confidence): Flags very short variable names outside common loop counters; covers declarations, function parameters, and destructured locals.
+
+## Security
+
+- `security.async-foreach` (warning; medium confidence): Flags async callbacks passed to forEach.
+- `security.disabled-tls-verification` (error; high confidence): Flags code that disables TLS certificate verification.
+- `security.document-write` (warning; high confidence): Flags document.write usage.
+- `security.dynamic-regexp` (warning; medium confidence): Flags external input used to construct regular expressions.
+- `security.eval-call` (error; high confidence): Flags eval() dynamic code execution.
+- `security.floating-promise` (warning; medium confidence): Flags promise-like calls without await, return, or void.
+- `security.github-actions-broad-permissions` (warning; medium confidence): Flags GitHub Actions workflows that grant broad write permissions.
+- `security.github-actions-pull-request-target` (warning; medium confidence): Flags pull_request_target workflows paired with risky execution or trust context.
+- `security.github-actions-remote-shell` (warning; medium confidence): Flags workflow run steps that pipe remote downloads to a shell.
+- `security.github-actions-secrets-in-pr` (warning; medium confidence): Flags pull request workflows that reference GitHub secrets.
+- `security.github-actions-unpinned-action` (warning; medium confidence): Flags third-party GitHub Actions that are not pinned to a full commit SHA.
+- `security.inner-html` (warning; high confidence): Flags innerHTML assignment.
+- `security.insecure-random` (warning; high confidence): Flags Math.random usage in source.
+- `security.javascript-url` (error; high confidence): Flags javascript: URL literals that execute script.
+- `security.new-function` (error; high confidence): Flags Function constructor dynamic code execution.
+- `security.open-redirect-candidate` (warning; medium confidence): Flags external input sent to redirect or navigation sinks.
+- `security.path-traversal-candidate` (warning; medium confidence): Flags external input sent to filesystem path sinks.
+- `security.process-exec` (warning; high confidence): Flags child-process execution calls.
+- `security.proto-access` (warning; medium confidence): Flags direct __proto__ access that can enable prototype pollution.
+- `security.remote-install-script` (error; medium confidence): Flags package scripts that pipe remote content to a shell.
+- `security.risky-lifecycle-script` (warning; medium confidence): Flags package lifecycle scripts that run automatically.
+- `security.sql-concatenation` (warning; high confidence): Flags SQL text composed with runtime string interpolation.
+- `security.ssrf-candidate` (warning; medium confidence): Flags external input sent to network request sinks.
+- `security.string-timer` (warning; high confidence): Flags string callbacks passed to timers.
+- `security.throw-non-error` (warning; medium confidence): Flags thrown non-Error values.
+- `security.url-dependency` (warning; medium confidence): Flags dependencies installed from URL or git specs.
+- `security.weak-crypto` (warning; high confidence): Flags weak crypto primitives such as md5, sha1, or createCipher.
+
+## Sensitive Data
+
+- `sensitive-data.api-key-pattern` (error; high confidence): Flags vendor API key patterns.
+- `sensitive-data.aws-access-key` (error; high confidence): Flags AWS access key looking values.
+- `sensitive-data.database-url-password` (error; high confidence): Flags database URLs that include passwords.
+- `sensitive-data.hardcoded-env-value` (error; medium confidence; threshold 16): Flags environment-style secret values committed in text.
+- `sensitive-data.high-entropy-string` (error; medium confidence; threshold 32): Flags high-entropy string literals that may be secrets.
+- `sensitive-data.jwt-token` (error; high confidence): Flags JWT-looking token literals.
+- `sensitive-data.pii-pattern` (error; high confidence): Flags PII-like identifier patterns.
+- `sensitive-data.private-key` (error; high confidence): Flags private key block markers.
+
+## Size
+
+- `size.file-length` (warning; high confidence; threshold 750): Flags files longer than the configured threshold.
+- `size.function-length` (warning; high confidence; threshold 200): Flags functions longer than the configured threshold.
+- `size.parameter-count` (warning; high confidence; threshold 7): Flags functions with too many parameters.
+- `size.stylesheet-length` (warning; high confidence; threshold 1500): Flags stylesheets longer than the configured threshold.
+
+## Test Quality
+
+- `test-quality.conditional-logic` (advisory; high confidence): Flags tests with conditional logic.
+- `test-quality.exception-type-only` (advisory; high confidence): Flags tests that only assert exception type.
+- `test-quality.global-state-mutation` (warning; high confidence): Flags tests mutating process or global runtime state.
+- `test-quality.loop-in-test` (advisory; high confidence): Flags loops inside test bodies.
+- `test-quality.magic-number-assertion` (advisory; medium confidence): Flags assertions against unexplained numeric literals.
+- `test-quality.missing-nearby-test` (advisory; medium confidence): Flags exported production files without nearby tests.
+- `test-quality.mock-only-test` (advisory; high confidence): Flags tests that only verify mock interaction.
+- `test-quality.no-assertions` (warning; high confidence): Flags tests without apparent assertions.
+- `test-quality.no-throw-only-test` (advisory; high confidence): Flags tests that only assert code does not throw.
+- `test-quality.only-skip` (advisory; high confidence): Flags focused or skipped test markers.
+- `test-quality.setup-bloat` (advisory; medium confidence; threshold 12): Flags tests with too much setup before the first assertion.
+- `test-quality.sleep-in-test` (advisory; high confidence): Flags sleeps in tests.
+- `test-quality.snapshot-only-test` (advisory; high confidence): Flags tests that rely only on snapshots.
+- `test-quality.trivial-assertion` (warning; high confidence): Flags tautological assertions.
+- `test-quality.unused-mock` (advisory; medium confidence): Flags mocks created but not used.
+
+## Maintainability
+
+- `waste.any-type` (warning; high confidence): Flags any type usage.
+- `waste.broad-runtime-version` (advisory; medium confidence): Flags broad runtime dependency version ranges.
+- `waste.commented-out-code` (advisory; high confidence): Flags comments that appear to contain disabled code.
+- `waste.console-log` (advisory; high confidence): Flags console log/debug calls in source.
+- `waste.empty-function` (advisory; high confidence): Flags functions with no executable body.
+- `waste.exported-any` (warning; medium confidence): Flags exported APIs exposing any.
+- `waste.redundant-boolean-cast` (advisory; medium confidence): Flags redundant boolean casts in condition expressions.
+- `waste.redundant-variable` (advisory; medium confidence): Flags variables returned immediately after assignment.
+- `waste.swallowed-catch` (warning; medium confidence): Flags empty catch blocks.
+- `waste.unreachable-code` (warning; high confidence): Flags statements after terminating statements.
+- `waste.unused-import` (advisory; medium confidence): Flags named imports with no apparent usage.
+- `waste.unused-parameter` (advisory; medium confidence): Flags parameters with no apparent usage.
+- `waste.useless-catch` (advisory; high confidence): Flags catch blocks that only rethrow the caught value.
+- `waste.useless-return` (advisory; medium confidence): Flags terminal bare return statements in void functions.

package/package.json

@@ -1,7 +1,7 @@
 {
   "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.",
+  "version": "0.1.1",
+  "description": "Static analyzer for TypeScript and JavaScript projects - 119 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",

package/scripts/bump-version.sh

@@ -1,9 +1,9 @@
 #!/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.
+# Bump gruff-ts to a new semver in package.json, package-lock.json, and src/constants.ts.
+# The CLI surfaces VERSION from src/constants.ts; package metadata drives `npm publish`.
+# Keeping all release version surfaces in lockstep is a release invariant.
 
 usage() {
   cat <<'USAGE'
@@ -15,7 +15,7 @@ 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.
+  --check         Verify package.json, package-lock.json, and src/constants.ts already agree.
   --help, -h      Show this help.
 
 Notes:
@@ -42,6 +42,14 @@ read_constants_version() {
   awk -F'"' '/^const VERSION = "/ { print $2; exit }' src/constants.ts
 }
 
+read_package_lock_version() {
+  node -e 'const fs = require("node:fs"); const data = JSON.parse(fs.readFileSync("package-lock.json", "utf8")); process.stdout.write(String(data.version ?? ""));'
+}
+
+read_package_lock_package_version() {
+  node -e 'const fs = require("node:fs"); const data = JSON.parse(fs.readFileSync("package-lock.json", "utf8")); process.stdout.write(String(data.packages?.[""]?.version ?? ""));'
+}
+
 write_package_version() {
   local next_version="$1"
   awk -v target="$next_version" '
@@ -69,13 +77,50 @@ write_constants_version() {
   mv src/constants.ts.tmp src/constants.ts
 }
 
+write_package_lock_version() {
+  local next_version="$1"
+  node - "$next_version" <<'NODE'
+const fs = require("node:fs");
+
+const target = process.argv[2];
+const lockPath = "package-lock.json";
+const lock = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+
+lock.version = target;
+if (!lock.packages || typeof lock.packages !== "object" || !lock.packages[""]) {
+  throw new Error('package-lock.json missing packages[""] root package entry');
+}
+lock.packages[""].version = target;
+
+fs.writeFileSync(`${lockPath}.tmp`, `${JSON.stringify(lock, null, 2)}\n`);
+NODE
+  mv package-lock.json.tmp package-lock.json
+}
+
 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.-]+)?$'
+  local pattern='^(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(-((0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*)(\.(0|[1-9][0-9]*|[0-9A-Za-z-]*[A-Za-z-][0-9A-Za-z-]*))*))?(\+([0-9A-Za-z-]+(\.[0-9A-Za-z-]+)*))?$'
   [[ "$value" =~ $pattern ]] || die "not a valid semver: $value"
 }
 
+check_version_lockstep() {
+  local pkg const_ lock lock_package
+  pkg="$(read_package_version)" || die "failed to read package.json version"
+  const_="$(read_constants_version)" || die "failed to read src/constants.ts VERSION"
+  lock="$(read_package_lock_version)" || die "failed to read package-lock.json root version"
+  lock_package="$(read_package_lock_package_version)" || die "failed to read package-lock.json package version"
+  [[ -n "$pkg" ]] || die "package.json has no \"version\" field"
+  [[ -n "$const_" ]] || die "src/constants.ts has no VERSION constant"
+  [[ -n "$lock" ]] || die "package-lock.json has no root \"version\" field"
+  [[ -n "$lock_package" ]] || die 'package-lock.json has no packages[""].version field'
+  if ! [[ "$pkg" == "$const_" && "$pkg" == "$lock" && "$pkg" == "$lock_package" ]]; then
+    printf 'version surfaces disagree: package.json=%s src/constants.ts=%s package-lock.json=%s package-lock.json packages[""]=%s\n' "$pkg" "$const_" "$lock" "$lock_package" >&2
+    exit 1
+  fi
+  printf 'package.json, package-lock.json, and src/constants.ts agree on %s\n' "$pkg"
+}
+
 main() {
   if [[ "$#" -eq 0 ]]; then
     usage >&2
@@ -84,6 +129,7 @@ main() {
 
   cd "$(repo_root)"
   [[ -f package.json ]] || die "package.json not found"
+  [[ -f package-lock.json ]] || die "package-lock.json not found"
   [[ -f src/constants.ts ]] || die "src/constants.ts not found"
 
   case "$1" in
@@ -92,16 +138,7 @@ main() {
       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"
+      check_version_lockstep
       exit 0
       ;;
   esac
@@ -117,8 +154,14 @@ main() {
   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)"
+  local current_lock current_lock_package
+  current_lock="$(read_package_lock_version)" || die "failed to read package-lock.json root version"
+  current_lock_package="$(read_package_lock_package_version)" || die "failed to read package-lock.json package version"
+  [[ -n "$current_lock" ]] || die "package-lock.json has no root \"version\" field"
+  [[ -n "$current_lock_package" ]] || die 'package-lock.json has no packages[""].version field'
+
+  if ! [[ "$current" == "$current_const" && "$current" == "$current_lock" && "$current" == "$current_lock_package" ]]; then
+    die "current versions diverge: package.json=$current src/constants.ts=$current_const package-lock.json=$current_lock package-lock.json packages[\"\"]=$current_lock_package (resolve manually first)"
   fi
 
   if [[ "$current" == "$next" ]]; then
@@ -128,15 +171,21 @@ main() {
 
   write_package_version "$next"
   write_constants_version "$next"
+  write_package_lock_version "$next"
 
-  local check_pkg check_const
+  local check_pkg check_const check_lock check_lock_package
   check_pkg="$(read_package_version)"
   check_const="$(read_constants_version)"
+  check_lock="$(read_package_lock_version)"
+  check_lock_package="$(read_package_lock_package_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})"
+  [[ "$check_lock" == "$next" ]] || die "package-lock.json did not update cleanly (read back: ${check_lock:-empty})"
+  [[ "$check_lock_package" == "$next" ]] || die "package-lock.json packages[\"\"] did not update cleanly (read back: ${check_lock_package:-empty})"
 
   printf 'bumped %s -> %s\n' "$current" "$next"
   printf '  package.json\n'
+  printf '  package-lock.json\n'
   printf '  src/constants.ts\n'
   # shellcheck disable=SC2016
   printf 'next: update CHANGELOG.md and run `npm run check`\n'

package/scripts/dependency-install.sh

@@ -0,0 +1,96 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+NPM_AUDIT_LEVEL="${NPM_AUDIT_LEVEL:-moderate}"
+RUN_AUDIT=1
+RUN_CHECK=0
+
+usage() {
+  cat <<'USAGE'
+Usage:
+  scripts/dependency-install.sh [options]
+
+Installs dependencies from package-lock.json using npm ci.
+
+Options:
+  --audit-level LEVEL  npm audit threshold (default: moderate)
+  --no-audit           Skip npm audit after install
+  --check              Run npm run check after install and audit
+  --help, -h           Show this help
+
+Environment:
+  NPM_AUDIT_LEVEL      Default audit threshold when --audit-level is omitted
+USAGE
+}
+
+die() {
+  printf 'dependency-install: %s\n' "$*" >&2
+  exit 1
+}
+
+repo_root() {
+  local script_dir
+  script_dir="$(CDPATH='' cd -- "$(dirname -- "${BASH_SOURCE[0]}")" && pwd)"
+  CDPATH='' cd -- "$script_dir/.." && pwd
+}
+
+parse_args() {
+  while [[ "$#" -gt 0 ]]; do
+    case "$1" in
+      --audit-level)
+        [[ "$#" -ge 2 ]] || die "--audit-level requires a value"
+        NPM_AUDIT_LEVEL="$2"
+        shift
+        ;;
+      --audit-level=*)
+        NPM_AUDIT_LEVEL="${1#*=}"
+        ;;
+      --no-audit)
+        RUN_AUDIT=0
+        ;;
+      --check)
+        RUN_CHECK=1
+        ;;
+      --help|-h)
+        usage
+        exit 0
+        ;;
+      *)
+        usage >&2
+        die "unknown option: $1"
+        ;;
+    esac
+    shift
+  done
+}
+
+require_tool() {
+  command -v "$1" >/dev/null 2>&1 || die "$1 is required"
+}
+
+main() {
+  parse_args "$@"
+  cd "$(repo_root)"
+
+  require_tool node
+  require_tool npm
+  [[ -f package.json ]] || die "package.json not found"
+  [[ -f package-lock.json ]] || die "package-lock.json not found"
+
+  echo "--- Install dependencies ---"
+  npm ci
+
+  if [[ "$RUN_AUDIT" -eq 1 ]]; then
+    echo ""
+    echo "--- Dependency audit ---"
+    npm audit --audit-level="$NPM_AUDIT_LEVEL"
+  fi
+
+  if [[ "$RUN_CHECK" -eq 1 ]]; then
+    echo ""
+    echo "--- TypeScript + tests ---"
+    npm run check
+  fi
+}
+
+main "$@"