ci(ratchets): fail PRs that add callers of sync helpers on Electron main (#43399)

* ci(ratchets): guard callers of sync helpers on main and skip worker-only modules

The main-thread ratchets counted blocking call syntax per file, so a new
caller of an existing sync helper in another file (env store reads, Codex
transcript cursor, durable secure writes) passed CI. A new ratchet counts
references to functions that make a synchronous fs, child_process or
SQLite call. Modules imported only by worker/utility entries are no longer
charged as main-thread work, and SQLite pragma()/transaction() now count.

* ci(ratchets): follow sync helpers two levels so timer and handler callers count

* ci(ratchets): guard event-loop entries, follow default exports and barrels, carry rows across renames

* test(ratchets): keep the shared import when checking a guarded entry

* ci(ratchets): shadow helpers only by parameters in scope, fail on unreadable entry lists, keep transaction results out of SQLite receivers

* ci(ratchets): match helper names file-wide (council ruling), harden entry discovery, count transaction modes

* Merge origin/main; baseline main's new WSL helper callers

* fix(ratchets): preserve helper exports and fail closed on missing roots

* Keep main's note on the worker large-send log baseline row
This commit is contained in:
Brennan Benson
2026-11-17 14:49:39 -08:00
committed by GitHub
parent 19e5992f0f
commit fb71c6ae4c
22 changed files with 2614 additions and 244 deletions
+1
View File
@@ -20,6 +20,7 @@ jobs:
run: |
node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-sync-fs-ratchet.mjs
node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-blocking-api-ratchet.mjs
node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-blocking-helper-ratchet.mjs
# The PR preflight runs spawn separately, so the discovery runner intentionally excludes it.
- name: Enforce synchronous launches
if: '!cancelled()'
+1 -1
View File
@@ -1,5 +1,5 @@
# Legacy synchronous atomics uses per file; counts may only go DOWN.
# Only explicit worker/utility entry files are exempt; their imports remain guarded.
# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.
1 src/main/runtime/rpc/server/pairing/device-registry-disk-merge.ts
1 src/main/startup/linux-display/ensure-virtual-display.ts
1 src/shared/file-write/windows-retry-file-operations.ts
@@ -1,5 +1,5 @@
# Legacy synchronous compression uses per file; counts may only go DOWN.
# Only explicit worker/utility entry files are exempt; their imports remain guarded.
# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.
1 src/main/browser/extensions/actions/browser-extension-action-icon.ts
2 src/main/native-chat/agent-session-journal/journal-stored-output.ts
1 src/main/runtime/rpc/mobile/e2ee/mobile-e2ee-v2-compressed-frame.ts
+1 -1
View File
@@ -1,3 +1,3 @@
# Legacy synchronous crypto uses per file; counts may only go DOWN.
# Only explicit worker/utility entry files are exempt; their imports remain guarded.
# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.
3 src/main/browser/cookies/sources/browser-cookie-key.ts
File diff suppressed because it is too large Load Diff
+3 -4
View File
@@ -1,12 +1,11 @@
# Legacy synchronous ipc uses per file; counts may only go DOWN.
# Only explicit worker/utility entry files are exempt; their imports remain guarded.
# Guest retirement must reserve and remove DOM in one renderer turn; async replies race visibility.
1 src/main/ipc/browser/browser-guest-discard-ipc.ts
1 src/preload/api/browser/browser-bridge-guest-discard.ts
# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.
3 src/main/host/native-chat-visual-guest-theme.ts
1 src/main/ipc/browser/browser-guest-discard-ipc.ts
1 src/main/ipc/renderer-shutdown-checkpoint.ts
1 src/main/ipc/settings/settings.ts
1 src/preload/api/app-bridge.ts
1 src/preload/api/browser/browser-bridge-guest-discard.ts
1 src/preload/api/native-chat/native-chat-bridge.ts
1 src/preload/api/preferences/settings-bridge.ts
1 src/preload/native-chat/native-chat-visual-guest-theme.ts
+21 -105
View File
@@ -1,22 +1,8 @@
# Legacy synchronous sqlite uses per file; counts may only go DOWN.
# Only explicit worker/utility entry files are exempt; their imports remain guarded.
3 src/main/ai-vault-search/query/session-search-engine.ts
6 src/main/ai-vault-search/query/session-search-postings.ts
8 src/main/ai-vault-search/query/session-search-retrieval.ts
2 src/main/ai-vault-search/query/session-search-snippet.ts
2 src/main/ai-vault-search/query/session-search-source-presence.ts
2 src/main/ai-vault-search/query/session-search-typo-repair.ts
10 src/main/ai-vault-search/storage/session-search-file-records.ts
8 src/main/ai-vault-search/storage/session-search-index-generation.ts
17 src/main/ai-vault-search/storage/session-search-index-writer.ts
# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.
10 src/main/ai-vault-search/storage/session-search-message-rows.ts
3 src/main/ai-vault-search/storage/session-search-query-schema.ts
22 src/main/ai-vault-search/storage/session-search-retention-delete.ts
13 src/main/ai-vault-search/storage/session-search-schema.ts
16 src/main/ai-vault-search/storage/session-search-store.ts
26 src/main/ai-vault-search/storage/session-search-tool-purge.ts
9 src/main/ai-vault-search/storage/session-search-write-buffer.ts
19 src/main/ai-vault/parse-cache/session-parse-cache-database.ts
20 src/main/ai-vault/parse-cache/session-parse-cache-database.ts
13 src/main/ai-vault/parse-cache/session-scope-cwds-table.ts
1 src/main/ai-vault/scanners/hermes/hermes-state-db-activity.ts
16 src/main/ai-vault/scanners/hermes/hermes-state-db-conversations.ts
@@ -25,115 +11,48 @@
2 src/main/ai-vault/scanners/hermes/session-scanner-hermes-sqlite.ts
2 src/main/ai-vault/scanners/opencode/sqlite/session-scanner-opencode-sqlite-capture.ts
4 src/main/ai-vault/scanners/opencode/sqlite/session-scanner-opencode-sqlite-list.ts
1 src/main/ai-vault/scanners/opencode/sqlite/session-scanner-opencode-sqlite-open.ts
2 src/main/ai-vault/scanners/opencode/sqlite/session-scanner-opencode-sqlite-open.ts
6 src/main/ai-vault/scanners/opencode/sqlite/session-scanner-opencode-sqlite.ts
5 src/main/ai-vault/scanners/opencode2/session-scanner-opencode2-sqlite-list.ts
9 src/main/ai-vault/scanners/opencode2/session-scanner-opencode2-sqlite.ts
6 src/main/ai-vault/scanners/opencode2/session-scanner-opencode2-sqlite-list.ts
10 src/main/ai-vault/scanners/opencode2/session-scanner-opencode2-sqlite.ts
5 src/main/browser-passwords/browser-password-chromium-import.ts
1 src/main/browser/cookies/chromium/prepare-import.ts
5 src/main/browser/cookies/sources/browser-cookie-firefox-import.ts
25 src/main/browser/cookies/staging/browser-cookie-staged-import.ts
5 src/main/codex/history/index/codex-state-db.ts
3 src/main/foreign-sqlite-readers/readers/cursor-profile.ts
44 src/main/github/pr-watch/pr-check-event-tables.ts
14 src/main/github/pr-watch/pr-pending-actions.ts
18 src/main/github/pr-watch/pr-watch-tables.ts
6 src/main/managed-data-accounts/credential-capture.ts
7 src/main/managed-data-accounts/credential-capture.ts
19 src/main/native-chat/agent-session-attachments/agent-session-attachment-claims.ts
3 src/main/native-chat/agent-session-journal/database/journal-checkpoint-owner.ts
13 src/main/native-chat/agent-session-journal/database/journal-database.ts
7 src/main/native-chat/agent-session-journal/database/journal-domain-database.ts
5 src/main/native-chat/agent-session-journal/database/journal-domain-migrations.ts
20 src/main/native-chat/agent-session-journal/database/journal-domain-profile-import.ts
5 src/main/native-chat/agent-session-journal/database/journal-checkpoint-owner.ts
22 src/main/native-chat/agent-session-journal/database/journal-database.ts
14 src/main/native-chat/agent-session-journal/database/journal-domain-database.ts
7 src/main/native-chat/agent-session-journal/database/journal-domain-migrations.ts
22 src/main/native-chat/agent-session-journal/database/journal-domain-profile-import.ts
1 src/main/native-chat/agent-session-journal/database/journal-host-database.ts
32 src/main/native-chat/agent-session-journal/database/journal-legacy-reconcile.ts
18 src/main/native-chat/agent-session-journal/database/journal-legacy-source.ts
12 src/main/native-chat/agent-session-journal/durable-rows/journal-row-table.ts
18 src/main/native-chat/agent-session-journal/history-import/journal-pi-active-branch.ts
14 src/main/native-chat/agent-session-journal/journal-domain-command-turn.ts
2 src/main/native-chat/agent-session-journal/journal-domain-context-command.ts
17 src/main/native-chat/agent-session-journal/journal-domain-context-replacement.ts
10 src/main/native-chat/agent-session-journal/journal-domain-control-command.ts
8 src/main/native-chat/agent-session-journal/journal-domain-current-item.ts
4 src/main/native-chat/agent-session-journal/journal-domain-dispatch-attempt.ts
2 src/main/native-chat/agent-session-journal/journal-domain-dispatch-placement.ts
8 src/main/native-chat/agent-session-journal/journal-domain-dispatch.ts
24 src/main/native-chat/agent-session-journal/journal-domain-edit-leases.ts
10 src/main/native-chat/agent-session-journal/journal-domain-generation-reads.ts
2 src/main/native-chat/agent-session-journal/journal-domain-generation-settlement.ts
10 src/main/native-chat/agent-session-journal/journal-domain-history-after.ts
9 src/main/native-chat/agent-session-journal/journal-domain-history-page.ts
4 src/main/native-chat/agent-session-journal/journal-domain-history-roster.ts
8 src/main/native-chat/agent-session-journal/journal-domain-history-window.ts
6 src/main/native-chat/agent-session-journal/journal-domain-import-discard.ts
24 src/main/native-chat/agent-session-journal/journal-domain-import-rows.ts
4 src/main/native-chat/agent-session-journal/journal-domain-import-submissions.ts
2 src/main/native-chat/agent-session-journal/journal-domain-import.ts
16 src/main/native-chat/agent-session-journal/journal-domain-input-ends.ts
12 src/main/native-chat/agent-session-journal/journal-domain-input-recovery.ts
4 src/main/native-chat/agent-session-journal/journal-domain-item-display.ts
4 src/main/native-chat/agent-session-journal/journal-domain-item-names.ts
2 src/main/native-chat/agent-session-journal/journal-domain-item-normalization.ts
4 src/main/native-chat/agent-session-journal/journal-domain-item-presentation.ts
24 src/main/native-chat/agent-session-journal/journal-domain-item-removal.ts
18 src/main/native-chat/agent-session-journal/journal-domain-item.ts
4 src/main/native-chat/agent-session-journal/journal-domain-lifecycle-dispatch.ts
12 src/main/native-chat/agent-session-journal/journal-domain-lifecycle-item.ts
12 src/main/native-chat/agent-session-journal/journal-domain-lifecycle.ts
11 src/main/native-chat/agent-session-journal/journal-domain-maintenance.ts
14 src/main/native-chat/agent-session-journal/journal-domain-outline.ts
8 src/main/native-chat/agent-session-journal/journal-domain-queue-clear.ts
6 src/main/native-chat/agent-session-journal/journal-domain-queue-command.ts
12 src/main/native-chat/agent-session-journal/journal-domain-maintenance.ts
10 src/main/native-chat/agent-session-journal/journal-domain-queue-failures.ts
6 src/main/native-chat/agent-session-journal/journal-domain-queue-pauses.ts
8 src/main/native-chat/agent-session-journal/journal-domain-queue-reads.ts
4 src/main/native-chat/agent-session-journal/journal-domain-queue-revision.ts
10 src/main/native-chat/agent-session-journal/journal-domain-queue-rows.ts
2 src/main/native-chat/agent-session-journal/journal-domain-request-failure.ts
8 src/main/native-chat/agent-session-journal/journal-domain-retained-failures.ts
6 src/main/native-chat/agent-session-journal/journal-domain-stop-notes.ts
12 src/main/native-chat/agent-session-journal/journal-domain-submission-admission.ts
2 src/main/native-chat/agent-session-journal/journal-domain-submission-consume.ts
4 src/main/native-chat/agent-session-journal/journal-domain-submission-records.ts
2 src/main/native-chat/agent-session-journal/journal-domain-submission-revision.ts
4 src/main/native-chat/agent-session-journal/journal-domain-taken-stop.ts
2 src/main/native-chat/agent-session-journal/journal-domain-text-snapshot.ts
14 src/main/native-chat/agent-session-journal/journal-domain-timeline-reads.ts
4 src/main/native-chat/agent-session-journal/journal-domain-turn-scope.ts
20 src/main/native-chat/agent-session-journal/journal-forgotten-chats.ts
10 src/main/native-chat/agent-session-journal/journal-fork-capture.ts
30 src/main/native-chat/agent-session-journal/journal-fork-preparation.ts
20 src/main/native-chat/agent-session-journal/journal-fork-presentation.ts
4 src/main/native-chat/agent-session-journal/journal-fork-source-proof.ts
10 src/main/native-chat/agent-session-journal/journal-fork-stage-page.ts
12 src/main/native-chat/agent-session-journal/journal-fork-stages.ts
4 src/main/native-chat/agent-session-journal/journal-fork-workspace.ts
2 src/main/native-chat/agent-session-journal/journal-items-by-kind-page.ts
2 src/main/native-chat/agent-session-journal/journal-open-queue-withdrawal.ts
4 src/main/native-chat/agent-session-journal/journal-sql-accepted-inputs.ts
6 src/main/native-chat/agent-session-journal/journal-sql-automatic-submission-command.ts
6 src/main/native-chat/agent-session-journal/journal-sql-batch.ts
10 src/main/native-chat/agent-session-journal/journal-sql-claude-identities.ts
2 src/main/native-chat/agent-session-journal/journal-sql-command-dispatch.ts
8 src/main/native-chat/agent-session-journal/journal-sql-continuation-context.ts
21 src/main/native-chat/agent-session-journal/journal-sql-database-read.ts
2 src/main/native-chat/agent-session-journal/journal-sql-edit-lease-command.ts
12 src/main/native-chat/agent-session-journal/journal-sql-event-tail.ts
4 src/main/native-chat/agent-session-journal/journal-sql-history-items.ts
22 src/main/native-chat/agent-session-journal/journal-sql-item-reads.ts
10 src/main/native-chat/agent-session-journal/journal-sql-lifecycle-reads.ts
5 src/main/native-chat/agent-session-journal/journal-sql-message-commit.ts
12 src/main/native-chat/agent-session-journal/journal-sql-message-effects.ts
13 src/main/native-chat/agent-session-journal/journal-sql-open-command.ts
5 src/main/native-chat/agent-session-journal/journal-sql-read-transaction.ts
10 src/main/native-chat/agent-session-journal/journal-sql-rewind-command.ts
4 src/main/native-chat/agent-session-journal/journal-sql-send-admission.ts
7 src/main/native-chat/agent-session-journal/journal-sql-steps.ts
10 src/main/native-chat/agent-session-journal/journal-stored-output-compaction.ts
4 src/main/native-chat/agent-session-journal/journal-stored-output-rows.ts
4 src/main/native-chat/agent-session-journal/journal-writer-effects.ts
4 src/main/native-chat/agent-session-journal/journal-writer-operation-expiry.ts
12 src/main/native-chat/agent-session-journal/journal-writer-store-mutation.ts
15 src/main/native-chat/agent-session-journal/outcomes/journal-outcome-format.ts
6 src/main/native-chat/agent-session-journal/outcomes/journal-outcome-table.ts
2 src/main/native-chat/agent-session-journal/queued-messages/journal-queue-import.ts
@@ -148,18 +67,16 @@
10 src/main/native-chat/transcript-history/opencode/transcript-opencode-sqlite-query.ts
14 src/main/native-chat/transcript-history/opencode/transcript-opencode2-fork-coverage.ts
10 src/main/native-chat/transcript-history/opencode/transcript-opencode2-sqlite.ts
10 src/main/opencode-usage/opencode-usage-row-queries.ts
1 src/main/opencode-usage/scanner.ts
12 src/main/persistence/moving-wsl-projects/desktop-state/wsl-move-orchestration-history-rewrite.ts
13 src/main/persistence/moving-wsl-projects/desktop-state/wsl-move-orchestration-history-rewrite.ts
8 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs-migration.ts
4 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs-reader.ts
6 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs-storage.ts
2 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs-validation.ts
8 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs-writer.ts
2 src/main/persistence/profile-state/automation-runs/profile-state-automation-runs.ts
3 src/main/persistence/profile-state/database/profile-state-database-snapshot.ts
4 src/main/persistence/profile-state/database/profile-state-database-validation.ts
6 src/main/persistence/profile-state/database/profile-state-database.ts
4 src/main/persistence/profile-state/database/profile-state-database-snapshot.ts
5 src/main/persistence/profile-state/database/profile-state-database-validation.ts
15 src/main/persistence/profile-state/database/profile-state-database.ts
3 src/main/persistence/profile-state/database/profile-state-read-snapshot.ts
4 src/main/persistence/profile-state/database/profile-state-revision.ts
3 src/main/persistence/profile-state/database/profile-state-write-transaction.ts
@@ -172,7 +89,7 @@
8 src/main/persistence/profile-state/documents/profile-state-domain-writes.ts
4 src/main/persistence/profile-state/legacy-json/profile-state-json-acceptance.ts
2 src/main/persistence/profile-state/recovery/profile-state-section-repair.ts
3 src/main/rate-limits/providers/opencode-go/opencode-go-api-key-source.ts
4 src/main/rate-limits/providers/opencode-go/opencode-go-api-key-source.ts
2 src/main/runtime/agent-session/records/agent-session-record-lineage.ts
40 src/main/runtime/agent-session/records/agent-session-record-rows.ts
23 src/main/runtime/orchestration/db/dispatch-context/presentation-completion-source.ts
@@ -180,16 +97,15 @@
1 src/main/runtime/orchestration/db/federation/federated-stub-home-run-backfill.ts
9 src/main/runtime/orchestration/db/lifecycle-transition.ts
7 src/main/runtime/orchestration/db/mutation-receipts/mutation-receipt-capacity.ts
5 src/main/runtime/orchestration/db/orchestration-db.ts
11 src/main/runtime/orchestration/db/orchestration-db.ts
4 src/main/runtime/orchestration/db/peer-runs/peer-run-queue-sql.ts
10 src/main/runtime/orchestration/db/reset/removed-orchestration-work-read.ts
6 src/main/runtime/orchestration/db/reset/removed-orchestration-work-store.ts
4 src/main/runtime/orchestration/db/runs/run-coordinator-mail-routing.ts
12 src/main/runtime/orchestration/db/schema/orchestration-schema-version-skew.ts
15 src/main/runtime/orchestration/db/schema/orchestration-schema-version-skew.ts
15 src/main/runtime/orchestration/db/schema/structured-worker-orca-session-backfill.ts
5 src/main/runtime/orchestration/db/worker-dispatch/worker-dispatch-settlement.ts
4 src/main/runtime/orchestration/workers/lifecycle/context-only-dispatch-release.ts
19 src/main/sqlite/row-cache/keyed-json-row-cache.ts
24 src/main/sqlite/row-cache/keyed-json-row-cache.ts
5 src/main/sqlite/sync-database.ts
8 src/main/sqlite/versioned-cache-database.ts
6 src/main/wsl/filesystem/wsl-drive-unc-chat-rekey.ts
14 src/main/sqlite/versioned-cache-database.ts
+35 -51
View File
@@ -1,4 +1,5 @@
# Synchronous node:fs calls (every *Sync export) in production src/main and src/shared, per file.
# Synchronous node:fs calls (every *Sync export) in production src/main and src/shared, per file;
# modules imported only by worker/utility entries are excluded.
# Startup-only or one-shot uses are fine to keep; per-RPC, per-spawn, per-focus or per-poll uses are the target.
# This is a RATCHET: counts may only go DOWN.
# Prune after removing calls: pnpm check:main-sync-fs-ratchet --prune
@@ -128,7 +129,6 @@
1 src/main/codex-accounts/runtime-home/routing/runtime-home-service-managed-home.ts
14 src/main/codex-accounts/runtime-home/runtime-home-service-paths.ts
1 src/main/codex-accounts/runtime-home/runtime-home-service-sync.ts
1 src/main/codex-usage/codex-session-file-discovery.ts
1 src/main/codex/configuration/codex-path-observation.ts
21 src/main/codex/configuration/homes/codex-home-paths.ts
6 src/main/codex/configuration/homes/codex-managed-home-resource-copy-marker.ts
@@ -146,7 +146,6 @@
5 src/main/codex/history/index/codex-session-index-heal-state.ts
2 src/main/codex/history/index/codex-state-db.ts
2 src/main/codex/history/resume/codex-session-resume-home.ts
2 src/main/codex/history/rollouts/codex-account-home-discovery.ts
1 src/main/codex/history/rollouts/codex-session-file-listing.ts
2 src/main/codex/history/rollouts/codex-session-link.ts
1 src/main/codex/hooks/installation/codex-hook-local-install.ts
@@ -160,10 +159,7 @@
1 src/main/codex/trust/hooks/hook-trust-promotion.ts
1 src/main/codex/trust/identity/codex-trust-identity.ts
1 src/main/codex/trust/toml/config-toml-project-trust.ts
2 src/main/computer/desktop-script/desktop-script-provider-paths.ts
1 src/main/computer/macos-native/macos-native-provider-client.ts
3 src/main/computer/macos-native/macos-native-provider-paths.ts
5 src/main/computer/macos-native/macos-native-provider-transport.ts
1 src/main/computer/sidecar-transport/sidecar-client.ts
3 src/main/connector-cloud/connector-turn-events.ts
1 src/main/copilot/hook-service.ts
@@ -244,11 +240,10 @@
14 src/main/filesystem/atomic-file-publication.ts
9 src/main/filesystem/durable-file-write.ts
3 src/main/filesystem/file-content-observation.ts # Existing reads/existence checks relocated from observed callers; no new synchronous I/O.
2 src/main/filesystem/local-file-io/filesystem-path-containment.ts
2 src/main/filesystem/rolling-file-backup.ts
2 src/main/foreign-sqlite-readers/foreign-sqlite-reader-entry-path.ts
1 src/main/foreign-sqlite-readers/foreign-sqlite-reader-spawn.ts
1 src/main/foreign-sqlite-readers/readers/cursor-profile.ts
1 src/main/foreign-sqlite-readers/readers/opencode-binder-sessions.ts
5 src/main/git/repositories/discovery/repo-detection.ts
13 src/main/git/repositories/discovery/repo-git-marker-scan.ts
1 src/main/git/source-control/ignores/huge-folder-ignore.ts
@@ -259,7 +254,6 @@
4 src/main/grok/grok-hook-symlink-cleanup-marker.ts
4 src/main/grok/hook-service.ts
8 src/main/hang-watchdog/hang-detection-marker.ts
4 src/main/hang-watchdog/hang-incident-snapshot.ts
1 src/main/hang-watchdog/hang-watchdog-worker-path.ts
1 src/main/hang-watchdog/previous-hang-detection.ts
9 src/main/hang-watchdog/renderer-hang-records.ts
@@ -271,23 +265,19 @@
1 src/main/ipc/command-path/command-path-directory-worker-client.ts
1 src/main/ipc/command-path/command-path-resolver.ts
4 src/main/ipc/diagnostics.ts
2 src/main/filesystem/local-file-io/filesystem-path-containment.ts
2 src/main/ipc/filesystem/watcher-process/child-lifecycle/parcel-watcher-canary-directory.ts
1 src/main/ipc/filesystem/watcher-process/child-lifecycle/parcel-watcher-child-launch.ts
4 src/main/ipc/filesystem/watcher-process/event-delivery/parcel-watcher-delivery-canary.ts
1 src/main/ipc/filesystem/watcher-process/native-subscriptions/parcel-watcher-shallow-file-subscription.ts
1 src/main/ipc/filesystem/watcher-process/native-subscriptions/parcel-watcher-shallow-subscription.ts
1 src/main/ipc/filesystem/watcher-process/native-subscriptions/rebinding-file-watch.ts
3 src/main/ipc/filesystem/watcher-process/parcel-watcher-entry-path.ts
1 src/main/ipc/filesystem/watcher-process/root-paths/watcher-event-root-path-rewrite.ts
1 src/main/ipc/filesystem/watcher-process/supervision/parcel-watcher-supervisor-subscribe.ts
1 src/main/ipc/worktrees/floating-workspace-directory.ts
1 src/main/ipc/keyboard/macos-keyboard-layout-snapshot.ts
1 src/main/ipc/notifications/notification-authorization-status.ts
1 src/main/ipc/pty/host-env/spawn-pane-env.ts
1 src/main/ipc/ssh/ssh-connect-flow.ts
1 src/main/ipc/worktrees/floating-workspace-directory.ts
2 src/main/ipc/worktrees/worktree-remote.ts
2 src/main/wsl/filesystem/wsl-guest-windows-drive-path.ts
7 src/main/jcode/hook-service.ts
8 src/main/jira/site-credential-store.ts
7 src/main/keybindings/keybinding-file-parser.ts
@@ -318,7 +308,6 @@
3 src/main/native-chat/agent-session-journal/database/journal-legacy-source-receipt.ts
1 src/main/native-chat/transcript-discovery/host-readable-transcript-path.ts
2 src/main/native-chat/transcript-filesystem/process/wsl-transcript-fs-process-spawn.ts
1 src/main/node-runtime/appimage-bundled-node-runtime.ts
2 src/main/node-runtime/managed-runtime-release-install.ts
7 src/main/node-runtime/managed-runtime-release.ts
11 src/main/notebook/python-environments.ts
@@ -370,11 +359,10 @@
7 src/main/orcad/native-runtime/node-pty-prebuilt-slot.ts
2 src/main/orcad/native-runtime/node-pty-precondition.ts
1 src/main/orcad/profile-state/orcad-host-identity-reset.ts
1 src/main/orcad/profile-state/serve-profile-ssh-targets.ts
12 src/main/orcad/runtime-launch/orcad-bundled-runtime.ts
8 src/main/orcad/runtime-launch/windows-breakaway-launcher.ts
2 src/main/orcad/serve-startup/orcad-cli-launcher.ts
1 src/main/orcad/serve-startup/orcad-command-arguments.ts
7 src/main/orcad/serve-startup/orcad-local-serve-selection.ts
6 src/main/persistence/atomic-snapshot-writer.ts
5 src/main/persistence/loading-store/user-data-path.ts
4 src/main/persistence/migrating-orcad-catalog/blob-transfer/orcad-migration-blob-installers.ts
@@ -432,13 +420,9 @@
3 src/main/plugins/storage/plugin-secrets-store.ts
3 src/main/plugins/storage/plugin-storage-store.ts
1 src/main/plugins/testing/plugin-editor-static-check.ts
3 src/main/plugins/workers/child-runtime/plugin-worker-source-hooks.ts
1 src/main/plugins/workers/parent-process/plugin-host-process.ts
8 src/main/ports/darwin-port-scan-lock.ts
1 src/main/ports/port-scan-command-client.ts
1 src/main/ports/port-scan-command-execution.ts
2 src/main/provider-process/provider-executable-missing.ts
# One cached startup capability check per state directory, before choosing native versus legacy dispatch.
3 src/main/provider-process/provider-ownership-journal.ts
5 src/main/providers/local-pty/local-pty-executable-spawn.ts
1 src/main/providers/local-pty/local-pty-session-operations.ts
@@ -446,6 +430,7 @@
1 src/main/providers/shell-launch/macos/login-session-pty-probe.ts
3 src/main/providers/shell-launch/macos/tcc-login-shell.ts
3 src/main/providers/shell-launch/windows/powershell-executable.ts
2 src/main/providers/shell-launch/windows/windows-interactive-login-spawn.ts
2 src/main/providers/working-directory/validation.ts
4 src/main/pty/history/fish-history-session.ts
4 src/main/pty/history/terminal-history-deletion.ts
@@ -470,10 +455,10 @@
2 src/main/rate-limits/providers/opencode-go/opencode-go-api-key-source.ts
1 src/main/rate-limits/providers/zcode/zcode-usage-credentials.ts
3 src/main/ripgrep/bundled-ripgrep-path.ts
1 src/main/runtime/agent-session/installation/structured-agent-session-attachment-wiring.ts
8 src/main/runtime/agent-session/ownership/agent-session-claim-identity.ts
1 src/main/runtime/agent-session/records/agent-session-record-store-slot.ts
7 src/main/runtime/agent-session/records/agent-session-runtime-end-record.ts
1 src/main/runtime/agent-session/installation/structured-agent-session-attachment-wiring.ts
1 src/main/runtime/client/navigation/desktop-chat-creation-history.ts
9 src/main/runtime/host-instance-identity.ts
4 src/main/runtime/hosts/platform-probe/host-descriptor.ts
@@ -564,6 +549,7 @@
1 src/main/wsl/execution/wsl-node-runtime-prefetch.ts
3 src/main/wsl/filesystem/wsl-drive-project-new-default.ts
9 src/main/wsl/filesystem/wsl-drive-unc-conversion-stores.ts
2 src/main/wsl/filesystem/wsl-guest-windows-drive-path.ts
2 src/main/wsl/host-lifecycle/wsl-host-automation-wake-store.ts
4 src/main/wsl/host-lifecycle/wsl-host-e2e-fake-connector.ts
1 src/main/wsl/host-lifecycle/wsl-host-early-wake.ts
@@ -571,51 +557,49 @@
1 src/main/zcode/hook-config-json.ts
12 src/main/zcode/zcode-plan-api-key-store.ts
6 src/shared/agent-hook-listener/claude-session-continuation.ts
9 src/shared/agent-hook-listener/providers/codex/codex-rollout-jsonl-cursor.ts
1 src/shared/agent-hook-listener/providers/codex/codex-subagent-roster.ts
3 src/shared/agent-hook-listener/providers/grok/grok-session-paths.ts
2 src/shared/agent-hook-listener/providers/jcode/jcode-session-files.ts
1 src/shared/agent-hook-listener/providers/muse/muse-session-log.ts
4 src/shared/agent-hook-listener/reverse-file-region-scan.ts
3 src/shared/agent-hook-listener/transcript-reader.ts
3 src/shared/agent-hook-listener/transport/agent-hook-endpoint-temp-cleanup.ts
13 src/shared/agent-hook-listener/transport/agent-hook-spool.ts
5 src/shared/agent-hook-listener/transport/endpoint-publication.ts
4 src/shared/agent-launch/startup/omp-fresh-config.ts
2 src/shared/desktop-distribution/appimage/appimage-cache-identity.ts
2 src/shared/web-client/bundled-web-client-manifest.ts
3 src/shared/web-client/bundled-web-client-root.ts
5 src/shared/shell/command-resolution/cli-fs-reads.ts
3 src/shared/shell/launch/cli-runtime-pairing-inputs.ts
9 src/shared/agent-hook-listener/providers/codex/codex-rollout-jsonl-cursor.ts
1 src/shared/agent-hook-listener/providers/codex/codex-subagent-roster.ts
4 src/shared/remote-runtime/ephemeral-vm-recipes/ephemeral-vm-recipe-doctor.ts
1 src/shared/remote-runtime/ephemeral-vm-recipes/ephemeral-vm-recipe-runner.ts
1 src/shared/remote-runtime/ephemeral-vm-store/ephemeral-vm-runtime-feature-store.ts
1 src/shared/remote-runtime/ephemeral-vm-store/ephemeral-vm-runtime-store.ts
6 src/shared/file-content/node-bounded-file-reader.ts
5 src/shared/file-content/node-file-content-equality.ts
6 src/shared/file-content/node-source-copy-content-equality.ts
3 src/shared/agent-hook-listener/providers/grok/grok-session-paths.ts
2 src/shared/agent-hook-listener/providers/jcode/jcode-session-files.ts
1 src/shared/agent-hook-listener/providers/muse/muse-session-log.ts
1 src/shared/agent-launch/plugins/opencode/opencode-installed-plugin.ts
10 src/shared/agent-launch/plugins/opencode/opencode-plugin-atomic-write.ts
5 src/shared/agent-launch/plugins/opencode/opencode-tui-config-registration.ts
1 src/shared/agent-launch/plugins/opencode/opencode-tui-plugin-install.ts
2 src/shared/remote-runtime/orcad-distribution/orcad-build-identity.ts
1 src/shared/plugins/declarative/testing/orca-testing.ts
4 src/shared/agent-launch/startup/omp-fresh-config.ts
2 src/shared/desktop-distribution/appimage/appimage-cache-identity.ts
2 src/shared/file-access/real-path-sync.ts
6 src/shared/file-content/node-bounded-file-reader.ts
5 src/shared/file-content/node-file-content-equality.ts
6 src/shared/file-content/node-source-copy-content-equality.ts
2 src/shared/file-write/windows-retry-file-operations.ts
1 src/shared/file-write/windows-transient-lock-removal.ts
1 src/shared/plugins/declarative/testing/orca-testing.ts
1 src/shared/remote-runtime/e2ee/node/remote-runtime-e2ee-v2-host-latch.ts
4 src/shared/remote-runtime/ephemeral-vm-recipes/ephemeral-vm-recipe-doctor.ts
1 src/shared/remote-runtime/ephemeral-vm-recipes/ephemeral-vm-recipe-runner.ts
1 src/shared/remote-runtime/ephemeral-vm-store/ephemeral-vm-runtime-feature-store.ts
1 src/shared/remote-runtime/ephemeral-vm-store/ephemeral-vm-runtime-store.ts
1 src/shared/remote-runtime/host-store/runtime-e2ee-keypair-file.ts
1 src/shared/remote-runtime/host-store/runtime-environment-store-records.ts
13 src/shared/secure-storage/secure-file.ts
1 src/shared/secure-storage/secure-path-metadata-snapshot.ts
1 src/shared/secure-storage/secure-path-windows-acl.ts
2 src/shared/remote-runtime/orcad-distribution/orcad-build-identity.ts
3 src/shared/remote-runtime/serve-supervisor/serve-abort-park.ts
7 src/shared/remote-runtime/serve-supervisor/serve-bundle-park.ts
1 src/shared/remote-runtime/serve-supervisor/serve-user-data-path.ts
13 src/shared/secure-storage/secure-file.ts
1 src/shared/secure-storage/secure-path-metadata-snapshot.ts
1 src/shared/secure-storage/secure-path-windows-acl.ts
2 src/shared/secure-storage/windows-security-addon.ts
5 src/shared/shell/command-resolution/cli-fs-reads.ts
3 src/shared/shell/launch/cli-runtime-pairing-inputs.ts
5 src/shared/shell/launch/startup-command-staging.ts
3 src/shared/source-scan/source-tree-scan.ts
2 src/shared/speech/native-recognizer/speech-recognizer-package.ts
5 src/shared/shell/launch/startup-command-staging.ts
1 src/shared/terminal/pty/native-process/pty-process-ceiling-state.ts
8 src/main/orcad/runtime-launch/windows-breakaway-launcher.ts
2 src/main/providers/shell-launch/windows/windows-interactive-login-spawn.ts
2 src/shared/file-write/windows-retry-file-operations.ts
2 src/shared/secure-storage/windows-security-addon.ts
1 src/shared/file-write/windows-transient-lock-removal.ts
2 src/shared/web-client/bundled-web-client-manifest.ts
3 src/shared/web-client/bundled-web-client-root.ts
+6 -2
View File
@@ -54,10 +54,14 @@ old behavior. Use controlled, counterbalanced benchmark samples for timings;
avoid new machine-dependent millisecond gates in the normal unit suite. A green
source scan and these contracts cannot establish that the whole app is fast.
Two count ratchets (counts per file may only fall) cover classes the audit only warns about:
Count ratchets (counts per file may only fall) cover classes the audit only warns about:
`pnpm check:main-sync-fs-ratchet` counts synchronous `node:fs` calls (every `*Sync` export) in production `src/main` and `src/shared`
(`config/main-sync-fs-baseline.txt`), and `pnpm check:recurring-timer-ratchet` counts `setInterval`
calls in production `src/main`, `src/renderer`, `src/shared` and `src/cli`
(`config/recurring-timer-baseline.txt`). Both run in `check:ratchets` on every non-draft PR that runs static analysis. A new use either
(`config/recurring-timer-baseline.txt`). `pnpm check:main-blocking-helper-ratchet` counts references to
functions that make a synchronous fs, child_process or SQLite call, or call such a function (`config/main-blocking-helper-baseline.txt`),
so a new caller of an existing sync helper in another file fails too. The main-blocking ratchets skip modules
imported only by worker or utility entries (`config/main-blocking-worker-entries.json`). All run in
`check:ratchets` on every non-draft PR that runs static analysis. A new use either
moves off the hot path (async fs or a stat-fingerprint cache; a push signal, a visibility-gated or
backing-off timer) or raises its file's count with reviewer sign-off.
@@ -27,6 +27,18 @@ const SOURCE_ROOTS = ['src/', 'mobile/', 'tests/', 'config/']
const TEST_FILE = /\.(?:test|spec|e2e|bench)\.[cm]?[jt]sx?$/
const LOCALES = 'src/renderer/src/i18n/'
const MAIN_BLOCKING_GRAPH_INPUTS = [
'src/main/',
'src/shared/',
'src/preload/',
'src/packages/',
'src/cli/',
'config/build-plugins/',
'config/main-blocking-worker-entries.json',
'config/scripts/static-analysis/process-boundaries/main-blocking-source-paths.mjs',
'config/scripts/workspace/source-exports/'
]
// Ratchets default to SOURCE_ROOTS; list narrower inputs only where a scan is clearly scoped.
const RATCHET_INPUTS = {
'check-daemon-blocking-call-ratchet.mjs': ['src/main/'],
@@ -35,12 +47,9 @@ const RATCHET_INPUTS = {
'check-host-list-render-ratchet.mjs': ['src/renderer/src/'],
'check-id-only-store-write-ratchet.mjs': ['src/main/persistence/'],
'check-layout-writer-ratchets.mjs': ['src/main/', 'src/renderer/src/'],
'check-main-sync-fs-ratchet.mjs': [
'src/main/',
'src/shared/',
'config/main-blocking-worker-entries.json',
'config/scripts/static-analysis/process-boundaries/main-blocking-source-paths.mjs'
],
// Both build the event-loop import graph, so anything that changes graph edges selects them.
'check-main-blocking-helper-ratchet.mjs': MAIN_BLOCKING_GRAPH_INPUTS,
'check-main-sync-fs-ratchet.mjs': MAIN_BLOCKING_GRAPH_INPUTS,
'check-main-sync-spawn-ratchet.mjs': [
'src/main/',
'src/shared/',
@@ -306,11 +315,24 @@ export function selectTypecheckProjects(files) {
const RATCHET_SHARED_MODULES = {
'config/scripts/static-analysis/process-boundaries/gated-call-use-collector.mjs': [
'check-main-blocking-api-ratchet.mjs',
'check-main-blocking-helper-ratchet.mjs',
'check-daemon-blocking-call-ratchet.mjs',
'check-main-sync-fs-ratchet.mjs',
'check-main-sync-spawn-ratchet.mjs',
'check-recurring-timer-ratchet.mjs'
],
'config/scripts/static-analysis/process-boundaries/main-blocking-import-graph.mjs': [
'check-main-blocking-api-ratchet.mjs',
'check-main-blocking-helper-ratchet.mjs',
'check-main-sync-fs-ratchet.mjs'
],
'config/scripts/static-analysis/process-boundaries/main-blocking-helper-propagation.mjs': [
'check-main-blocking-helper-ratchet.mjs'
],
'config/scripts/static-analysis/process-boundaries/sqlite-call-use-collector.mjs': [
'check-main-blocking-api-ratchet.mjs',
'check-main-blocking-helper-ratchet.mjs'
],
'config/scripts/static-analysis/ratchets/react-compiler/react-compiler-hazards.mjs': [
'check-react-compiler-compat-ratchet.mjs'
],
@@ -46,6 +46,7 @@ export const LINT_STEPS = [
'check:unproven-pty-retirement-ratchet',
'check:daemon-blocking-call-ratchet',
'check:main-sync-fs-ratchet',
'check:main-blocking-helper-ratchet',
'check:recurring-timer-ratchet',
'check:node-runtime-pin',
'check:path-literal-ratchet',
@@ -16,7 +16,7 @@ function moduleKey(file) {
return normalized(file).replace(/\.[cm]?[jt]sx?$/, '')
}
function isValueReference(node) {
export function isValueReference(node) {
const parent = node.parent
if (
ts.isImportSpecifier(parent) ||
@@ -55,22 +55,36 @@ export function createGatedCallCollector(families, ratchetName) {
const advice = new Map(families.flatMap((family) => Object.entries(family.advice)))
const markers = [
...advice.keys(),
...families.flatMap((family) => Object.keys(family.localAdvice ?? {})),
...families.filter((family) => family.exportPattern).map(() => 'Sync'),
...new Set(
families.flatMap((family) => family.modules.map((module) => path.posix.basename(module)))
)
]
function symbolsOf(key) {
const matched = families.filter((family) => family.modules.includes(key))
if (!matched.length) {
const familiesByModule = new Map()
for (const family of families) {
for (const module of family.modules) {
familiesByModule.set(module, [...(familiesByModule.get(module) ?? []), family])
}
}
function symbolsOf(key, local = false) {
const matched = familiesByModule.get(key)
if (!matched) {
return null
}
const names = new Set(matched.flatMap((family) => Object.keys(family.advice)))
const names = new Set(
matched.flatMap((family) => [
...Object.keys(family.advice),
...(local ? Object.keys(family.localAdvice ?? {}) : [])
])
)
const patterns = matched.map((family) => family.exportPattern).filter(Boolean)
names.has = (name) =>
Set.prototype.has.call(names, name) ||
(typeof name === 'string' && patterns.some((pattern) => pattern.test(name)))
names.moduleKey = key
return names
}
@@ -100,16 +114,21 @@ export function createGatedCallCollector(families, ratchetName) {
throw new Error(`Cannot parse ${file}; the ${ratchetName} ratchet must not skip it.`)
}
if (!analyze) {
return { count: 0, symbols: [] }
return { count: 0, symbols: [], sites: [] }
}
const used = new Set()
const sites = []
let count = 0
const namespaces = new Map(
families.flatMap((family) =>
(family.globals ?? []).map((name) => [name, new Set(Object.keys(family.advice))])
)
)
const functions = new Map([...(symbolsOf(moduleKey(file)) ?? [])].map((name) => [name, name]))
const functions = new Map(
[...(symbolsOf(moduleKey(file), true) ?? [])].map((name) => [name, name])
)
// Which module each local function binding came from, so same-named exports stay distinct.
const origins = new Map([...functions.keys()].map((name) => [name, moduleKey(file)]))
const aliases = []
const members = []
const identifiers = []
@@ -154,8 +173,9 @@ export function createGatedCallCollector(families, ratchetName) {
}
return null
}
function recordUse(name) {
function recordUse(name, node, module) {
used.add(name)
sites.push({ name, position: node.getStart(source), module })
count += 1
}
function visitImport(node) {
@@ -166,6 +186,10 @@ export function createGatedCallCollector(families, ratchetName) {
}
if (clause.name) {
namespaces.set(clause.name.text, symbols)
if (symbols.has('default')) {
functions.set(clause.name.text, 'default')
origins.set(clause.name.text, symbols.moduleKey)
}
}
const named = clause.namedBindings
if (named && ts.isNamespaceImport(named)) {
@@ -175,6 +199,7 @@ export function createGatedCallCollector(families, ratchetName) {
const imported = (element.propertyName ?? element.name).text
if (!element.isTypeOnly && symbols.has(imported)) {
functions.set(element.name.text, imported)
origins.set(element.name.text, symbols.moduleKey)
}
}
}
@@ -193,8 +218,7 @@ export function createGatedCallCollector(families, ratchetName) {
.filter((element) => !element.isTypeOnly)
.map((element) => (element.propertyName ?? element.name).text)
for (const name of names.filter((name) => symbols.has(name))) {
used.add(name)
count += 1
recordUse(name, node, symbols.moduleKey)
}
}
function visit(node) {
@@ -241,6 +265,16 @@ export function createGatedCallCollector(families, ratchetName) {
changed = true
} else if (gated && !functions.has(name)) {
functions.set(name, gated)
const target = unwrap(initializer)
origins.set(
name,
target && ts.isIdentifier(target)
? origins.get(target.text)
: target &&
(ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target))
? moduleSymbols(target.expression)?.moduleKey
: undefined
)
changed = true
}
}
@@ -255,6 +289,7 @@ export function createGatedCallCollector(families, ratchetName) {
!functions.has(element.name.text)
) {
functions.set(element.name.text, name)
origins.set(element.name.text, symbols.moduleKey)
changed = true
}
}
@@ -278,17 +313,18 @@ export function createGatedCallCollector(families, ratchetName) {
}
for (const node of members) {
const name = propertyName(node)
if (!aliasSetup.has(node) && moduleSymbols(node.expression)?.has(name)) {
recordUse(name)
const symbols = aliasSetup.has(node) ? null : moduleSymbols(node.expression)
if (symbols?.has(name)) {
recordUse(name, node, symbols.moduleKey)
}
}
for (const node of identifiers) {
const name = aliasSetup.has(node) ? null : functions.get(node.text)
if (name) {
recordUse(name)
recordUse(name, node, origins.get(node.text))
}
}
return { count, symbols: [...used].sort() }
return { count, symbols: [...used].sort(), sites }
}
function adviceFor(symbols) {
@@ -0,0 +1,306 @@
import path from 'node:path'
import ts from 'typescript-api'
import { createGatedCallCollector, isValueReference } from './gated-call-use-collector.mjs'
import { unwrap } from '../module-requests/static-module-specifiers.mjs'
// Per-file call counts never see a new caller of an existing sync helper in another file; this
// marks top-level functions that reach a blocking call (directly or through other marked functions)
// and counts every reference to them, so the helper's callers are guarded too.
function moduleKeys(file) {
const key = file.replace(/\.[cm]?[jt]sx?$/, '')
return path.posix.basename(key) === 'index' ? [key, path.posix.dirname(key)] : [key]
}
function hasModifier(node, kind) {
return !!ts.getModifiers?.(node)?.some((modifier) => modifier.kind === kind)
}
function isFunctionLike(node) {
node = unwrap(node)
return !!node && (ts.isArrowFunction(node) || ts.isFunctionExpression(node))
}
/** Runtime references inside a function body: type positions and property names are not calls. Names match
* file-wide, like the direct collectors: a local or parameter reusing a helper's name is counted (never missed). */
function scanBody(node) {
const references = new Set()
const visit = (child) => {
if (ts.isTypeNode(child) && !ts.isExpressionWithTypeArguments(child)) {
return
}
if (ts.isIdentifier(child) && isValueReference(child)) {
references.add(child.text)
}
ts.forEachChild(child, visit)
}
ts.forEachChild(node, visit)
return { references }
}
/** Top-level functions with their ranges, runtime references, export names and re-exports. */
function scanDeclarations(file, contents) {
const source = ts.createSourceFile(file, contents, ts.ScriptTarget.Latest, true)
const functions = []
const exportNames = new Map()
const reexports = []
const imports = new Map()
const explicitExports = new Set()
const exportAs = (local, exported) =>
exportNames.set(local, [...(exportNames.get(local) ?? []), exported])
const targetModule = (specifier) =>
path.posix
.normalize(path.posix.join(path.posix.dirname(file), specifier))
.replace(/\.[cm]?[jt]sx?$/, '')
const reserveBinding = (name) => {
if (ts.isIdentifier(name)) {
explicitExports.add(name.text)
} else {
for (const element of name.elements) {
if (ts.isBindingElement(element)) {
reserveBinding(element.name)
}
}
}
}
const addFunction = (name, node) => {
functions.push({ name, start: node.getStart(source), end: node.getEnd(), ...scanBody(node) })
}
for (const statement of source.statements) {
const exported = hasModifier(statement, ts.SyntaxKind.ExportKeyword)
const isDefault = hasModifier(statement, ts.SyntaxKind.DefaultKeyword)
if (
exported &&
!ts.isTypeAliasDeclaration(statement) &&
!ts.isInterfaceDeclaration(statement) &&
statement.name &&
ts.isIdentifier(statement.name)
) {
explicitExports.add(isDefault ? 'default' : statement.name.text)
}
if (
ts.isImportDeclaration(statement) &&
ts.isStringLiteral(statement.moduleSpecifier) &&
statement.moduleSpecifier.text.startsWith('.') &&
statement.importClause &&
!statement.importClause.isTypeOnly
) {
const target = targetModule(statement.moduleSpecifier.text)
const clause = statement.importClause
if (clause.name) {
imports.set(clause.name.text, { target, name: 'default' })
}
if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
for (const element of clause.namedBindings.elements) {
if (!element.isTypeOnly) {
imports.set(element.name.text, {
target,
name: (element.propertyName ?? element.name).text
})
}
}
}
}
if (ts.isFunctionDeclaration(statement) && statement.body) {
const name = statement.name?.text ?? 'default'
addFunction(name, statement)
if (exported) {
exportAs(name, isDefault ? 'default' : name)
}
} else if (ts.isVariableStatement(statement)) {
for (const declaration of statement.declarationList.declarations) {
if (exported) {
reserveBinding(declaration.name)
}
if (ts.isIdentifier(declaration.name) && isFunctionLike(declaration.initializer)) {
addFunction(declaration.name.text, declaration)
if (exported) {
exportAs(declaration.name.text, declaration.name.text)
}
}
}
} else if (ts.isExportAssignment(statement) && !statement.isExportEquals) {
const target = unwrap(statement.expression)
if (target && ts.isIdentifier(target)) {
exportAs(target.text, 'default')
} else if (isFunctionLike(target)) {
addFunction('default', statement)
exportAs('default', 'default')
}
} else if (
ts.isExportDeclaration(statement) &&
!statement.isTypeOnly &&
statement.exportClause &&
ts.isNamedExports(statement.exportClause) &&
!statement.moduleSpecifier
) {
for (const element of statement.exportClause.elements) {
if (!element.isTypeOnly) {
exportAs((element.propertyName ?? element.name).text, element.name.text)
}
}
} else if (
ts.isExportDeclaration(statement) &&
!statement.isTypeOnly &&
statement.moduleSpecifier &&
ts.isStringLiteral(statement.moduleSpecifier) &&
statement.moduleSpecifier.text.startsWith('.')
) {
const target = targetModule(statement.moduleSpecifier.text)
const names =
statement.exportClause && ts.isNamedExports(statement.exportClause)
? statement.exportClause.elements
.filter((element) => !element.isTypeOnly)
.map((element) => [(element.propertyName ?? element.name).text, element.name.text])
: null
if (statement.exportClause && ts.isNamespaceExport(statement.exportClause)) {
explicitExports.add(statement.exportClause.name.text)
} else {
reexports.push({ target, names })
for (const [, name] of names ?? []) {
explicitExports.add(name)
}
}
}
}
for (const [local, exported] of exportNames) {
for (const name of exported) {
explicitExports.add(name)
}
const imported = imports.get(local)
if (imported) {
reexports.push({
target: imported.target,
names: exported.map((name) => [imported.name, name])
})
}
}
return { functions, exportNames, reexports, explicitExports }
}
/**
* `direct`: file -> start offsets of blocking calls, with the call each one reaches. Returns file -> helper
* references counted and the helpers used (each with the blocking call it reaches).
*/
export function collectBlockingHelperUses(sources, direct, { depth = Infinity } = {}) {
const scans = new Map()
const scan = (file) => {
if (!scans.has(file)) {
scans.set(file, scanDeclarations(file, sources.get(file)))
}
return scans.get(file)
}
// file -> helper name -> description of the blocking call it reaches.
const helpers = new Map()
const markSites = (file, sites) => {
const { functions } = scan(file)
const marked = helpers.get(file) ?? new Map()
let added = false
for (const { position, reaches } of sites) {
const owner = functions.find((fn) => position >= fn.start && position < fn.end)
if (owner && !marked.has(owner.name)) {
marked.set(owner.name, reaches)
added = true
}
}
// A function calling a marked function in its own file reaches the same blocking call.
for (let changed = true; changed;) {
changed = false
for (const fn of functions) {
if (marked.has(fn.name)) {
continue
}
const via = [...fn.references].find((name) => marked.has(name))
if (via) {
marked.set(fn.name, marked.get(via))
changed = added = true
}
}
}
if (marked.size > 0) {
helpers.set(file, marked)
}
return added
}
for (const [file, sites] of direct) {
if (sources.has(file)) {
markSites(file, sites)
}
}
const barrels = [...sources.keys()].filter((file) => scan(file).reexports.length > 0)
for (let round = 0; ; round++) {
// module key -> exported name -> what it reaches
const reachesByModule = new Map()
for (const [file, marked] of helpers) {
const { exportNames } = scan(file)
const names = new Map()
for (const [local, reaches] of marked) {
for (const exported of exportNames.get(local) ?? []) {
names.set(exported, reaches)
}
}
for (const key of moduleKeys(file)) {
reachesByModule.set(key, names)
}
}
// Re-exports add no call depth, so barrels (and barrels of barrels) resolve fully every round.
for (let changed = true; changed;) {
changed = false
for (const file of barrels) {
const own = reachesByModule.get(moduleKeys(file)[0]) ?? new Map()
const { reexports, explicitExports } = scan(file)
for (const { target, names } of reexports) {
const reached = reachesByModule.get(target)
const pairs = names ?? [...(reached?.keys() ?? [])].map((name) => [name, name])
for (const [from, to] of pairs) {
if (!names && (from === 'default' || explicitExports.has(to))) {
continue
}
if (reached?.has(from) && !own.has(to)) {
own.set(to, reached.get(from))
changed = true
}
}
}
if (own.size > 0) {
for (const key of moduleKeys(file)) {
reachesByModule.set(key, own)
}
}
}
}
const families = [...reachesByModule].map(([key, names]) => ({
modules: [key],
advice: Object.fromEntries(names)
}))
for (const [file, marked] of helpers) {
families.push({
modules: [moduleKeys(file)[0]],
advice: {},
localAdvice: Object.fromEntries(marked)
})
}
const collector = createGatedCallCollector(families, 'main blocking helper')
const uses = new Map()
let grew = false
for (const [file, contents] of sources) {
const { count, sites } = collector.collectUses(file, contents)
if (count === 0) {
continue
}
const reached = sites.map(({ name, position, module }) => ({
position,
name,
reaches: reachesByModule.get(module)?.get(name) ?? helpers.get(file)?.get(name) ?? name
}))
uses.set(file, {
count,
reaches: [...new Set(reached.map(({ name, reaches }) => `${name} (${reaches})`))].sort()
})
grew = markSites(file, reached) || grew
}
if (!grew || round + 1 >= depth) {
return { uses, helpers }
}
}
}
@@ -0,0 +1,243 @@
import { build } from 'esbuild'
import { existsSync, readFileSync } from 'node:fs'
import path from 'node:path'
import ts from 'typescript-api'
import { createWorkspaceSourceResolver } from '../../workspace/source-exports/workspace-source-exports.mjs'
import { listTrackedFiles, readTrackedSources } from '../ratchet-baseline/ratchet-baseline.mjs'
import { unwrap } from '../module-requests/static-module-specifiers.mjs'
import {
isMainBlockingSource,
MAIN_BLOCKING_WORKER_ENTRIES
} from './main-blocking-source-paths.mjs'
const EXTERNAL = [
'electron',
'node-pty',
'@parcel/watcher',
'better-sqlite3',
'keytar',
'fsevents',
'cpu-features'
]
const externalNativeAddons = {
name: 'external-native-addons',
setup(pluginBuild) {
pluginBuild.onResolve({ filter: /\.node$|\?[\w&]+$/ }, (args) => ({
path: args.path,
external: true
}))
}
}
/** Repo-relative file -> repo-relative files it imports, for every scanned source in one bundle pass. */
export async function collectImportGraph(root, files) {
const workspace = createWorkspaceSourceResolver(root)
const result = await build({
stdin: {
contents: files
.map(
(file, index) => `export * as m${index} from ${JSON.stringify(path.resolve(root, file))}`
)
.join('\n'),
resolveDir: root,
loader: 'ts',
sourcefile: 'main-blocking-import-graph-entry.ts'
},
bundle: true,
write: false,
outdir: path.join(root, 'main-blocking-import-graph-metafile-only'),
platform: 'node',
target: 'node20',
format: 'esm',
external: EXTERNAL,
packages: 'external',
metafile: true,
absWorkingDir: root,
logLevel: 'silent',
plugins: [
externalNativeAddons,
{
name: 'main-blocking-workspace-sources',
setup(pluginBuild) {
pluginBuild.onResolve({ filter: /^@orca\// }, ({ path: specifier }) => {
const source = workspace.resolve(specifier)
return source ? { path: source.path } : undefined
})
}
}
]
})
const relative = (file) => path.relative(root, path.resolve(root, file)).split(path.sep).join('/')
const graph = new Map()
for (const [file, info] of Object.entries(result.metafile.inputs)) {
graph.set(
relative(file),
(info.imports ?? []).filter((edge) => !edge.external).map((edge) => relative(edge.path))
)
}
return graph
}
// esbuild does not follow `createRequire(...)('./x')`; without the edge a main-loaded module could look worker-only.
const RESOLVE_EXTENSIONS = ['.ts', '.tsx', '.mts', '.cts', '.js', '.mjs', '.cjs']
function createRequireTargets(file, contents, sources) {
const source = ts.createSourceFile(file, contents, ts.ScriptTarget.Latest, true)
const loaders = new Set()
const targets = []
const isCreateRequire = (node) =>
ts.isCallExpression(node) &&
ts.isIdentifier(node.expression) &&
node.expression.text === 'createRequire'
const visit = (node) => {
if (
ts.isVariableDeclaration(node) &&
ts.isIdentifier(node.name) &&
node.initializer &&
isCreateRequire(node.initializer)
) {
loaders.add(node.name.text)
}
if (
ts.isCallExpression(node) &&
(isCreateRequire(node.expression) ||
(ts.isIdentifier(node.expression) && loaders.has(node.expression.text))) &&
node.arguments[0] &&
ts.isStringLiteralLike(node.arguments[0]) &&
node.arguments[0].text.startsWith('.')
) {
const base = path.posix.normalize(
path.posix.join(path.posix.dirname(file), node.arguments[0].text)
)
const resolved = [
base,
...RESOLVE_EXTENSIONS.map((ext) => `${base}${ext}`),
...RESOLVE_EXTENSIONS.map((ext) => `${base}/index${ext}`)
].find((candidate) => sources.has(candidate))
if (resolved) {
targets.push(resolved)
}
}
ts.forEachChild(node, visit)
}
visit(source)
return targets
}
/** Electron main, CLI, orcad and preload entries: guarded even when a worker happens to import one. */
export function eventLoopEntryFiles(root) {
// Fixtures lack build config; a renamed main entry must not disable root validation in the real repo.
const realRepo =
listTrackedFiles(root, ['config/build-plugins/main-build-entry-points.ts']).length > 0
const read = (file) => {
try {
return readFileSync(path.join(root, file), 'utf8')
} catch {
return ''
}
}
const builtSource = read('config/build-plugins/main-build-entry-points.ts')
const built = [...builtSource.matchAll(/resolve\(\s*(['"])([^'"]+)\1\s*\)/g)].map(
(match) => match[2]
)
const cliSource = ts.createSourceFile(
'cli-main-entry-names.ts',
read('config/build-plugins/cli-main-entry-names.ts'),
ts.ScriptTarget.Latest,
true
)
const cliList = unwrap(
cliSource.statements
.filter(ts.isVariableStatement)
.flatMap((statement) => [...statement.declarationList.declarations])
.find(
(declaration) =>
ts.isIdentifier(declaration.name) && declaration.name.text === 'CLI_MAIN_ENTRY_NAMES'
)?.initializer
)
const validCli =
cliSource.parseDiagnostics.length === 0 &&
cliList &&
ts.isArrayLiteralExpression(cliList) &&
cliList.elements.every(ts.isStringLiteral)
const cli = validCli ? cliList.elements.map((element) => `src/main/${element.text}.ts`) : []
const preload = listTrackedFiles(root, ['src/preload']).filter(
(file) => file.split('/').length === 3 && isMainBlockingSource(file)
)
const entries = [...built, ...cli, 'src/main/index.ts', 'src/main/orcad/main.ts', ...preload]
if (realRepo) {
const tracked = new Set(listTrackedFiles(root, entries))
const missing = entries.filter(
(file) => !tracked.has(file) || !existsSync(path.join(root, file))
)
// Every non-template resolve() in the entry list must be a literal we read, or a root went missing.
const resolveCalls = (builtSource.match(/resolve\(\s*(?!`)/g) ?? []).length
if (
!built.includes('src/main/index.ts') ||
built.length !== resolveCalls ||
!validCli ||
cli.length === 0 ||
missing.length > 0
) {
throw new Error(
`main-blocking-import-graph: cannot read the event-loop entries from config/build-plugins (main ${built.length}, CLI ${cli.length}, missing: ${missing.join(', ') || 'none'}); update eventLoopEntryFiles`
)
}
}
return entries.filter((file) => !Object.hasOwn(MAIN_BLOCKING_WORKER_ENTRIES, file))
}
/** Files imported only beneath worker/utility entries; anything an event-loop file or entry imports stays guarded. */
export function workerOnlyFiles(graph, files, eventLoopEntries = []) {
const entries = new Set(Object.keys(MAIN_BLOCKING_WORKER_ENTRIES))
const underWorker = new Set()
const walk = (start, seen) => {
const stack = [start]
while (stack.length > 0) {
const file = stack.pop()
if (seen.has(file)) {
continue
}
seen.add(file)
stack.push(...(graph.get(file) ?? []))
}
}
for (const entry of entries) {
walk(entry, underWorker)
}
const guarded = new Set()
for (const entry of eventLoopEntries) {
walk(entry, guarded)
}
for (const file of files) {
if (!underWorker.has(file)) {
walk(file, guarded)
}
}
return new Set(files.filter((file) => underWorker.has(file) && !guarded.has(file)))
}
/** Tracked event-loop sources under `pathspecs`: main-blocking sources minus worker-only modules. */
export async function readEventLoopSources(root, pathspecs) {
const sources = readTrackedSources(
root,
['src/main', 'src/shared', 'src/preload'],
isMainBlockingSource
)
// Worker entries themselves are not main-blocking sources, but the graph must start from them.
const entries = new Set(listTrackedFiles(root, Object.keys(MAIN_BLOCKING_WORKER_ENTRIES)))
const graph = await collectImportGraph(root, [...sources.keys(), ...entries])
for (const [file, contents] of sources) {
if (contents.includes('createRequire')) {
graph.set(file, [
...(graph.get(file) ?? []),
...createRequireTargets(file, contents, sources)
])
}
}
const workerOnly = workerOnlyFiles(graph, [...sources.keys()], eventLoopEntryFiles(root))
const inPathspecs = (file) =>
pathspecs.some((spec) => file === spec || file.startsWith(`${spec}/`))
return new Map([...sources].filter(([file]) => inPathspecs(file) && !workerOnly.has(file)))
}
@@ -1,10 +1,11 @@
import { existsSync, readFileSync } from 'node:fs'
import { isTestOnlySourcePath } from './test-only-source-path.mjs'
// Exact entry files only: dependencies remain guarded, even when a worker imports them.
// Entry files are exempt here; main-blocking-import-graph.mjs also exempts modules only these entries import.
const entries = JSON.parse(
readFileSync(new URL('../../../main-blocking-worker-entries.json', import.meta.url), 'utf8')
)
export const MAIN_BLOCKING_WORKER_ENTRIES = entries
for (const [file, reason] of Object.entries(entries)) {
if (
!file.startsWith('src/main/') ||
@@ -1,12 +1,28 @@
import ts from 'typescript-api'
import { propertyName, unwrap } from '../module-requests/static-module-specifiers.mjs'
const METHODS = new Set(['prepare', 'run', 'get', 'all', 'iterate', 'exec'])
// pragma() and transaction() run SQL too: a durability pragma or BEGIN/COMMIT blocks like any statement.
const TRANSACTION_MODES = new Set(['immediate', 'deferred', 'exclusive'])
const METHODS = new Set([
'prepare',
'run',
'get',
'all',
'iterate',
'exec',
'pragma',
'transaction'
])
const SQLITE_MODULE =
/^(?:node:sqlite|better-sqlite3)$|(?:^|\/)(?:sync-database|sqlite-statement)(?:\.[cm]?[jt]s)?$/
// Local syntax only: imported SQLite types, typed receivers, constructors and prepare() results.
export function countSqliteCalls(file, contents) {
return collectSqliteCallSites(file, contents).length
}
// Local syntax only: imported SQLite types, typed receivers, constructors and prepare() results.
/** Start offsets of each synchronous SQLite call. */
export function collectSqliteCallSites(file, contents) {
const source = ts.createSourceFile(file, contents, ts.ScriptTarget.Latest, true)
if (source.parseDiagnostics.length) {
throw new Error(`Cannot parse ${file}; SQLite ratchet must not skip it.`)
@@ -131,9 +147,32 @@ export function countSqliteCalls(file, contents) {
}
return false
}
// `const insertMany = db.transaction(fn)`: each insertMany() call runs BEGIN/COMMIT; its result is not a database.
const transactionCalls = new Set()
const transactionWrapper = (node) => {
node = unwrap(node)
return (
!!node &&
ts.isCallExpression(node) &&
(ts.isPropertyAccessExpression(node.expression) ||
ts.isElementAccessExpression(node.expression)) &&
propertyName(node.expression) === 'transaction' &&
instance(node.expression.expression)
)
}
for (let changed = true; changed;) {
changed = false
for (const node of declarations) {
if (
ts.isVariableDeclaration(node) &&
ts.isIdentifier(node.name) &&
!transactionCalls.has(node.name.text) &&
transactionWrapper(node.initializer)
) {
transactionCalls.add(node.name.text)
changed = true
continue
}
if (!ts.isIdentifier(node.name) || !(sqliteType(node.type) || instance(node.initializer))) {
continue
}
@@ -149,18 +188,31 @@ export function countSqliteCalls(file, contents) {
}
}
}
return calls.filter((node) => {
const target = unwrap(node.expression)
if (ts.isNewExpression(node)) {
return constructor(target)
}
if (callableConstructors.has(key(target))) {
return true
}
return (
(ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) &&
METHODS.has(propertyName(target)) &&
instance(target.expression)
)
}).length
return calls
.filter((node) => {
const target = unwrap(node.expression)
if (ts.isNewExpression(node)) {
return constructor(target)
}
if (
callableConstructors.has(key(target)) ||
transactionCalls.has(key(target)) ||
transactionWrapper(target)
) {
return true
}
if (
(ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) &&
TRANSACTION_MODES.has(propertyName(target)) &&
transactionCalls.has(key(target.expression))
) {
return true
}
return (
(ts.isPropertyAccessExpression(target) || ts.isElementAccessExpression(target)) &&
METHODS.has(propertyName(target)) &&
instance(target.expression)
)
})
.map((node) => node.getStart(source))
}
@@ -155,17 +155,53 @@ export function totalCount(counts) {
return [...counts.values()].reduce((sum, count) => sum + count, 0)
}
/** Lowers baseline rows to `current` and keeps their notes; growth still has to be fixed in code. */
/** Files renamed since the change's base (ORCA_CODE_QUALITY_BASE, else the merge base with origin/main). */
function renamedSinceBase(root) {
try {
const base =
process.env.ORCA_CODE_QUALITY_BASE ||
execFileSync('git', ['merge-base', 'HEAD', 'origin/main'], {
cwd: root,
encoding: 'utf8'
}).trim()
const fields = execFileSync(
'git',
['diff', '-M', '--name-status', '-z', '--diff-filter=R', base],
{
cwd: root,
encoding: 'utf8'
}
)
.split('\0')
.filter(Boolean)
const renames = []
for (let index = 0; index + 2 < fields.length; index += 3) {
renames.push([fields[index + 1], fields[index + 2]])
}
return renames
} catch {
return []
}
}
/** Lowers baseline rows to `current` and keeps their notes; a renamed file keeps its row. Growth still needs a code fix. */
export function pruneCountBaseline(root, baselinePath, header, current) {
const file = path.join(root, baselinePath)
const text = fs.existsSync(file) ? fs.readFileSync(file, 'utf8') : ''
const baseline = parseCountBaseline(text)
const notes = parseCountNotes(text)
for (const [from, to] of renamedSinceBase(root)) {
if (baseline.has(from) && !baseline.has(to) && !current.get(from)) {
baseline.set(to, baseline.get(from))
if (notes.has(from)) {
notes.set(to, notes.get(from))
}
}
}
const pruned = new Map(
[...parseCountBaseline(text)].map(([rel, allowed]) => [
rel,
Math.min(allowed, current.get(rel) ?? 0)
])
[...baseline].map(([rel, allowed]) => [rel, Math.min(allowed, current.get(rel) ?? 0)])
)
fs.writeFileSync(file, formatCountBaseline(pruned, header, parseCountNotes(text)))
fs.writeFileSync(file, formatCountBaseline(pruned, header, notes))
return totalCount(pruned)
}
@@ -185,10 +221,18 @@ export function runCountRatchet(ratchet, root, arg) {
const keep = (counts) => (inScope ? new Map([...counts].filter(([key]) => inScope(key))) : counts)
const { grown, shrunk } = diffCounts(keep(current), keep(baseline))
for (const { file, now, allowed } of grown) {
console.error(`${file}: ${now} ${ratchet.unit}, baseline allows ${allowed}.`)
const detail = ratchet.detail?.(file)
console.error(
`${file}: ${now} ${ratchet.unit}, baseline allows ${allowed}.${detail ? ` ${detail}` : ''}`
)
}
if (grown.length > 0) {
console.error(ratchet.fix.join('\n'))
if (grown.some(({ allowed }) => allowed === 0) && shrunk.length > 0) {
console.error(
`A moved or renamed file keeps its allowance: ${ratchet.pruneCommand ?? `pnpm check:${ratchet.name}-ratchet --prune`} carries its row to the new path.`
)
}
}
for (const { file, now, allowed } of shrunk) {
console.error(`${file}: now ${now}, baseline ${allowed}.`)
@@ -5,7 +5,8 @@ import { createGatedCallCollector } from '../../process-boundaries/gated-call-us
import { countSqliteCalls } from '../../process-boundaries/sqlite-call-use-collector.mjs'
import { isMainBlockingSource } from '../../process-boundaries/main-blocking-source-paths.mjs'
import { propertyName } from '../../module-requests/static-module-specifiers.mjs'
import { readTrackedSources, runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
import { runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
import { readEventLoopSources } from '../../process-boundaries/main-blocking-import-graph.mjs'
export const OFF_MAIN_ADVICE =
'Move CPU or SQL work to a worker, utility process or the backend; async is right only for real I/O waits. Use asynchronous requests and replies for IPC.'
@@ -102,9 +103,9 @@ export function countBlockingApis(sources) {
return counts
}
export function main(root = process.cwd(), arg = undefined) {
export async function main(root = process.cwd(), arg = undefined) {
const counts = countBlockingApis(
readTrackedSources(root, ['src/main', 'src/shared', 'src/preload'], isMainBlockingSource)
await readEventLoopSources(root, ['src/main', 'src/shared', 'src/preload'])
)
let status = 0
for (const [category, current] of counts) {
@@ -114,7 +115,7 @@ export function main(root = process.cwd(), arg = undefined) {
baselinePath: `config/main-blocking-${category}-baseline.txt`,
header: [
`# Legacy synchronous ${category} uses per file; counts may only go DOWN.`,
'# Only explicit worker/utility entry files are exempt; their imports remain guarded.'
'# Worker/utility entries and modules only they import are exempt; anything event-loop code imports stays guarded.'
],
collect: () => current,
pruneCommand:
@@ -131,5 +132,5 @@ export function main(root = process.cwd(), arg = undefined) {
}
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
process.exitCode = main(process.cwd(), process.argv[2])
process.exitCode = await main(process.cwd(), process.argv[2])
}
@@ -6,6 +6,9 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
import { main as fsMain } from './check-main-sync-fs-ratchet.mjs'
import '../../process-boundaries/check-main-sync-spawn-ratchet.mjs'
import { countBlockingApis, main } from './check-main-blocking-api-ratchet.mjs'
import { collectDirectBlockingSites } from './check-main-blocking-helper-ratchet.mjs'
import { collectBlockingHelperUses } from '../../process-boundaries/main-blocking-helper-propagation.mjs'
import { workerOnlyFiles } from '../../process-boundaries/main-blocking-import-graph.mjs'
const file = 'src/main/consumer.ts'
const counts = (source, name = file) =>
@@ -24,17 +27,17 @@ afterEach(() => {
})
describe('main blocking API ratchets', () => {
it('guards typed SQL receivers without charging Map.get or async backup', () => {
it('guards typed SQL receivers and pragmas without charging Map.get or async backup', () => {
expect(
counts(`import type Database from '../sqlite/sync-database'
class Owner {
db: Database.Database | null
query() { this.db.prepare('select').get(); this.db.backup('copy') }
query() { this.db.prepare('select').get(); this.db.backup('copy'); this.db.pragma('synchronous = FULL') }
}
function query(db: Database.Database, statement: Database.Statement, cache: Map<string, Database.Database>) {
db.exec('schema'); statement.run(); cache.get('key')
}`)
).toEqual({ compression: 0, crypto: 0, atomics: 0, sqlite: 4, ipc: 0 })
).toEqual({ compression: 0, crypto: 0, atomics: 0, sqlite: 5, ipc: 0 })
})
it('guards constructor properties and namespace SQLite types', () => {
@@ -59,7 +62,7 @@ describe('main blocking API ratchets', () => {
).toEqual({ compression: 0, crypto: 0, atomics: 0, sqlite: 0, ipc: 0 })
})
it('rejects growth and shrinkage; prune cannot raise a baseline', () => {
it('rejects growth and shrinkage; prune cannot raise a baseline', async () => {
const root = mkdtempSync(path.join(tmpdir(), 'orca-blocking-ratchet-'))
roots.push(root)
mkdirSync(path.join(root, 'src/main'), { recursive: true })
@@ -81,20 +84,80 @@ describe('main blocking API ratchets', () => {
execFileSync('git', ['add', '.'], { cwd: root })
vi.spyOn(console, 'error').mockImplementation(() => {})
vi.spyOn(console, 'log').mockImplementation(() => {})
expect(fsMain(root)).toBe(0)
expect(await fsMain(root)).toBe(0)
writeFileSync(
daemon,
"import { statSync } from 'node:fs'; statSync('file'); statSync('another')"
)
expect(fsMain(root)).toBe(1)
expect(main(root)).toBe(1)
main(root, '--prune')
expect(await fsMain(root)).toBe(1)
expect(await main(root)).toBe(1)
await main(root, '--prune')
expect(readFileSync(cryptoFile, 'utf8')).not.toContain('1 src/')
writeFileSync(cryptoFile, '1 src/main/consumer.ts\n')
expect(main(root)).toBe(0)
expect(await main(root)).toBe(0)
writeFileSync(path.join(root, file), '')
expect(main(root)).toBe(1)
main(root, '--prune')
expect(main(root)).toBe(0)
expect(await main(root)).toBe(1)
await main(root, '--prune')
expect(await main(root)).toBe(0)
})
it('counts callers of a sync helper in another file, not only the helper itself', () => {
const sources = new Map([
[
'src/main/config-read.ts',
`import { readFileSync } from 'node:fs'
function readRaw(file: string) { return readFileSync(file, 'utf8') }
export const readConfig = (file: string) => JSON.parse(readRaw(file))
export function configPath() { return '/tmp/config.json' }`
],
[
'src/main/poller.ts',
`import { readConfig, configPath } from './config-read'
setInterval(() => readConfig(configPath()), 1000)`
]
])
const { uses } = collectBlockingHelperUses(sources, collectDirectBlockingSites(sources), {
depth: 1
})
expect(uses.get('src/main/poller.ts')?.count).toBe(1)
})
it('counts callers through locally exported imported helpers', () => {
const sources = new Map([
[
'src/main/impl.ts',
`import { readFileSync } from 'node:fs'
export function readConfig() { return readFileSync('config') }
export default function readDefault() { return readFileSync('default') }`
],
[
'src/main/barrel.ts',
`import readDefault, { readConfig as read } from './impl'
export { read as load, readDefault as default }`
],
[
'src/main/consumer.ts',
`import readDefault, { load } from './barrel'
load(); readDefault()`
]
])
const { uses } = collectBlockingHelperUses(sources, collectDirectBlockingSites(sources), {
depth: 1
})
expect(uses.get('src/main/consumer.ts')?.count).toBe(2)
})
it('exempts modules only worker entries import', () => {
const entry = 'src/main/native-chat/agent-session-journal/journal-sql-worker-entry.ts'
const graph = new Map([
[entry, ['src/main/worker-only.ts', 'src/main/shared-store.ts']],
['src/main/index.ts', ['src/main/shared-store.ts']]
])
const files = ['src/main/index.ts', 'src/main/worker-only.ts', 'src/main/shared-store.ts']
expect([...workerOnlyFiles(graph, files)]).toEqual(['src/main/worker-only.ts'])
// An event-loop entry a worker imports stays guarded, and so does everything it imports.
graph.get(entry).push('src/main/index.ts')
graph.get('src/main/index.ts').push('src/main/worker-only.ts')
expect([...workerOnlyFiles(graph, files, ['src/main/index.ts'])]).toEqual([])
})
})
@@ -0,0 +1,76 @@
import path from 'node:path'
import { pathToFileURL } from 'node:url'
import { createGatedCallCollector } from '../../process-boundaries/gated-call-use-collector.mjs'
import { collectSqliteCallSites } from '../../process-boundaries/sqlite-call-use-collector.mjs'
import { readEventLoopSources } from '../../process-boundaries/main-blocking-import-graph.mjs'
import { collectBlockingHelperUses } from '../../process-boundaries/main-blocking-helper-propagation.mjs'
import { runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
import { OFF_MAIN_ADVICE } from './check-main-blocking-api-ratchet.mjs'
const BASELINE_PATH = 'config/main-blocking-helper-baseline.txt'
// Two levels: a timer or handler calling a function that calls the sync reader (the 11-09 and 11-13 regressions).
const HELPER_DEPTH = 2
const BLOCKING_FAMILIES = [
{ modules: ['fs', 'node:fs', 'original-fs', 'graceful-fs'], exportPattern: /Sync$/, advice: {} },
{ modules: ['child_process', 'node:child_process'], exportPattern: /Sync$/, advice: {} }
]
const direct = createGatedCallCollector(BLOCKING_FAMILIES, 'main blocking helper')
export function collectDirectBlockingSites(sources) {
const sites = new Map()
for (const [file, contents] of sources) {
const found = [
...direct.collectUses(file, contents).sites.map(({ name, position }) => ({
position,
reaches: `${name} in ${file}`
})),
...collectSqliteCallSites(file, contents).map((position) => ({
position,
reaches: `SQLite in ${file}`
}))
]
if (found.length > 0) {
sites.set(file, found)
}
}
return sites
}
export async function collectMainBlockingHelperUses(root, depth) {
const sources = await readEventLoopSources(root, ['src/main', 'src/shared', 'src/preload'])
return collectBlockingHelperUses(sources, collectDirectBlockingSites(sources), { depth }).uses
}
export async function main(root = process.cwd(), arg = undefined) {
const uses = await collectMainBlockingHelperUses(root, HELPER_DEPTH)
const counts = new Map([...uses].map(([file, { count }]) => [file, count]))
return runCountRatchet(
{
name: 'main-blocking-helper',
baselinePath: BASELINE_PATH,
header: [
'# References to functions that make a synchronous fs, child_process or SQLite call, or call such a',
'# function, per file, in event-loop code (Electron main, orcad, daemon, preload; worker-only modules excluded).',
'# This is a RATCHET: counts may only go DOWN.',
'# Prune: node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-blocking-helper-ratchet.mjs --prune'
],
collect: () => counts,
detail: (file) => `Uses: ${uses.get(file)?.reaches.join(', ')}.`,
pruneCommand:
'node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-blocking-helper-ratchet.mjs --prune',
unit: 'blocking helper reference(s)',
fix: [
`Each listed helper makes a synchronous fs, child_process or SQLite call, or calls one that does. ${OFF_MAIN_ADVICE}`,
'If a helper itself just became blocking, fix it there: every file that calls it is charged.',
"Names match file-wide: a local or parameter that reuses an imported helper's name is counted; rename it.",
`A one-shot startup or shutdown call may raise the file's row in ${BASELINE_PATH} with reviewer sign-off and a trailing "# why" note.`
]
},
root,
arg
)
}
if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
process.exitCode = await main(process.cwd(), process.argv[2])
}
@@ -1,9 +1,8 @@
import process from 'node:process'
import { pathToFileURL } from 'node:url'
import { createGatedCallCollector } from '../../process-boundaries/gated-call-use-collector.mjs'
import { readTrackedSources, runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
import { isMainBlockingSource } from '../../process-boundaries/main-blocking-source-paths.mjs'
import { isTestOnlySourcePath } from '../../process-boundaries/test-only-source-path.mjs'
import { runCountRatchet } from '../../ratchet-baseline/ratchet-baseline.mjs'
import { readEventLoopSources } from '../../process-boundaries/main-blocking-import-graph.mjs'
// Sync fs on Electron main stalls every window (and in the daemon/orcad, every terminal); per-spawn/RPC/focus stat and read sweeps were a recurring lag source (#39805, #35967, #38481).
@@ -69,22 +68,13 @@ const collector = createGatedCallCollector(
'main sync-fs'
)
function isScannedPath(rel) {
return (
isMainBlockingSource(rel) &&
/\.[cm]?[jt]sx?$/.test(rel) &&
!rel.endsWith('.d.ts') &&
!isTestOnlySourcePath(rel)
)
}
export function countSyncFsCalls(rel, source) {
return collector.collectUses(rel, source).count
}
export function collectMainSyncFsCounts(root = process.cwd()) {
export async function collectMainSyncFsCounts(root = process.cwd()) {
const counts = new Map()
for (const [rel, source] of readTrackedSources(root, SCAN_ROOTS, isScannedPath)) {
for (const [rel, source] of await readEventLoopSources(root, SCAN_ROOTS)) {
const count = countSyncFsCalls(rel, source)
if (count > 0) {
counts.set(rel, count)
@@ -93,18 +83,20 @@ export function collectMainSyncFsCounts(root = process.cwd()) {
return counts
}
export function main(root = process.cwd(), arg = undefined) {
export async function main(root = process.cwd(), arg = undefined) {
const counts = await collectMainSyncFsCounts(root)
return runCountRatchet(
{
name: 'main-sync-fs',
baselinePath: BASELINE_PATH,
header: [
'# Synchronous node:fs calls (every *Sync export) in production src/main and src/shared, per file.',
'# Synchronous node:fs calls (every *Sync export) in production src/main and src/shared, per file;',
'# modules imported only by worker/utility entries are excluded.',
'# Startup-only or one-shot uses are fine to keep; per-RPC, per-spawn, per-focus or per-poll uses are the target.',
'# This is a RATCHET: counts may only go DOWN.',
'# Prune after removing calls: pnpm check:main-sync-fs-ratchet --prune'
],
collect: collectMainSyncFsCounts,
collect: () => counts,
unit: 'sync fs call(s)',
fix: [
`Sync fs blocks the thread it runs on: Electron main (every window) or the daemon/orcad loop (every terminal). ${ADVICE}.`,
@@ -117,5 +109,5 @@ export function main(root = process.cwd(), arg = undefined) {
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
process.exit(main(process.cwd(), process.argv[2]))
process.exitCode = await main(process.cwd(), process.argv[2])
}
+1
View File
@@ -218,6 +218,7 @@
"check:process-host-imports": "node config/scripts/static-analysis/process-boundaries/check-process-host-imports.mjs",
"check:main-sync-spawn-ratchet": "node config/scripts/static-analysis/process-boundaries/check-main-sync-spawn-ratchet.mjs",
"check:main-sync-fs-ratchet": "node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-sync-fs-ratchet.mjs",
"check:main-blocking-helper-ratchet": "node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-main-blocking-helper-ratchet.mjs",
"check:recurring-timer-ratchet": "node config/scripts/static-analysis/ratchets/runtime-lifecycle/check-recurring-timer-ratchet.mjs",
"check:compat-boundary-imports": "node config/scripts/static-analysis/process-boundaries/check-compat-boundary-imports.mjs",
"check:import-boundaries": "bun config/scripts/static-analysis/process-boundaries/check-import-boundaries.mjs"