eslint-plugin-traceability 1.7.0 → 1.8.0

package/docs/decisions/adr-pre-push-parity.md

@@ -0,0 +1,112 @@
+# ADR: Pre-push vs CI parity for quality checks
+
+Status: Accepted
+Date: 2025-11-20
+
+## Context
+
+The project has a comprehensive CI/CD pipeline (`.github/workflows/ci-cd.yml`) that runs on every push to `main` and on pull requests:
+
+- `npm run build`
+- `npm run type-check`
+- `npm run lint`
+- `npm run format:check`
+- `npm run duplication`
+- `npm run check:traceability`
+- `npm test -- --coverage`
+- `npm run audit:ci`
+- `npm run safety:deps`
+- `npm audit --production --audit-level=high`
+- `npm run audit:dev-high`
+- plus post-build checks such as `npm run lint-plugin-check` and a smoke test of the published package.
+
+Locally, we previously used a fast subset of these checks (`ci-verify:fast`) as a pre-push safeguard to keep `main` healthy without making every push prohibitively slow. The existing `ci-verify` and `ci-verify:fast` scripts are:
+
+```jsonc
+// package.json
+"ci-verify": "npm run type-check && npm run lint && npm run format:check && npm run duplication && npm run check:traceability && npm test && npm run audit:ci && npm run safety:deps",
+"ci-verify:fast": "npm run type-check && npm run check:traceability && npm run duplication && jest --ci --bail --passWithNoTests --testPathPatterns 'tests/(unit|fast)'"
+```
+
+Running only the fast subset on every `git push` reduced local feedback times, but it also allowed a class of failures (lint, formatting, full test suite, audits) to be detected **only** in CI, leading to avoidable red pipelines and additional iteration overhead.
+
+We now want **full parity** between local pre-push checks and the core CI quality checks, so that a successful push locally very strongly predicts CI success. A separate, optional fast-check path remains available for developers who want a quicker pre-flight before doing heavier work.
+
+## Decision
+
+- The `.husky/pre-push` hook will run **`npm run ci-verify:full`**, a script that mirrors the **full CI-equivalent quality gate** (build, type-check, lint, formatting, duplication, traceability, full tests, and audits).
+- We formally accept that pre-push checks are now a **comprehensive gate** focused on matching the CI quality bar, even at the cost of longer local push times.
+- The previous fast-only `ci-verify:fast` remains available as an **optional, manual command** but is no longer wired into the pre-push hook.
+- The **authoritative, complete gate** for `main` remains the CI/CD workflow on GitHub Actions, which may include additional CI-only post-build/post-publish steps.
+
+Concretely, `.husky/pre-push` runs:
+
+```sh
+npm run ci-verify:full && echo "Pre-push full CI-equivalent checks completed"
+```
+
+and **does not** omit any of the core CI quality checks represented in `ci-verify:full`. The only remaining divergence is that certain CI-only steps (for example, publish-time smoke tests and release automation such as `semantic-release`) continue to run **only in CI**.
+
+## Rationale
+
+- **Reduce CI-only failures**: The earlier approach (pre-push running only `ci-verify:fast`) led to recurring CI failures for checks not covered locally (lint, formatting, full tests, audits). Promoting a full CI-equivalent sequence to pre-push significantly lowers this risk.
+- **Stronger local guarantees**: Developers can treat a successful push as a strong indicator that CI will also pass, improving confidence in trunk-based development and reducing context-switching caused by failed pipelines.
+- **Explicit trade-off**: We accept longer pre-push times in exchange for fewer broken builds on `main` and fewer re-runs of CI for easily preventable issues.
+- **Optional fast path preserved**: For workflows where rapid feedback is still important (e.g., early in a feature branch), `npm run ci-verify:fast` remains available as a manual pre-flight, but it is not the enforced gate.
+
+## Constraints and guardrails
+
+To keep pre-push and CI aligned while retaining some flexibility, we adopt the following constraints:
+
+1. **Minimum checks in `ci-verify:full`**
+   - `ci-verify:full` (currently `ci-verify`) must remain the **full CI-equivalent quality sequence** runnable locally. At a minimum, it must include:
+     - `npm run build` (or equivalent build step, if present)
+     - `npm run type-check`
+     - `npm run lint`
+     - `npm run format:check`
+     - `npm run duplication`
+     - `npm run check:traceability`
+     - The main Jest test suite (including coverage configuration as enforced in CI)
+     - Security and dependency checks (`npm run audit:ci`, `npm run safety:deps`, and other CI-enforced audits)
+   - `.husky/pre-push` must invoke this full sequence (or its future renamed equivalent).
+   - `ci-verify:fast` is now a **manual, optional** helper for developers and is not the pre-push script.
+
+2. **Relationship to `ci-verify:full` and CI**
+   - `ci-verify:full` is the **script-level mirror** of the CI quality gates, intended to be as close as practical to what CI runs before any deploy/release steps.
+   - CI may include additional steps that are inherently CI-only (e.g., publish-time smoke tests, `lint-plugin-check` on the published artifact, release automation). These are not expected to run locally.
+   - `ci-verify:fast` is a secondary, **manual fast check** that can be used by contributors for quick feedback but does not replace `ci-verify:full` as the enforced pre-push gate.
+
+3. **Failure patterns and escalation**
+   - If CI frequently fails **despite** `ci-verify:full` being enforced pre-push (e.g., due to extremely slow or flaky steps, environment-specific issues, or CI-only checks beyond `ci-verify:full`):
+     - Maintain a log of which steps are responsible.
+     - Consider optimizing or parallelizing the slowest steps in `ci-verify:full`.
+     - As a last resort, consider **temporarily relaxing** the pre-push hook (for example, moving some especially slow but low-signal checks back to CI-only) while updating this ADR to describe the new contract.
+
+4. **Documentation linkage**
+   - `.husky/pre-push` and contributor docs must reference this ADR so maintainers and contributors can discover and understand the policy.
+   - Any changes to the composition of `ci-verify:full` or to which script `.husky/pre-push` invokes must be reflected here.
+
+## Rollback / migration plan
+
+If we decide that pre-push parity with CI is too costly in practice (for example, due to repeatedly long pre-push times in common workflows), we can revert to the previous "fast subset" approach or a hybrid.
+
+1. **Option A – Roll back to fast-only pre-push (`ci-verify:fast`)**
+   - Change `.husky/pre-push` to run `npm run ci-verify:fast` instead of `ci-verify:full`.
+   - Explicitly document that pre-push is once again a **fast, partial gate**, and that contributors are encouraged to run `npm run ci-verify:full` manually before risky pushes.
+   - Update this ADR (or supersede it with a new one) to reflect the rollback and clearly describe which CI checks are no longer enforced pre-push.
+
+2. **Option B – Hybrid / optimized pre-push**
+   - If full parity is mostly helpful but certain steps are disproportionately slow or flaky, adjust `ci-verify:full` and the pre-push hook to:
+     - Keep the highest-value checks (type-check, lint, format, core tests, audits that commonly fail) in pre-push.
+     - Move only the least valuable or inherently CI-only steps back to CI.
+   - Document any deviation from full parity in this ADR, including which checks are pre-push vs CI-only.
+
+3. **Option C – Workflow-specific relaxation**
+   - For specific workflows (e.g., automated tooling, bots, or bulk operations) where long pre-push times are impractical:
+     - Document how to temporarily bypass the pre-push hook (standard Husky guidance) while keeping it enabled for interactive developer usage.
+     - Consider project-level policies for when bypassing is acceptable.
+   - If bypassing becomes common, reassess whether enforced full parity is still the right default.
+
+Any significant change to pre-push behavior—including rolling back to `ci-verify:fast` as the main gate—**must** be accompanied by an ADR update or a new ADR that supersedes this one.
+
+Created autonomously by voder.ai

package/docs/decisions/code-quality-ratcheting-plan.md

@@ -0,0 +1,53 @@
+---
+status: "accepted"
+date: 2025-11-17
+decision-makers: [Development Team]
+consulted: [Implementation Plan, ESLint Documentation]
+informed: [All Contributors]
+---
+
+# Code Quality Ratcheting Plan
+
+## Context and Decision Drivers
+
+The project currently enforces maintainability through ESLint rules `max-lines-per-function` and `complexity` with thresholds that allow overly large functions and moderately high cyclomatic complexity. While these thresholds have kept development velocity high, they permit functions and branches that are too complex to maintain effectively over time.
+
+To systematically improve code quality and maintainability, we will implement an incremental ratcheting plan that gradually tightens these ESLint rules across multiple sprints, ensuring continuous improvement without large-scale refactors in a single release.
+
+## Considered Options
+
+1. **Immediate Strict Enforcement**: Set aggressive thresholds (e.g., 50 lines/function, complexity max 10) immediately.
+2. **No Change**: Maintain current thresholds indefinitely.
+3. **Incremental Ratcheting**: Gradually reduce thresholds over successive sprints.
+
+### Decision Outcome
+
+We choose **Incremental Ratcheting** (Option 3) to balance maintainability improvements with manageable refactoring efforts.
+
+## Ratcheting Schedule
+
+| Sprint         | `max-lines-per-function` |         `complexity` | Success Criteria                            |
+| -------------- | -----------------------: | -------------------: | ------------------------------------------- |
+| Now (Sprint 0) |                       65 |                   18 | No ESLint violations against new thresholds |
+| Sprint 1 (2w)  |                       60 |                   16 | All functions ≤60 lines, all methods comply |
+| Sprint 2 (4w)  |                       55 |                   14 | All functions ≤55 lines, complexity ≤14     |
+| Sprint 3 (6w)  |                       50 |                   12 | All functions ≤50 lines, complexity ≤12     |
+| Final Review   |         Default (revert) | Default (see ESLint) | Remove explicit overrides, rely on defaults |
+
+- **Timeline**: Each sprint is bi-weekly (2 weeks) aligned with release cycles.
+- **Metrics**: ESLint violations count per rule must be zero at each milestone.
+- **Automation**: CI will enforce thresholds and fail builds on any violations.
+
+## Implementation Steps
+
+1. Update `eslint.config.js` to set the `max-lines-per-function` and `complexity` rules to the Sprint 0 values.
+2. Configure CI/CD to fail on any rule violations by running `npm run lint -- --max-warnings=0`.
+3. Identify and refactor existing functions and branches that exceed the new thresholds.
+4. At the end of each sprint, verify zero violations, then ratchet thresholds to the next values.
+5. After the final Sprint, remove explicit rule overrides to revert to ESLint defaults.
+
+## Future Review
+
+- At each sprint boundary, review the ratcheting plan and adjust if necessary.
+- Consider additional ratcheting for other style rules (e.g., `max-lines-per-file`, `max-params`).
+- Document the ratcheting process in CONTRIBUTING.md for new contributors.

package/docs/dependency-health.md

@@ -0,0 +1,238 @@
+# Dependency Health and dry-aged-deps Usage
+
+This document explains how we assess and maintain dependency health in this project, with a focus on the `dry-aged-deps` maturity tool, how it interacts with our CI/CD pipeline, and how its outputs are incorporated into security incident and risk-acceptance records.
+
+This is **internal/development-facing documentation** for maintainers and advanced contributors. The guarantees in the README and other user docs are **plain-language summaries** that are _backed by_ the processes described here, not the other way around.
+
+## Canonical Commands
+
+Contributors and automation **must** use the following npm scripts when working with dependency health.
+
+### 1. Dependency maturity (dry-aged-deps)
+
+We use [`dry-aged-deps`](https://github.com/voder-ai/dry-aged-deps) to identify dependency upgrade candidates that are both time-tested and free from known vulnerabilities, for **both production and development dependencies**.
+
+- **Script**: `npm run deps:maturity`
+- **CLI**: `dry-aged-deps`
+
+Run with JSON output (recommended for reviews and CI tooling):
+
+```bash
+npm run deps:maturity -- --format=json
+```
+
+To additionally enforce exit codes based on health status, use the `--check` flag:
+
+```bash
+npm run deps:maturity -- --format=json --check
+```
+
+The JSON report is written to **stdout**. In CI, `npm run safety:deps` wraps this command and persists the latest report to `ci/dry-aged-deps.json` as a build artifact for later inspection and for use in incident documentation.
+
+**Important behavior:**
+
+- `dry-aged-deps` is **advisory only**:
+  - It **does not** automatically modify `package.json`, `package-lock.json`, or install anything.
+  - It **does not** auto-upgrade dependencies in CI or locally.
+- All dependency changes are made explicitly (e.g., via `npm install`, `npm update`, or manual edits), and then reviewed through normal PR and release processes.
+- `--check` can cause CI to fail if health thresholds are not met, but it still does **not** apply any changes; it only reports and signals status.
+
+### 2. Production security audit
+
+For production (runtime) dependencies, we use npm’s built-in audit with modern flags:
+
+```bash
+npm audit --omit=dev --audit-level=high
+```
+
+This command is part of `npm run ci-verify:full` and is executed automatically in CI and the Husky pre-push hook. It must pass (no high-severity issues in the **production** dependency tree) for a release to proceed.
+
+The JSON output from broader audits (see below) is used as evidence in:
+
+- Security incident reports.
+- Known-error records.
+- Architecture/decision records related to dependency risk.
+
+### 3. Dev-dependency audit and safety checks
+
+Dev-only vulnerabilities are tracked separately and **do not** block CI by themselves, but they must be documented and reviewed:
+
+- `npm run audit:dev-high` – runs a dev-only audit using `npm audit --include=dev --audit-level=high --json`, normalizes the result to always exit with code `0` (never failing CI directly), and writes the JSON output to `ci/npm-audit.json` for targeted inspection of high-severity dev-only vulnerabilities.
+- `npm run audit:ci` – runs `npm audit --json` and writes `ci/npm-audit.json` for CI artifacts.
+- `npm run safety:deps` – runs `dry-aged-deps` with JSON output and writes `ci/dry-aged-deps.json`.
+
+The dev audit focuses **exclusively** on dev dependencies via `npm audit --include=dev --audit-level=high --json`. It is designed **never to fail CI** (the script forces an exit code of `0`), and its JSON output is stored at `ci/npm-audit.json` for inspection alongside the full audit.
+
+These scripts are wired into `ci-verify:full` and the GitHub Actions pipeline and, together with `dry-aged-deps` reports, form the evidence base for:
+
+- Security incident investigations.
+- Known-error documentation when dev-only vulnerabilities are accepted.
+- Validating the claims we make in user-facing docs (e.g., the README).
+
+## How dry-aged-deps Guides Upgrades
+
+`dry-aged-deps` evaluates available versions against configurable **age** and **security** thresholds for both production and development dependencies.
+
+### Current Configuration
+
+In this project, the thresholds are currently equivalent for both groups:
+
+```json
+{
+  "prod": { "minAge": 7, "minSeverity": "none" },
+  "dev": { "minAge": 7, "minSeverity": "none" }
+}
+```
+
+Explicitly:
+
+1. **7-day minimum age**
+   - A candidate version must have been published for **at least 7 days** (`minAge: 7`).
+   - This applies to **both**:
+     - Production dependencies (`prod`)
+     - Development dependencies (`dev`)
+
+2. **"none" minimum severity**
+   - `minSeverity: "none"` means **any known vulnerability** (even low-severity) disqualifies a version as a "safe" update.
+   - For a version to be considered a safe candidate upgrade by `dry-aged-deps`, it must:
+     - Be at least 7 days old.
+     - Have **zero** known vulnerabilities of any severity.
+
+When `dry-aged-deps` finds no qualifying candidates under these constraints:
+
+- `summary.totalOutdated` and `summary.safeUpdates` will both be `0`.
+- `packages` will be an empty array.
+
+This state is a **signal** that:
+
+- Either we are already on the latest qualifying versions under the configured thresholds, or
+- All newer versions are either too recent (younger than 7 days) or have at least one known vulnerability.
+
+### Advisory Role in Upgrade Decisions
+
+Because `dry-aged-deps` is advisory and non-mutating:
+
+- It **highlights** which dependency updates are both:
+  - Maturity-qualified (age ≥ 7 days).
+  - Vulnerability-free (`minSeverity: "none"`).
+- It **does not**:
+  - Change dependency files.
+  - Automatically apply any upgrades in CI.
+
+Maintainership responsibilities:
+
+- Use the JSON report (especially `ci/dry-aged-deps.json` from CI) during dependency review to:
+  - Identify safe upgrade paths for both prod and dev dependencies.
+  - Understand when no safe upgrade path currently exists under the configured criteria.
+- Make explicit, manual changes to dependencies, then re-run:
+  - `npm run deps:maturity -- --format=json --check`
+  - `npm audit --omit=dev --audit-level=high`
+  - Relevant audit scripts
+    to validate the updated state before merging and releasing.
+
+## How dry-aged-deps, npm audit, and Incident Records Interact
+
+`dry-aged-deps` reports and npm audit outputs are used together to:
+
+1. Determine **release readiness** for production dependencies.
+2. Document and justify any **accepted risks**, especially for dev-only tooling.
+3. Provide **evidence backing** for the security-related statements in the README and other user-facing docs.
+
+### Evidence for Production-Side Guarantees
+
+Our user-facing docs (e.g., the README) state that published versions of this project do not contain any _known_ high-severity vulnerabilities in their **production dependency tree** at release time.
+
+Internally, this claim is backed by:
+
+- Successful execution of:
+  - `npm audit --omit=dev --audit-level=high`
+- Verification that:
+  - The audit reports **0 high-severity** production vulnerabilities.
+- Corroborating context from:
+  - `dry-aged-deps` reports (for availability of mature, vulnerability-free upgrades).
+
+If these conditions are not met, a release is not allowed to proceed under normal circumstances, and a security incident or exception process is invoked.
+
+### Handling Dev-Only Vulnerabilities and Semantic-Release/npm
+
+Some high-severity vulnerabilities exist in **dev-only tooling**, specifically in the semantic-release/npm toolchain, which is used only in CI/release workflows, not at runtime in production environments.
+
+Current handling:
+
+- `npm audit --include=dev --audit-level=high --json` (via `npm run audit:dev-high` and `npm run audit:ci`) identifies these vulnerabilities and writes **dev-focused** and **full** audit results to `ci/npm-audit.json`.
+- `dry-aged-deps` is run with the same strict thresholds for dev dependencies:
+  - `minAge: 7`
+  - `minSeverity: "none"`
+
+Under these thresholds, `dry-aged-deps` currently reports:
+
+- No safe upgrade path (no candidate versions that are both ≥ 7 days old and vulnerability-free) for certain semantic-release/npm–related packages.
+
+As a result:
+
+- We **intentionally continue** to use the existing semantic-release/npm toolchain.
+- We record and manage this as an **accepted dev-only risk**, not a production risk.
+
+This acceptance is formalized and supported by:
+
+- A **known error** record:
+  - `docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md`
+- An **architecture/decision record** (ADR):
+  - `docs/decisions/adr-accept-dev-dep-risk-glob.md`
+- CI artifacts:
+  - `ci/npm-audit.json`
+  - `ci/dry-aged-deps.json`
+
+These documents and artifacts show:
+
+- What the vulnerabilities are.
+- Where they live (dev-only, CI-only tooling).
+- Why they are accepted (no safe, mature, vulnerability-free alternatives under our thresholds).
+- What compensating controls are in place.
+
+### Compensating Controls for Accepted Dev-Only Risk
+
+Because `dry-aged-deps` currently identifies **no safe upgrade path** (under the 7-day / `"none"` thresholds) that would resolve these bundled dev-only vulnerabilities, we:
+
+- Keep the existing semantic-release/npm toolchain in place.
+- Enforce the following compensating controls:
+  - CI isolation and hardened environments for release automation.
+  - Strict audits for **production** dependencies (must pass `npm audit --omit=dev --audit-level=high`).
+  - Explicit documentation via:
+    - Known-error and incident records.
+    - ADRs describing the rationale and review process.
+- Periodically re-run and re-review:
+  - `npm run deps:maturity -- --format=json --check`
+  - `npm run audit:dev-high`
+  - `npm run audit:ci`
+    to see whether a new, safe, mature upgrade path has appeared.
+
+These processes ensure that:
+
+- End users see a concise, plain-language statement of security posture in the README and related docs.
+- That statement is grounded in:
+  - Concrete `dry-aged-deps` configuration (7-day / `"none"` thresholds for prod and dev).
+  - Regular, automated `npm audit` runs.
+  - Documented incident handling and risk acceptance when no compliant upgrade path exists.
+
+## Current Status (2025-12-03, verified)
+
+As of the latest review:
+
+- `npm run deps:maturity -- --format=json --check` reports:
+  - `totalOutdated: 0`
+  - `safeUpdates: 0`
+  - `packages: []`
+- `npm audit --omit=dev --audit-level=high` reports **0 high-severity** vulnerabilities for production dependencies.
+- Remaining high-severity issues are limited to **dev-only tooling** (the semantic-release/npm toolchain) and are documented as a **known error**:
+  - `docs/security-incidents/SECURITY-INCIDENT-2025-11-18-semantic-release-bundled-npm.known-error.md`
+  - `docs/decisions/adr-accept-dev-dep-risk-glob.md`
+
+This combination of:
+
+- Advisory `dry-aged-deps` checks (with 7-day / `"none"` thresholds for prod and dev),
+- Mandatory production-only `npm audit` gating,
+- Non-blocking but fully recorded dev-only audits, and
+- Documented risk acceptance for the semantic-release/npm toolchain
+
+is what underpins the security-related guarantees we present to users in the README and other user-facing documentation.