Bring production TypeScript to messcript's idiomatic ruleset

[jonbaldie]

Problem Statement

The Queue Service has no enforced structural-quality gate for its production TypeScript. This makes it possible for the HTTP handler, Queue Manager, Persist Engine, configuration, routing, middleware, rate limiting, or executable entrypoint to accumulate avoidable complexity and non-idiomatic constructs while the existing behavior tests remain green.

The work needs to be incremental because the application has a public HTTP contract, FIFO Queue semantics, Queue Manager lifecycle rules, Persist Engine replay behavior, bearer-token authentication, rate limiting, and graceful shutdown behavior. A package-by-package pass gives each change a small reviewable boundary while keeping the service behavior protected.

Solution

Adopt github.com/quality-gates/messcript as a reproducible quality gate for the application’s production TypeScript. Use messcript’s recommended typescript policy as the idiomatic ruleset, with CyclomaticComplexity and NPathComplexity explicitly retained and enforced at messcript’s configured defaults unless a later decision changes the thresholds.

Process the production surface one module at a time, refactoring findings without changing the Queue Service’s external behavior. The final aggregate run must return no selected findings for the production modules and executable entrypoint, including code-size, naming, unused-code, clean-code, design, and controversial rules selected by the idiomatic policy. Tests, mutation harnesses, documentation, CI configuration, and other development-only code are not part of this production gate.

Make the invocation reproducible for local development and CI by pinning the messcript revision or released artifact used by the repository and building/installing it as needed. Do not depend on an unpinned moving GitHub branch or on an unavailable registry latest package. Add a CI quality check in an environment compatible with messcript’s Node runtime while leaving the Queue Service’s Deno 2.7.6 test and production environments unchanged.

User Stories

1. As a maintainer, I want the application’s production TypeScript checked by messcript, so that structural quality problems are visible before they accumulate.
2. As a contributor, I want a reproducible messcript version, so that local results and CI results agree.
3. As a CI maintainer, I want the messcript quality check to run in a Node-compatible environment, so that the Deno 2.7.6 service jobs do not need to change runtime.
4. As a maintainer, I want only application production code included in the gate, so that tests and mutation infrastructure do not create unrelated findings.
5. As a maintainer, I want the production surface analyzed module by module, so that each refactor has a clear scope and review boundary.
6. As a maintainer, I want configuration parsing to remain behaviorally identical while satisfying the quality gate, so that environment variables, defaults, flags, and validation errors remain stable.
7. As a Queue Service operator, I want Queue Manager refactors to preserve FIFO ordering, queue isolation, queue limits, empty-queue cleanup, and persistence interactions, so that operational queue behavior does not change.
8. As a Queue Service operator, I want Persist Engine refactors to preserve append-only event recording, replay order, truncation, directory handling, and missing-file behavior, so that persisted Queue state remains recoverable.
9. As an API client, I want HTTP handler refactors to preserve every documented endpoint, method restriction, response status, response body, content type, payload validation rule, and queue-name validation rule, so that clients do not need to change.
10. As a security-conscious operator, I want authentication and rate-limiting middleware refactors to preserve bearer-token enforcement, health-check exemptions, forwarded-client handling, and rate-limit responses, so that access controls remain intact.
11. As an API client, I want router refactors to preserve route matching, method-not-allowed responses, unknown-route responses, and route parameter extraction, so that request dispatch remains stable.
12. As a Queue Service operator, I want rate limiter refactors to preserve per-client windows, forwarded-address precedence, stale-entry cleanup, capacity eviction, and boundary behavior, so that abuse protection remains stable.
13. As an operator, I want executable startup and shutdown refactors to preserve host and port binding, startup observability, signal handling, persistence flushing, and clean process exit, so that deployments remain operationally safe.
14. As a maintainer, I want cyclomatic complexity findings to be active for every production module, so that branching complexity cannot be hidden by a reduced rule selection.
15. As a maintainer, I want NPath complexity findings to be active for every production module, so that combinations of independent branches cannot grow unchecked even when cyclomatic complexity is below its threshold.
16. As a maintainer, I want the final messcript command to fail through its normal non-zero exit code when findings or processing errors exist, so that CI cannot report a false green result.
17. As a maintainer, I want no broad suppressions, ignored violations, or disabled rules used as a substitute for remediation, so that a passing report reflects production code quality rather than hidden findings.
18. As a reviewer, I want the HTTP handler to remain the highest behavioral test seam for application refactors, so that implementation decomposition does not create a large number of brittle internal tests.
19. As a reviewer, I want real end-to-end startup and shutdown checks after entrypoint refactors, so that process-level behavior is verified rather than inferred from unit tests.
20. As a maintainer, I want the existing Deno test suite and mutation gates to remain green after each package pass, so that messcript remediation cannot trade structural cleanliness for behavior regressions.
21. As a contributor, I want clean production modules recorded as completed in the package-by-package worklist, so that the remaining work is explicit and no module is accidentally omitted.
22. As a release owner, I want the aggregate production quality check to cover the complete application surface on every applicable CI run, so that a clean individual-module pass cannot conceal a failing entrypoint or newly added production module.

Implementation Decisions

• Treat the Queue Service’s production surface as these package-sized units: configuration, router, middleware, rate limiter, Queue Manager, Persist Engine, HTTP handler, and executable entrypoint.
• Use messcript’s recommended typescript policy as the idiomatic policy. This policy’s normal selected rules include CyclomaticComplexity and NPathComplexity; neither may be removed through --only, --disable, priority filtering, or a custom exclusion.
• Use messcript’s default thresholds for this first adoption: cyclomatic complexity reports above 10 and NPath complexity reports at or above 200. Threshold changes are a separate policy decision and are not part of this work.
• Pin the messcript source revision or released artifact used by local and CI commands. Because the tool is sourced from GitHub and may require a build before execution, the installation/build path must be explicit and reproducible.
• Add one documented local command for a single production unit and one aggregate command for the complete production surface. The aggregate command must include the executable entrypoint as well as the application modules.
• Add a CI quality check using a compatible Node runtime, while preserving the existing Deno 2.7.6 image and permissions for the Queue Service’s compile, test, and mutation jobs.
• Keep the current public construction seam for the HTTP handler. Refactor its route registration, request parsing, response formatting, and operational logging behind internal helpers only where needed to remove excessive method length and complexity.
• Preserve the HTTP handler’s externally observable contract: health, queue listing, enqueue, dequeue, peek, and length operations; bearer authentication; rate limiting; body-size handling; JSON validation; queue limits; status codes; response bodies; and content types.
• Preserve the Queue Manager’s public operations and Queue lifecycle semantics. Any decomposition must keep Queue registration, count/depth limits, FIFO behavior, cleanup of empty Queues, and Persist Engine event ordering unchanged.
• Preserve both Persist Engine implementations and their shared contract. Refactors must not change append-only writes, replay behavior, locking, truncation, directory normalization, or the special behavior that clearing creates the persistence file when absent.
• Preserve middleware composition and the health endpoint’s exemptions from authentication and rate limiting.
• Preserve router method dispatch and URLPattern-based routing; do not introduce a compatibility layer for Deno 1.x APIs.
• Preserve rate-limiter behavior at window boundaries and during stale-entry cleanup and IP eviction. Avoid introducing time-dependent abstractions solely to satisfy messcript.
• Preserve executable startup and graceful shutdown behavior, including the startup line consumed by the end-to-end test and the final persistence flush on SIGINT and SIGTERM. Replace debug-style logging constructs with operational logging that remains observable and is not hidden by messcript.
• Remediate findings rather than adding source suppressions or weakening the selected policy. A suppression is not an accepted completion criterion for this work.
• Work in this order unless a finding or dependency makes a different order safer: verify clean configuration, router, Queue Manager, and rate limiter units; remediate middleware; remediate the Persist Engine; decompose and remediate the HTTP handler; then remediate the executable entrypoint; finally run the aggregate gate.
• Do not alter the application’s domain model, HTTP API, persistence schema/event shape, Deno version, or existing mutation-testing strategy as part of this quality pass.

Testing Decisions

• Use the highest existing behavioral seam: real Request objects passed through the public HTTP handler and assertions on real Response status, body, headers, and Queue effects. Do not test private helper structure merely because the handler is decomposed.
• Retain and run the existing focused tests for configuration, Queue Manager behavior, Persist Engine behavior, HTTP behavior, rate limiting, and the end-to-end server lifecycle. These tests are the prior art for behavior preservation in this repository.
• Use real persistence directories and real file I/O for Persist Engine and Queue Manager persistence scenarios. Do not mock the Persist Engine or filesystem calls.
• Use real HTTP requests against a real child server process for startup, port binding, signal shutdown, and persistence flushing. Do not mock Deno.serve, signals, or process status.
• Run a tracer-bullet smoke test after the handler and entrypoint passes: start the actual server, verify health without authentication, enqueue a payload with authentication, dequeue it in FIFO order, and terminate the process while checking the expected clean exit and persistence behavior where enabled.
• Run the messcript check once per production unit during implementation and once over the complete production surface at completion. Each unit must have zero selected findings before it is marked complete.
• Verify that the selected report contains both CyclomaticComplexity and NPathComplexity rule identities, even if a clean run has no findings for one of them.
• Treat messcript processing errors as failures. Do not use --ignore-errors-on-exit, --ignore-violations-on-exit, broad path exclusions, or a report-only command that does not enforce the exit status.
• Run the complete Deno test suite, the real server smoke test, and the existing mutation checks after the aggregate messcript run. Automated assertions are necessary but not sufficient; inspect the real process behavior and quality-gate exit status as well.
• If a refactor reveals a genuine missing behavioral test, add it at the highest external seam that demonstrates the behavior. Do not add mocks or tests coupled to private implementation details.

Out of Scope

• Enabling messcript’s separate opinionated ruleset in addition to the recommended typescript policy.
• Changing messcript thresholds, inventing repository-specific exceptions, or suppressing findings to obtain a green report.
• Applying the production gate to tests, mutation runners, CI scripts, documentation, generated output, or development tooling.
• Changing Queue Service HTTP endpoints, payload semantics, authentication policy, rate-limit policy, persistence event format, configuration names/defaults, or shutdown semantics.
• Replacing Deno, upgrading or downgrading the required Deno 2.7.6 runtime, or changing Deno 2.x APIs.
• Replacing the existing mutation engines or changing their operators, thresholds, target semantics, or test commands.
• Migrating CircleCI to another CI provider; the quality check should fit the current workflow and remain independently portable.
• Introducing a general logging framework, observability platform, or unrelated architecture redesign.
• Reformatting or renaming tests except where a behavior-preserving change is required by a production interface adjustment.

Further Notes

A baseline run of the current GitHub version of messcript found no selected findings in configuration, Queue Manager, rate limiter, or router. Findings were present in the HTTP handler for excessive method length, cyclomatic complexity, unused-parameter naming, and debug-style logging; in middleware for constant naming; in the Persist Engine for assignment in a loop condition and underscore-prefixed names; and in the executable entrypoint for constant naming and debug-style logging. The baseline is informational; the implementation must rerun the pinned tool version and treat its complete report as authoritative.

NPath complexity did not currently produce a finding, but it remains an enforced rule and must be present in the selected policy. A clean result means both that no current NPath finding exists and that future code cannot evade the rule.

The repository currently has no committed application package manifest for this tool. The implementation should add only the minimal reproducible development metadata needed to acquire/build/run messcript and should avoid coupling Queue Service runtime startup to Node tooling.

The .serena project configuration has unrelated local changes at the time this spec was written and must be preserved.

[jonbaldie]

Completed the production quality worklist and CI migration.\n\nEvidence:\n- CI migrated from CircleCI to GitHub Actions; exact CircleCI webhook removed; Serena project tooling/schema changes shipped.\n- Messcript pinned and documented in PR #38; unit gates cleared through PRs #40–#43, with already-clean #29–#32 closed serially.\n- PR #44 added the Node 22 Production quality job. The aggregate reports all 8 production units plus CyclomaticComplexity and NPathComplexity, and exits non-zero on findings/errors.\n- Final local validation: aggregate zero findings; Deno 180/180; Mutasaurus 98% overall with every file at least 80%; Stryker 94.72% overall with every file at least 80%; real startup/health/enqueue/FIFO/persistence/SIGTERM smoke passed.\n- Final GitHub Actions main run 30017577877 passed Test, Production quality, Mutasaurus, and Stryker.\n\nImplemented and merged: #38, #39, #40, #41, #42, #43, #44.

[jonbaldie]

All production quality and CI acceptance criteria are complete; final main CI verification passed in run 30017577877.