Files
software-mansion__argent/scripts/e2e-full/phases/00-install.sh
filip131311 b232114422 docs: audit every comment in src against the code it describes (#931)
Audits every comment in `src/` and `scripts/` against the code it
describes.

**462 files, 57 commits, net −8,194 lines.** Comment text only — the
whole branch is code-identical to `main`.

## Method

One subagent per file, strictly sequential. Scope was `src/` +
`scripts/` (459 files); three more files were added at the end because
they carried dead references of the same kind — two test headers citing
design docs that do not exist, and `publish-npm.yml` citing a retired
workflow. Each agent verified every comment — line, block, JSDoc, file
header, trailing — against the surrounding code and the rest of the
repo, following identifiers, paths, tool ids, config keys, env vars and
issue links to see whether they still exist and still behave as
described. Rules:

- **A false or misleading comment is deleted, not reworded.** If a claim
could not be confirmed by reading the source, it went. That is why the
deletion count is so much larger than the rewrite count.
- Survivors are cut to the shortest form carrying something the code
does not already say. Restatement, preamble, hedging, changelog prose
and ASCII banners are gone; the non-obvious *why* stays.
- Preserved byte-identical: license headers, pragmas and directives
(`@ts-*`, `eslint-disable`, shebangs, `/// <reference>`), JSDoc tag
tokens, everything inside a string or template literal, and the sole
comment inside an otherwise empty block (ESLint `no-empty` counts a
comment-bearing block as non-empty).

## Verification

Every file passed two independent gates before being recorded as done:

1. `comments-only` — the required check.
2. A second comment-stripping comparator with a proper mode stack,
written for this pass because `comments-only`'s flat scanner desyncs on
nested template literals and quote-bearing regex literals and then
reports comment lines as code changes. Two files hit that false FAIL
(`utils/android-profiler/pipeline/index.ts`,
`scripts/extract-tools.mjs`); in both the "changed code" it printed was
literally `//` lines, and the second checker confirmed the code was
byte-identical.

After the last file, all 462 changed files were re-checked against
`main` with the same comparator, rather than trusting any agent's
self-report. **459 code-identical; 2 are non-code (`.svg`, `.md`); 1
intentional.**

The intentional one is `packages/argent/scripts/bundle-tools.cjs`: the
changed template literal *is* the comment header of the file it
generates, `packages/native-devtools-android/src/bundled-meta.ts`.
Fixing only the generated file would have been reverted by the next
build, so the generator changed too — and it has been verified to
reproduce the committed generated file byte-for-byte.

## Representative false claims removed

Not wording nits — statements a reader would have acted on:

- **Reversed directions.** `proxyStart`'s JSDoc had the tunnel backwards
(it is a reverse tunnel: the host binds first and the simulator dials
in). A `paste()` doc had the pasteboard copy direction reversed.
- **Contradicted by the code below it.** A timeout budget multiplied by
three where the probes run concurrently — the same comment said so six
lines later. A "warn once" that warns on every call. A "binary search"
that is a linear scan.
- **Named things that do not exist.** A `vega-fast-cli` binary, a
`finish-recording.ts`, a `publish-next.yml` workflow, two
`profiler-react19-*.md` design docs, a `DebuggerTarget.ts`, a commit
hash git does not know, two tool ids, an `ensureEnv` cycle.
- **Wrong by construction.** "Welford accumulators" across four files
where the code keeps naive `n`/`sum`/`sumSq`; `sum`/`sumSq` documented
over `actualDuration` when reduce sums `selfDuration`; a strict-mode
halving written `n/2` where the code ceils; field docs listing enum
values the producers never emit.
- **Guarantees the code does not make.** A validation matrix claiming to
cover "EVERY tool" that skips flagless ones; a Pareto cutoff that
`slice(0, 20)` makes inert; an idempotence claim where the real rule is
at-or-ahead; a capability note describing a clean 400 the shape-based
device resolver can never produce.
- **Unverifiable assertions** about prebuilt binaries, external CLIs and
the cloud SDK — deleted rather than kept as folklore, since nothing in
the repo can confirm them.
- **Stale numbers**: invented Android tool versions, hard-coded tool
counts and description lengths that had drifted.

## Review

A Fable agent reviewed both halves adversarially for over-deletion,
misread code, `no-empty` hazards and byte-identity violations.
Second-half verdict: **SHIP**, with two one-line restores, both applied
in the final commit — the `npm view ""` rationale behind a blank-token
guard, and the note that `argent-mcp` keeps a copy of
`SECRET_PLACEHOLDER_MARKER` it cannot import.

## Code issues surfaced but deliberately not fixed

This pass changes comments only. Eight genuine findings are logged for a
follow-up:

1. `telemetry/src/consent.ts` — a non-ENOENT read error returns null and
falls through to the default-on path, so file errors *can* silently flip
telemetry on.
2. `chromium-server/navigation.ts` — `navigate()` is reachable from
`POST /api/navigate` with only a `typeof === "string"` check; open-url's
schema is a bare `z.string()`, so the "already validated by zod" premise
never held.
3. `http.ts` — `constantTimeEqual` returns early on a length mismatch,
so the auth token's length is observable.
4. `describe/index.ts:~114` — the ios-remote branch passes `{ isTvOs:
false }` unconditionally, so a remote tvOS simulator takes the iOS
ax-service path, though `isRemoteTvOsSimulator` exists and shake/paste
do use it.
5. `devices/boot-device.ts` — `-crash-report-mode never` is passed
unconditionally *and* appended again by the feature-detecting path, so
every emulator spawn passes it twice.
6. `react-profiler/pipeline/04-rank.ts` — `PARETO_THRESHOLD_PCT` is
dead: `slice(0, 20)` always wins.
7. `reaped-sessions.ts` — a user-facing hint string tells the agent that
`react-profiler-start { force: true }` disposes the debugger and
profiler session; it does not. Left byte-identical because it is a
string literal, not a comment.
8. `utils/simctl-backend.ts` — `localSimctl` is exported with no
importers anywhere.

## Docs

No documentation change is needed: this pass touches only source
comments, and no user-facing capability, tool, CLI flag, config key or
flow-file behaviour changed.

---------

Co-authored-by: filip131311 <f.kaminski2000@gmail.com>
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
2026-08-24 12:16:20 +02:00

165 lines
7.5 KiB
Bash

#!/usr/bin/env bash
# Phase 0 — install assertions for the tgz.
#
# run-e2e.sh already ran the primary `npm install -g <tgz>` into the sandbox
# prefix; that install is what ARGENT_BIN drives and what this phase checks.
# Find a workspace config file that registers the argent MCP server. Which
# editor adapters run depends on which editors are detected, so match any known
# config file rather than pinning one path.
# The default pattern is the server key, not the package name: a global-mode
# init writes the MCP command as plain `argent`.
_argent_mcp_in_ws() { # ws [grep-pattern]
local pat="${2:-\"argent\"}"
grep -rl "$pat" "$1" \
--include='*.json' --include='*.jsonc' --include='*.toml' --include='*.yaml' 2>/dev/null \
| grep -v -e '/node_modules/' -e 'skills-lock.json' -e 'package-lock.json' -e 'package.json' \
| head -1
}
_pkg_dir() {
local d="$E2E_PREFIX/lib/node_modules/@swmansion/argent"
[ -d "$d" ] && { printf '%s\n' "$d"; return; }
find "$E2E_PREFIX" -maxdepth 4 -type d -name argent -path '*@swmansion*' 2>/dev/null | head -1
}
run_phase() {
local P=install
local pkg; pkg="$(_pkg_dir)"
if argent_cli --version && [ "$CLI_OUT" = "$TGZ_VERSION" ]; then
pass "$P" npm-global version "argent v$CLI_OUT on PATH"
else
fail "$P" npm-global version "got '$CLI_OUT' want '$TGZ_VERSION' (install broken?)"
fi
if [ -n "$pkg" ] && [ -d "$pkg" ]; then
pass "$P" npm-global package-dir "$pkg"
else
fail "$P" npm-global package-dir "installed package dir not found under $E2E_PREFIX"
return 0
fi
local plat="linux"
case "$E2E_OS" in darwin) plat="darwin";; esac
# arm64 linux ships in its own dir.
local simsrv=""
for cand in "$pkg/bin/$plat/simulator-server" "$pkg/bin/${plat}-arm64/simulator-server"; do
[ -f "$cand" ] && simsrv="$cand" && break
done
if [ -n "$simsrv" ] && [ -x "$simsrv" ]; then
pass "$P" bundle simulator-server "$(basename "$(dirname "$simsrv")")"
else
fail "$P" bundle simulator-server "missing/non-executable: $simsrv"
fi
# trace-processor assets (profiler) always shipped
[ -d "$pkg/assets/trace-processor" ] && pass "$P" bundle trace-processor || fail "$P" bundle trace-processor "assets/trace-processor missing"
if [ "$E2E_OS" = "darwin" ]; then
ls "$pkg"/dylibs/*.dylib >/dev/null 2>&1 && pass "$P" bundle dylibs || fail "$P" bundle dylibs "no dylibs in package"
else
skip "$P" bundle dylibs "macOS-only"
fi
# The postinstall was dropped in #510 and its jobs moved to runtime, because
# installs passing --ignore-scripts skip it silently. Pin the absence so it
# cannot creep back in.
# Parse the manifest first: `jq -e` exits non-zero for an unreadable file just
# as it does for an absent key, so an install missing its package.json would
# otherwise report "no hook" — an absence check passing because it could not
# look.
if ! jq -e . "$pkg/package.json" >/dev/null 2>&1; then
fail "$P" postinstall no-hook "package.json missing or unparseable at $pkg"
elif [ -f "$pkg/scripts/postinstall.cjs" ] || jq -e '.scripts.postinstall' "$pkg/package.json" >/dev/null 2>&1; then
fail "$P" postinstall no-hook "package ships a postinstall hook again (dropped in #510)"
else
pass "$P" postinstall no-hook
fi
local gws="$E2E_WORK/ws/global"
mkdir -p "$gws"; ( cd "$gws" && git init -q >/dev/null 2>&1 || true )
printf '{"name":"e2e-global-probe","private":true}\n' > "$gws/package.json"
pushd "$gws" >/dev/null
if argent_cli init --yes --global --no-telemetry --from "$E2E_TGZ"; then
pass "$P" init-global exit0
else
fail "$P" init-global exit0 "$(printf '%s' "$CLI_OUT" | tail -3 | tr '\n' ' ')"
fi
popd >/dev/null
local gcfg; gcfg="$(_argent_mcp_in_ws "$gws")"
if [ -n "$gcfg" ]; then
pass "$P" init-global mcp-config "$(basename "$(dirname "$gcfg")")/$(basename "$gcfg")"
else
fail "$P" init-global mcp-config "no argent MCP config written under $gws"
fi
[ -f "$gws/skills-lock.json" ] && pass "$P" init-global skills-lock || skip "$P" init-global skills-lock "no skills-lock.json"
[ -f "$E2E_HOME/.argent/config.json" ] && pass "$P" init-global home-config || skip "$P" init-global home-config "no ~/.argent/config.json"
local lws="$E2E_WORK/ws/local"
mkdir -p "$lws"
printf '{"name":"e2e-local-probe","private":true,"version":"0.0.0"}\n' > "$lws/package.json"
pushd "$lws" >/dev/null
if argent_cli init --yes --local --no-telemetry --from "$E2E_TGZ"; then
pass "$P" init-local exit0
else
fail "$P" init-local exit0 "$(printf '%s' "$CLI_OUT" | tail -3 | tr '\n' ' ')"
fi
popd >/dev/null
if [ -d "$lws/node_modules/@swmansion/argent" ]; then
pass "$P" init-local devDependency
else
fail "$P" init-local devDependency "package not in $lws/node_modules"
fi
if [ -f "$lws/.argent/install.json" ] && [ "$(jq -r '.mode' "$lws/.argent/install.json" 2>/dev/null)" = "local" ]; then
pass "$P" init-local install-record "mode=local"
else
fail "$P" init-local install-record "no local .argent/install.json"
fi
local lcfg; lcfg="$(_argent_mcp_in_ws "$lws" 'node_modules/@swmansion/argent')"
if [ -n "$lcfg" ]; then
pass "$P" init-local mcp-config "$(basename "$(dirname "$lcfg")")/$(basename "$lcfg") -> node_modules path"
else
# fall back: yarn-PnP and npx modes write no node_modules path.
lcfg="$(_argent_mcp_in_ws "$lws")"
[ -n "$lcfg" ] && pass "$P" init-local mcp-config "$(basename "$lcfg")" || fail "$P" init-local mcp-config "no local argent MCP config under $lws"
fi
# Before the uninstall tests, while the driver is still installed.
pushd "$lws" >/dev/null
if argent_cli update --yes; then
pass "$P" update ran "completed (rc=0)"
else
skip "$P" update ran "non-zero (likely offline/registry): $(printf '%s' "$CLI_OUT" | head -1)"
fi
popd >/dev/null
# Safe first: this removes the devDependency and workspace config, never the
# global driver the rest of the run depends on.
pushd "$lws" >/dev/null
if argent_cli uninstall --yes --local; then pass "$P" uninstall-local exit0; else skip "$P" uninstall-local exit0 "$(printf '%s' "$CLI_OUT" | tail -2 | tr '\n' ' ')"; fi
popd >/dev/null
if [ ! -d "$lws/node_modules/@swmansion/argent" ] || [ ! -f "$lws/.argent/install.json" ]; then
pass "$P" uninstall-local config-removed
else
fail "$P" uninstall-local config-removed "local install still present under $lws"
fi
pushd "$gws" >/dev/null
if argent_cli uninstall --yes --global; then pass "$P" uninstall-global exit0; else skip "$P" uninstall-global exit0 "$(printf '%s' "$CLI_OUT" | tail -2 | tr '\n' ' ')"; fi
popd >/dev/null
local gcfg2; gcfg2="$(_argent_mcp_in_ws "$gws")"
if [ -z "$gcfg2" ]; then pass "$P" uninstall-global config-removed; else fail "$P" uninstall-global config-removed "argent MCP config remains: $gcfg2"; fi
# uninstall --global removed the sandbox bin ARGENT_BIN points at.
if [ ! -x "${ARGENT_BIN%% *}" ]; then
log "restoring driver after uninstall test"
# Put back exactly what run-e2e.sh installed — same prefix, same
# optional-dep policy. Hardcoding --omit=optional drops electron on a full
# run and the chromium tier then skips itself as "electron not installed";
# hardcoding the sandbox prefix under --system leaves the machine's real
# global argent missing.
# shellcheck disable=SC2086
npm install -g "$E2E_TGZ" ${E2E_NPM_PREFIX_ARGS:-} ${E2E_NPM_OMIT:-} >/dev/null 2>&1 || true
fi
if argent_cli --version >/dev/null 2>&1; then pass "$P" driver-restored ok; else fail "$P" driver-restored ok "argent not runnable after restore"; fi
}