feat(engine): injectable AST timeout, BOM coverage, .cts support

[rhuanbarreto]

Summary

• feat: make AST subprocess timeout injectable for test coverage #453 — Make runAstSubprocess() timeout injectable via optional timeoutMs parameter (defaults to AST_SUBPROCESS_TIMEOUT_MS) so tests can exercise the timeout→kill→throw path deterministically
• test: add BOM fixture coverage for Python/Ruby AST serializers #454 — Add BOM fixture tests for Python (utf-8-sig) and Ruby (r:bom|utf-8) serializers to guard against encoding regressions
• feat: add .cts extension support to ctx.ast() TypeScript language #455 — Parse .cts files with sourceType: "script" in the TypeScript AST branch, mirroring the existing .cjs handling for JavaScript

Test plan

• Timeout test: spawns a long-sleeping subprocess with a 50ms injected timeout, asserts it throws with the expected message
• Python BOM test: writes a UTF-8 BOM-prefixed .py fixture, verifies the serializer parses it successfully
• Ruby BOM test: writes a UTF-8 BOM-prefixed .rb fixture, verifies the serializer parses it successfully
• .cts test: verifies .cts produces sourceType: "script" while .mts produces sourceType: "module"
• bun run validate passes (lint, typecheck, format, 1390 tests, 43/43 ADR checks, knip, build)

Closes #453, closes #454, closes #455

https://claude.ai/code/session_01H7XPPVhN1t6HzH8F3xN4DP

[cursor]

Bugbot couldn't run - usage limit reached

Bugbot is counted against Cursor usage for this user or team, and this run hit a usage or spend limit.

A user or team admin can review and increase usage limits in the Cursor dashboard.

(requestId: serverGenReqId_0bafb8f6-d712-4233-9cde-61bd48270a59)

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 398c2dac-a1e2-42c6-a567-75a3080aa32a

📥 Commits

Reviewing files that changed from the base of the PR and between 81f68c8 and 7fee870.

📒 Files selected for processing (4)

• src/engine/ast-support.ts
• src/engine/runner.ts
• tests/engine/ast-support.test.ts
• tests/engine/runner-ast.test.ts

📜 Recent review details

⏰ Context from checks skipped due to timeout. (1)

• GitHub Check: Smoke Test (Windows) / Windows

⚠️ CI failures not shown inline (4)

GitHub Actions: DCO / 0_DCO Sign-off Check.txt: feat(engine): injectable AST timeout, BOM coverage, .cts support

Conclusion: failure

View job details

##[group]Run base="81f68c85a5cdc3890460ca6e3e82db05cf32a3d1"
 �[36;1mbase="81f68c85a5cdc3890460ca6e3e82db05cf32a3d1"�[0m
 �[36;1mhead="7fee870886fc20d1de1378def6b3370dc4750526"�[0m
 �[36;1mfailed=0�[0m
 �[36;1m�[0m
 �[36;1mfor sha in $(git rev-list --no-merges "$base".."$head"); do�[0m
 �[36;1m  if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then�[0m
 �[36;1m    echo "::error::Commit $sha is missing a DCO Signed-off-by line."�[0m

---

GitHub Actions: DCO / DCO Sign-off Check: feat(engine): injectable AST timeout, BOM coverage, .cts support

Conclusion: failure

View job details

##[group]Run base="81f68c85a5cdc3890460ca6e3e82db05cf32a3d1"
 �[36;1mbase="81f68c85a5cdc3890460ca6e3e82db05cf32a3d1"�[0m
 �[36;1mhead="7fee870886fc20d1de1378def6b3370dc4750526"�[0m
 �[36;1mfailed=0�[0m
 �[36;1m�[0m
 �[36;1mfor sha in $(git rev-list --no-merges "$base".."$head"); do�[0m
 �[36;1m  if ! git log -1 --format='%B' "$sha" | grep -qiE '^Signed-off-by: .+ <.+>'; then�[0m
 �[36;1m    echo "::error::Commit $sha is missing a DCO Signed-off-by line."�[0m

---

GitHub Actions: Code Quality: PR #457 / Analyze (go): Code Quality: PR #457

Conclusion: failure

View job details

bundleSupportsIncludeLogs":true,"bundleSupportsOverlay":true,"databaseInterpretResultsSupportsSarifRunProperty":true,"featuresInVersionResult":true,"indirectTracingSupportsStaticBinaries":false,"informsAboutUnsupportedPathFilters":true,"supportsPython312":true,"mrvaPackCreate":true,"threatModelOption":true,"traceCommandUseBuildMode":true,"v2ramSizing":true,"mrvaPackCreateMultipleQueries":true,"setsCodeqlRunnerEnvVar":true,"sarifMergeRunsFromEqualCategory":true,"forceOverwrite":true,"generateSummarySymbolMap":true,"pythonDefaultIsToNotExtractStdlib":true,"queryServerRunQueries":true,"queryServerTrimCacheWithMode":true,"builtinExtractorsSpecifyDefaultQueries":true,"bqrsDiffResultSets":true,"bundleSupportsIncludeOption":true,"suppressesMissingFileBaselineWarning":true}}}
   CODEQL_ACTION_GO_BINARY: /home/runner/work/_temp/codeql-action-go-tracing/bin/go
   CODEQL_RAM: 14575
   CODEQL_THREADS: 4
   CODEQL_PROXY_HOST:
   CODEQL_PROXY_PORT:
   CODEQL_PROXY_CA_CERTIFICATE:
   CODEQL_PROXY_URLS:
 ##[endgroup]
 ##[group]Attempting to automatically build go code
 [command]/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/codeql database trace-command --use-build-mode --working-dir /home/runner/work/cli/cli /home/runner/work/_temp/codeql_databases/go
 Picked up JAVA_TOOL_OPTIONS:  -Dhttp.keepAlive=false -Dmaven.wagon.http.pool=false
 Running command in /home/runner/work/cli/cli: [/opt/hostedtoolcache/CodeQL/2.25.6/x64/codeql/go/tools/autobuild.sh]
 [] [build-stderr] 2026/07/06 17:13:24 Autobuilder was built with go1.26.0, environment has go1.24.13
 [] [build-stderr] 2026/07/06 17:13:24 LGTM_SRC is /home/runner/work/cli/cli
 [] [build-stderr] 2026/07/06 17:13:24 Found no go.work files in the workspace; looking for go.mod files...
 [] [build-stderr] 2026/07/06 17:13:24 Found 1 go.mod files in: shims/go/go.mod.
 [] [build-stderr] 2026/07/06 17:13:24 Found 1 go.mod file(s).
 [] [build-stderr] 2026/07/06 17:13:24 Import path is 'github.com/archgate/cli'
 [] [build-stderr] 2026/07/06...

---

GitHub Actions: Code Quality: PR #457 / 5_Analyze (go).txt: Code Quality: PR #457

Conclusion: failure

View job details

xtracting types for package crypto/aes.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/aes.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/des.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/des.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/des.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/internal/fips140/nistec/fiat.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/internal/fips140/nistec/fiat.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/internal/fips140/nistec/fiat.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/internal/fips140/nistec.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/internal/fips140/nistec.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/internal/fips140/nistec.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/internal/fips140/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/internal/fips140/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/internal/fips140/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/internal/fips140/edwards25519/field.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/internal/fips140/edwards25519/field.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/internal/fips140/edwards25519/field.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Done extracting types for package crypto/ecdh.
 [] [build-stderr] 2026/07/06 17:13:33 Processing package crypto/elliptic.
 [] [build-stderr] 2026/07/06 17:13:33 Extracting types for package crypto/elliptic.
 [] [build-std...

🧰 Additional context used

📓 Path-based instructions (8)

src/**/*.ts

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)

src/**/*.ts: Use logError() from src/helpers/log.ts for user-facing errors instead of printing errors directly.
Exit with code 1 for expected failures such as missing config, invalid input, or validation violations.
Let unexpected errors crash naturally so they are treated as internal errors with exit code 2.
Include actionable suggestions in user-facing error messages whenever possible.
Write user-facing errors to stderr via logError(); do not send them to stdout.
When findProjectRoot() returns null for commands that do not require .archgate/, fall back to process.cwd() as the path key or working directory.
Catch ExitPromptError from Inquirer in the top-level error boundary and treat it as user cancellation: exit with code 130 without logging an error or sending it to Sentry.
Do not use console.error() directly; use logError() for consistent formatting.
Do not exit with codes other than 0, 1, 2, or 130.
Do not send user-cancellation errors such as Inquirer ExitPromptError to Sentry; filter them in beforeSend.

src/**/*.ts: Use styleText(format, text) from node:util for all terminal colors and formatting in CLI source files; do not use raw ANSI escape codes or third-party color libraries.
Commands that produce structured results and support --json must emit machine-readable JSON to stdout with no colors or decorative formatting.
When a command supports --json, use formatJSON() from src/helpers/output.ts for JSON serialization, and pass forcePretty: true when the user explicitly provided --json.
Use isAgentContext() from src/helpers/output.ts to enable auto-JSON behavior for commands that support both human-readable and JSON output modes.
CLI output must not include emoji; use text symbols and colors instead.
Send normal command output to stdout with console.log(), and send errors, warnings, and debug messages to stderr via logError(), logWarn(), and logDebug().
Keep CLI output concise and scannabl...

Files:

• src/engine/ast-support.ts
• src/engine/runner.ts

src/{helpers,engine}/**/*.ts

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-002-error-handling.md)

Do not use console.log(), console.warn(), or console.info() directly in helper or engine files; use logInfo() or logWarn() instead. Command files are exempt because they are the I/O layer.

Files:

• src/engine/ast-support.ts
• src/engine/runner.ts

**/*.{ts,tsx,js,jsx,mjs,cjs}

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-006-dependency-policy.md)

**/*.{ts,tsx,js,jsx,mjs,cjs}: Use Bun built-ins for file I/O (Bun.file, Bun.write), HTTP, subprocess execution (Bun.spawn), globbing (Bun.Glob), and testing (bun:test).
Do not use Node.js-specific APIs when Bun alternatives exist; for example, use Bun.file() instead of fs.readFile() for simple reads.
Prefer node: built-in modules such as node:util, node:path, and node:fs over npm alternatives.
Do not use utility libraries for single functions, such as importing lodash for one helper like pick.
Do not use path aliases (tsconfig paths); use relative imports with Bun's native module resolution.
Do not install packages globally during development; use bunx for one-off tools.

Files:

• src/engine/ast-support.ts
• tests/engine/ast-support.test.ts
• src/engine/runner.ts
• tests/engine/runner-ast.test.ts

src/**/!(*platform).ts

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)

src/**/!(*platform).ts: In src/ TypeScript source files, do not read process.platform directly; use src/helpers/platform.ts (isWindows(), isMacOS(), isLinux(), isWSL(), getPlatformInfo()) for all platform detection.
Use the centralized platform helper instead of duplicating OS/WSL detection logic inline anywhere in src/ TypeScript source.
When behavior differs between Linux and Windows, account for WSL by using isWSL() rather than assuming `

Files:

• src/engine/ast-support.ts
• src/engine/runner.ts

{src,tests}/**/*.ts

📄 CodeRabbit inference engine (.archgate/adrs/LEGAL-001-spdx-license-headers.md)

{src,tests}/**/*.ts: Every TypeScript source file in src/ and tests/ must begin with // SPDX-License-Identifier: Apache-2.0 followed by // Copyright 2026 Archgate.
If a TypeScript file has a shebang line (for example #!/usr/bin/env bun in src/cli.ts), the SPDX license header must appear immediately after the shebang.
Use single-line // comments for the SPDX header; do not use block comments (/* */) or alternate license identifiers.

Files:

• src/engine/ast-support.ts
• tests/engine/ast-support.test.ts
• src/engine/runner.ts
• tests/engine/runner-ast.test.ts

**

⚙️ CodeRabbit configuration file

**: # CLAUDE.md

Archgate is a CLI tool for AI governance via Architecture Decision Records (ADRs) — combining human-readable docs with machine-checkable rules. The CLI dogfoods itself via ADRs in .archgate/adrs/. AI features are delivered as a Claude Code plugin (../plugins/claude-code), not via direct API calls.

Technology Stack

• Runtime: Bun (>=1.2.21) — not Node.js compatible
• Language: TypeScript (strict mode, ESNext, ES modules)
• CLI framework: Commander.js (@commander-js/extra-typings)
• Linter: Oxlint | Formatter: Oxfmt | Dead exports: Knip | Commits: Conventional Commits

Commands

bun run src/cli.ts <command>  # run CLI locally
bun run lint                  # oxlint
bun run typecheck             # tsc --build
bun run format                # oxfmt --write
bun run format:check          # oxfmt --check
bun run test                  # all tests (not bare `bun test` — picks up --timeout; see GEN-003)
bun run knip                  # dead export detection
bun run validate              # MANDATORY: lint + typecheck + format:check + test + ADR check + knip + build check
bun run build:check            # verify build compiles (CI builds binaries via release workflow)
bun run commit                # conventional commit wizard

Validation Gate

bun run validate must pass before any task is considered complete. Fail-fast pipeline: lint → typecheck → format:check → test → ADR check → knip → build check. Mirrors CI in .github/workflows/code-pull-request.yml.

Git Hooks (Git 2.54+)

Config-based hooks in .githooks run validation locally before commits and pushes:

• pre-commit: lint + typecheck + format:check (~15s)
• pre-push: full bun run validate (~60s, mirrors CI)

Activate once per clone:

git config --local include.path ../.githooks

Opt out of a specific hook: git config --local hook.<name>.enabled false. Skip all hooks for a single commit: git commit --no-verify.

#...

Files:

• src/engine/ast-support.ts
• tests/engine/ast-support.test.ts
• src/engine/runner.ts
• tests/engine/runner-ast.test.ts

---

⚙️ CodeRabbit configuration file

**: This project uses Archgate — an AI governance framework based on
Architecture Decision Records (ADRs). The ADRs in .archgate/adrs/
are the authoritative rules for this codebase. Each ADR has a companion
.rules.ts file with automated checks that run via archgate check.

When reviewing, you must:

1. Treat ADR violations as blocking issues, not suggestions.
2. Cite the specific ADR ID when flagging a violation (e.g., "Violates ARCH-006").
3. Focus on semantic and contextual violations that automated rules cannot catch —
   the .rules.ts files already cover syntactic/structural patterns.
4. If you are unsure whether something violates an ADR, flag it as a question
   rather than approving it.

Files:

• src/engine/ast-support.ts
• tests/engine/ast-support.test.ts
• src/engine/runner.ts
• tests/engine/runner-ast.test.ts

tests/**/*.test.ts

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-005-testing-standards.md)

tests/**/*.test.ts: Use Bun's built-in test runner (bun:test) for all test files, and place tests under tests/ mirroring the src/ directory structure with <module-name>.test.ts naming.
Use temp directories (mkdtemp) for filesystem tests, and clean them up in afterEach or afterAll.
Close external SDK instances (servers, clients, transports, connections) in afterEach or afterAll, managing their lifecycle in hooks rather than inside individual test bodies.
When a test creates a temporary git repository and runs git commit, configure local user.email and user.name immediately after git init.
Test public module interfaces, not private implementation details.
Use descriptive test names that explain the expected behavior.
Every runnable test()/it() must contain at least one expect() assertion; smoke tests must make the contract explicit with expect(() => fn()).not.toThrow() or await expect(promise).resolves.toBeUndefined().
Use test.skip, test.skipIf, or test.todo for intentionally empty or disabled tests; do not use bare return or empty callbacks to skip work.
If the first expect() is being added to a previously assertion-less test file, add expect to the bun:test import.
When mocking fetch in tests, assign directly to globalThis.fetch and restore the original or use mock.restore() afterward.
Wrap spyOn() and inline mockImplementation() usage in try/finally, or create and restore spies in hooks, so mockRestore() always runs.
Only raise a per-test timeout above the global bun test --timeout 60000; never set a shorter per-test timeout.
Mock first-party modules with import * as mod plus spyOn(mod, "fn"), not mock.module().
When a test needs to redirect user-scope paths, mock os.homedir() instead of relying on HOME/Bun.env.HOME; restore the spy in test hooks.
Do not depend on network access in unit tests.
Do not leave temp files after test runs.
Do not leave external SDK instances open after tests...

Files:

• tests/engine/ast-support.test.ts
• tests/engine/runner-ast.test.ts

tests/**/*.ts

📄 CodeRabbit inference engine (.archgate/adrs/ARCH-009-platform-detection-helper.md)

In test files, use _resetPlatformCache() to simulate different platforms instead of mocking or mutating process.platform directly.

Files:

• tests/engine/ast-support.test.ts
• tests/engine/runner-ast.test.ts

🔇 Additional comments (4)

tests/engine/runner-ast.test.ts (1)

359-417: LGTM!

Also applies to: 465-467

src/engine/runner.ts (1)

202-206: 🎯 Functional Correctness

No issue: AST_LANGUAGE_EXTENSIONS.typescript already includes .cts and .mts, so the .cts/.mts branch is reachable as written.

			> Likely an incorrect or invalid review comment.

src/engine/ast-support.ts (1)

158-160: LGTM!

Also applies to: 172-180

tests/engine/ast-support.test.ts (1)

83-91: LGTM!

Also applies to: 180-199, 253-275

---

📝 Walkthrough

Walkthrough

This change makes the AST subprocess timeout configurable via a timeoutMs parameter on runAstSubprocess, used consistently in timer scheduling and error messaging. It adds sourceType detection ("script" for .cts, "module" otherwise) to the TypeScript parsing branch in the rule runner. Test coverage is expanded with a deterministic timeout-rejection test, new UTF-8 BOM fixture tests for Python and Ruby AST serialization, an expanded .cjs/.cts/.mts/.mjs sourceType test, and an updated wrong-extension guardrail test now including Python.

Sequence Diagram(s)

Not applicable; changes are parameter additions, conditional logic, and test coverage rather than new interactive workflows.

Related Issues

• feat: make AST subprocess timeout injectable for test coverage #453: Makes the AST subprocess timeout injectable and adds deterministic test coverage.
• test: add BOM fixture coverage for Python/Ruby AST serializers #454: Adds BOM fixture coverage for Python/Ruby AST serializers.
• feat: add .cts extension support to ctx.ast() TypeScript language #455: Adds .cts extension support with sourceType: "script" in TypeScript AST parsing.

Suggested labels: tests, engine, typescript

Suggested reviewers: none identified from provided context

Poem
A timeout tamed, no more the endless wait,
A BOM slipped in, the parser stayed it straight.
The .cts files found their scripted place,
While .mjs still rejected, kept its space.
Tests now hum where once there was a gap—
A rabbit checks each corner off the map. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 inconclusive)

Check name	Status	Explanation	Resolution
Linked Issues check	❓ Inconclusive	Issues #453 and #454 are covered; #455 is only partially evidenced because the .cts guardrail addition in ast-support.ts isn't shown.	Add or confirm .cts is included in AST_LANGUAGE_EXTENSIONS.typescript and that ctx.ast("file.cts", "typescript") passes the guardrail.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title is concise and matches the main changes: injectable timeout, BOM tests, and .cts support.
Description check	✅ Passed	The description clearly summarizes the timeout, BOM, and .cts changes and their tests.
Out of Scope Changes check	✅ Passed	The changes stay focused on the three requested engine/test updates; no unrelated edits are evident.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying archgate-cli with    Cloudflare Pages

Latest commit:	7fee870
Status:	✅  Deploy successful!
Preview URL:	https://2280d288.archgate-cli.pages.dev
Branch Preview URL:	https://fix-issues-453-454-455.archgate-cli.pages.dev

View logs

[github-actions]

Code Coverage

Metric	Value
Lines	90.1% (7365 / 8171)
Threshold	90% minimum — met
Platforms	Linux + Windows

Full HTML report available in workflow artifacts.

Per-directory breakdown

Directory	Coverage	Lines
src/commands/	88.7%	1994 / 2249
src/engine/	91.2%	1632 / 1789
src/formats/	100.0%	142 / 142
src/helpers/	90.1%	3597 / 3991