@gobing-ai/spur 0.3.3 → 0.3.5

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gobing-ai/spur",
-    "version": "0.3.3",
+    "version": "0.3.5",
     "description": "Spur CLI — local-first harness for mainstream coding agents: constraint checking, workflow orchestration, agent health, and history analytics. Bun-native; exposes the `spur` command.",
     "keywords": [
         "spur",
@@ -49,13 +49,13 @@
     },
     "devDependencies": {
         "@commander-js/extra-typings": "^14.0.0",
-        "@gobing-ai/ts-ai-runner": "^0.4.3",
-        "@gobing-ai/ts-dual-workflow-engine": "^0.4.3",
-        "@gobing-ai/ts-infra": "^0.4.3",
-        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.3",
-        "@gobing-ai/ts-rule-engine": "^0.4.3",
-        "@gobing-ai/ts-runtime": "^0.4.3",
-        "@gobing-ai/ts-utils": "^0.4.3",
+        "@gobing-ai/ts-ai-runner": "^0.4.4",
+        "@gobing-ai/ts-dual-workflow-engine": "^0.4.4",
+        "@gobing-ai/ts-infra": "^0.4.4",
+        "@gobing-ai/ts-llm-jsonl-importer": "^0.4.4",
+        "@gobing-ai/ts-rule-engine": "^0.4.4",
+        "@gobing-ai/ts-runtime": "^0.4.4",
+        "@gobing-ai/ts-utils": "^0.4.4",
         "@types/bun": "1.3.14",
         "@types/figlet": "^1.7.0",
         "@types/node-notifier": "8.0.5",

package/spur-cli/config/rules/quality/tsdoc-exports.yaml

@@ -23,7 +23,7 @@ exclude:
 rules:
   - id: every-export-has-tsdoc
     description: >
-      Exported declarations must have a preceding TSDoc comment.
+      Exported declarations must have a preceding doc comment (JSDoc `/** */` or line `//`).
     severity: error
     enabled: true
     evaluator:

package/spur-cli/config/rules/typescript/guarded-happy-dom-register.yaml

@@ -0,0 +1,64 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Require try/catch guard around GlobalRegistrator.register() in web tests.
+#
+# WHY: GlobalRegistrator.register() sets up happy-dom globals (window, document,
+# etc.). In a full bun test suite, multiple test files call it. The first call
+# succeeds; subsequent calls throw "Happy DOM has already been globally
+# registered" and the error kills the test file (4 test files × ~13 tests each
+# = 52 tests lost). This only surfaces when ALL tests run together (CI, or
+# `bun test ./apps/web/`), not when a single file runs in isolation.
+# Real incident: 52 CI-only failures across 4 test files, 2026-07-09.
+#
+# FIX: wrap in try/catch:
+#
+#   try { GlobalRegistrator.register(); } catch {} // already registered in suite
+#
+# The teardown helper (apps/web/tests/happy-dom.ts) is the sanctioned unregister
+# caller (see happy-dom-teardown.yaml). This rule guards the register side.
+#
+# Severity warning: the file may pass in isolation but will fail in the full
+# suite; fix before merge.
+include:
+  - "apps/web/tests/**/*.test.ts"
+  - "apps/web/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  # Helper that manages happy-dom lifecycle — not a raw register call.
+  - "apps/web/tests/happy-dom.ts"
+  # These files already wrap register() in try/catch; they are compliant.
+  - "apps/web/tests/modules/task-kanban/board.test.tsx"
+  - "apps/web/tests/modules/task-kanban/components.test.tsx"
+  - "apps/web/tests/modules/task-kanban/task-detail.test.tsx"
+  - "apps/web/tests/modules/task-kanban/index.test.tsx"
+  - "apps/web/tests/modules/task-kanban/new-task-panel.test.tsx"
+  - "apps/web/tests/modules/task-kanban/markdown-body.test.tsx"
+  - "apps/web/tests/modules/task-kanban/useTaskParams.test.tsx"
+  - "apps/web/tests/modules/task-kanban/task-filters.test.tsx"
+  - "apps/web/tests/modules/task-kanban/useTasks.test.ts"
+  - "apps/web/tests/modules/features/components.test.tsx"
+  - "apps/web/tests/lib/theme.test.ts"
+  - "apps/web/tests/components/BoardLayout.test.tsx"
+  - "apps/web/tests/modules/observability/components.test.tsx"
+  - "apps/web/tests/components/ThemeToggle.test.tsx"
+  - "apps/web/tests/components/ResponsiveAndTheme.test.tsx"
+
+rules:
+  - id: guarded-happy-dom-register
+    description: >
+      GlobalRegistrator.register() must be wrapped in try/catch — without
+      it, the second test file that calls it throws "already been globally
+      registered" and all tests in that file are lost (a CI-only failure
+      that never reproduces when a single file runs in isolation). Wrap:
+      `try { GlobalRegistrator.register(); } catch {}`. 52-real CI incidents,
+      2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match bare GlobalRegistrator.register() — NOT inside try/catch
+        # Negative lookbehind: line does NOT start with "try" before the call
+        pattern: "GlobalRegistrator\\.register\\(\\)"
+        # Only flag lines where the call is NOT preceded by try{ on the same line
+        # (the fixed version is `try { GlobalRegistrator.register(); } catch {}`)
+        # We match the call itself and let the description guide the fix

package/spur-cli/config/rules/typescript/no-leaky-module-mocks.yaml

@@ -35,21 +35,20 @@ include:
 exclude:
   - "**/node_modules/**"
   - "**/dist/**"
-  # These tests mock the FIRST-PARTY oRPC `api` client (`../../../src/lib/rpc-client`).
-  # That client is a callable Proxy, so spyOn cannot intercept it (the call regenerates
-  # and hits the network) — `mock.module()` is the only working mechanism. They are safe
-  # because they sort AFTER both rpc-client unit-test files (`lib/rpc-client.test.ts`,
-  # `rpc-client.test.ts`), so the override never leaks back into a real-import reader.
-  # Keep this list minimal: only files that mock a first-party module and have no
-  # spyOn-able alternative belong here. (markdown-body mocks only third-party modules —
-  # mermaid/dompurify — which the narrowed pattern no longer flags, so it is not listed.)
+  # Shared full-surface mock helpers are the CORRECT pattern — they ensure every
+  # test file registers the same compatible surface, neutralizing "last mock wins."
+  - "apps/web/tests/test-helpers/rpc-client-mock.ts"
+  # These files use beforeEach restoreMock() atop the shared baseline — the mock.module
+  # call is in a runtime function, not at module scope, and always registers the full surface.
   - "apps/web/tests/modules/task-kanban/board.test.tsx"
   - "apps/web/tests/modules/task-kanban/components.test.tsx"
   - "apps/web/tests/modules/task-kanban/new-task-panel.test.tsx"
   - "apps/web/tests/modules/features/components.test.tsx"
   - "apps/web/tests/modules/task-kanban/task-detail.test.tsx"
   - "apps/web/tests/modules/task-kanban/index.test.tsx"
-
+  # index.test.tsx no longer mocks useTasks/useTaskParams/TaskDetail; useTasks.test.ts
+  # uses custom listFn (isolated store), not mock.module for first-party modules.
+  - "apps/web/tests/modules/task-kanban/useTasks.test.ts"
 rules:
   - id: no-leaky-mock-module
     description: >

package/spur-cli/config/rules/typescript/no-module-scope-import-calls.yaml

@@ -0,0 +1,61 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Forbid calling imported functions at module-evaluation scope in source files.
+#
+# WHY: calling an imported function at module scope (outside any function/class
+# body) creates an evaluation-time side effect that captures the depencency
+# before any test mock can intercept it. If the first test file that evaluates
+# this module has a mock active, the module caches with that mock's state; in
+# CI (where test-file order differs from local), a different test may evaluate
+# it first with NO mock or a different mock, causing CI-only failures that pass
+# locally every time. Real incidents:
+#
+#   2026-07-09: useTasks.ts:6   — const SSE_URL = `${resolveApiUrl()}/...`  (73 failures)
+#   2026-07-09: SystemEventsTab.tsx:42-43 — const HISTORY_URL = `${resolveApiUrl()}/...`;
+#              const SSE_URL = `${resolveApiUrl()}/...`  (1 failure)
+#
+# The pattern is always the same: a top-level `const` or `let` whose initializer
+# calls a function imported from another module. Defer the call to a function:
+#
+#   // BEFORE (broken):
+#   const SSE_URL = `${resolveApiUrl()}/events/planning`;
+#
+#   // AFTER (fixed):
+#   const sseUrl = () => `${resolveApiUrl()}/events/planning`;
+#
+# FIX: wrap the initializer in an arrow function and call it lazily at the
+# point of use. If the value is used as a default parameter or a constant
+# reference, convert it to a getter function or compute it in the
+# constructor/init method.
+#
+# Severity: warning. A hit may pass locally but WILL fail in CI if a mock is
+# involved; justify with a comment or convert to lazy.
+include:
+  - "apps/**/src/**/*.ts"
+  - "apps/**/src/**/*.tsx"
+  - "packages/**/src/**/*.ts"
+  - "packages/**/src/**/*.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  - "**/tests/**"
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+
+rules:
+  - id: no-module-scope-import-calls
+    description: >
+      Calling an imported function at module scope (outside any function or
+      class body) creates an evaluation-time side effect that captures the
+      dependency before any test mock can intercept it — a CI-only,
+      ordering-dependent failure. Defer the call: wrap the value in an arrow
+      function and call it lazily at the point of use. Real incidents:
+      useTasks.ts:6 (73 CI failures), SystemEventsTab.tsx:42 (1 CI failure),
+      2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match top-level const/let whose initializer is a template literal
+        # calling an import (e.g. resolveApiUrl(), api.*, ...).
+        # The pattern: line starts with `const`/`let`, contains `${...()}`.
+        pattern: "^(const|let)\\s+\\w+\\s*=\\s*`[^`]*\\$\\{[^}]*\\([^)]*\\)[^}]*\\}[^`]*`"

package/spur-cli/config/rules/typescript/no-unmocked-module-eval-side-effects.yaml

@@ -0,0 +1,60 @@
+$schema: "@gobing-ai/spur/schemas/rule-file.schema.json"
+# Require test files to mock dependencies of modules with module-eval side effects.
+#
+# WHY (the general pattern): some source modules run code at module-evaluation
+# time — creating singletons, computing constants from imports, calling functions
+# from other modules at module scope (not inside a function/class body). When a
+# test file imports such a module, it triggers the side effect. If the dependency
+# modules are not mocked, the side effect captures the real API and that state
+# persists across the entire test suite — a CI-only, file-ordering-dependent
+# failure that never reproduces locally. The sibling rule `no-leaky-module-mocks`
+# handles the mirror problem (mock.module leaking into real-import readers).
+#
+# KNOWN MODULES WITH MODULE-EVAL SIDE EFFECTS:
+#
+#   (None currently active — the useTasks.ts singleton side effect was fixed by
+#    commit 3937d31 which converted resolveApiUrl() and api.task.list() calls to
+#    lazy dynamic imports. The singleton _sharedStore = new TaskStore() no longer
+#    triggers an API call at module-eval time. When a new side-effect module is
+#    discovered, add it here with the pattern shown below.)
+#
+#   RESOLVED — src/modules/task-kanban/useTasks.ts (fixed 2026-07-08)
+#     - Line 6: was const SSE_URL = `${resolveApiUrl()}/events/planning`;
+#       → now: const sseUrl = async () => { const { resolveApiUrl } = await import(...); return ...; };
+#     - Line 159: was const sharedStore = new TaskStore(); (calls defaultListTasks
+#       which statically imported api.task.list) → now: defaultListTasks uses
+#       dynamic await import('../../lib/rpc-client'), so construction is lazy.
+#     - 73 CI failures, 2026-07-08. Fix: commit 3937d31.
+#
+# To ADD a new module to this list when another CI-only failure is traced to a
+# module-eval side effect: append its import pattern to `rules[].evaluator.config.pattern`
+# (alternation) and add the corresponding entry above.
+include:
+  - "apps/**/tests/**/*.test.ts"
+  - "apps/**/tests/**/*.test.tsx"
+  - "packages/**/tests/**/*.test.ts"
+  - "packages/**/tests/**/*.test.tsx"
+exclude:
+  - "**/node_modules/**"
+  - "**/dist/**"
+  # All known side-effect modules are resolved. When a new one is discovered,
+  # exclude files that already mock the dependency before importing it.
+
+rules:
+  - id: no-unmocked-module-eval-side-effects
+    description: >
+      Test files that import a module with module-evaluation side effects
+      (singletons created at module scope, imports called at eval time, etc.)
+      MUST mock the dependency modules BEFORE the import. Without the mock,
+      the side effect captures the real API and leaks into every subsequent
+      test file — a CI-only, ordering-dependent failure. Add mock.module()
+      for the listed dependency before any import of the side-effect module.
+      See the file header for the list of known side-effect modules and their
+      dependencies. 73-real CI incidents (useTasks → rpc-client), 2026-07-09.
+    severity: warning
+    evaluator:
+      type: rg
+      config:
+        # Match imports from modules with known module-eval side effects.
+        # Add new patterns here as alternations (|) when new cases are discovered.
+        pattern: "from ['\"].*task-kanban/useTasks['\"]"

package/spur-cli/config/workflows/task-pipeline.yaml

@@ -120,7 +120,7 @@ states:
           command: "bun run lint"
 
   - id: review
-    description: SECUA-framework code review via /sp:dev-review (Security, Efficiency, Correctness, Usability, Architecture).
+    description: Three-dimensional code review via /sp:dev-review (functional requirements traceability + SECUA framework (Security, Efficiency, Correctness, Usability, Architecture) + architecture depth), findings written to `## Review`.
     onEnter:
       - kind: agent.run
         options: