Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
591b910e31 | ||
|
|
9ffc6210a4 | ||
|
|
b973b1b1ec | ||
|
|
47947eb01c | ||
|
|
2d99e1e3b2 | ||
|
|
5d6eeb22fb | ||
|
|
e964a06b83 | ||
|
|
5aa30b8b86 | ||
|
|
8c7569aca7 | ||
|
|
539a0f95b5 | ||
|
|
c73cf0ab76 | ||
|
|
aa7008f8a5 | ||
|
|
1887e1120e | ||
|
|
ca7ef69c0c | ||
|
|
b9c439831d | ||
|
|
bace2c5a4f | ||
|
|
3cd80cbb88 | ||
|
|
6cd5ea0fb2 | ||
|
|
706bba6e13 | ||
|
|
9964af6b79 | ||
|
|
3059d8a40f | ||
|
|
86b223b33e | ||
|
|
92741187ec | ||
|
|
5fdb0636b4 | ||
|
|
72b3209f3a | ||
|
|
2309cebb7b |
@@ -31,7 +31,7 @@ When tools are absent or registration is stale:
|
||||
`npx -y rea-agents@latest doctor --client codex --json`. Substitute the current
|
||||
supported client: `claude_code`, `claude_desktop`, `codex`, `cursor`,
|
||||
`gemini_cli`, `windsurf`, `devin`, `opencode`, `antigravity`, `copilot_cli`,
|
||||
`commandcode`, `vscode`, `grok_build`, `omp`, or `grok_bot`. `grok_bot` has no local
|
||||
`commandcode`, `qwen_code`, `vscode`, `grok_build`, `omp`, `pi`, `hermes`, or `grok_bot`. `grok_bot` has no local
|
||||
file registration: doctor reports the Grok Bot chat step, and setup does not
|
||||
write `mcp.json`. If the client is unknown, use `doctor --json` and
|
||||
inspect its registration results before choosing a setup scope.
|
||||
|
||||
@@ -35,9 +35,5 @@ jobs:
|
||||
sudo apt-get update
|
||||
sudo apt-get install --no-install-recommends -y libcairo2 fonts-dejavu-core
|
||||
python3 -m pip install -r website/requirements.txt
|
||||
- name: Prepare website assets
|
||||
run: python3 scripts/prepare-website.py
|
||||
- name: Check website links, metadata and publishing configuration
|
||||
run: python3 scripts/verify-website.py
|
||||
- name: Check sitemap discovery and metadata regressions
|
||||
run: python3 scripts/test-website.py
|
||||
- name: Check shared HTML, links, assets and contributor workflows
|
||||
run: python3 scripts/website.py check
|
||||
|
||||
@@ -59,10 +59,8 @@ jobs:
|
||||
sudo apt-get update
|
||||
sudo apt-get install --no-install-recommends -y libcairo2 fonts-dejavu-core
|
||||
python3 -m pip install -r website/requirements.txt
|
||||
- name: Prepare website assets
|
||||
run: python3 scripts/prepare-website.py
|
||||
- name: Check website links, metadata and publishing configuration
|
||||
run: python3 scripts/verify-website.py
|
||||
- name: Check shared HTML, links, assets and contributor workflows
|
||||
run: python3 scripts/website.py check
|
||||
- name: Record the published commit
|
||||
run: |
|
||||
python3 - <<'PY'
|
||||
|
||||
@@ -208,10 +208,53 @@ Windows, `~/.hermes` elsewhere — including any `HERMES_DATA_DIR_SUFFIX`. Herme
|
||||
connects an entry unless `enabled` is false, so setup states `enabled: true`.
|
||||
|
||||
Hermes personal skills install under the active Hermes home's `skills` directory.
|
||||
Setup, doctor and uninstall follow the root's `active_profile` selection, as
|
||||
plain Hermes CLI commands do. An explicit `HERMES_HOME` pointing to
|
||||
`profiles/<name>` selects that named profile directly. An invalid, missing or
|
||||
deleted sticky profile is reported instead of writing into the default home;
|
||||
repair the profile or run `hermes profile use default` before retrying.
|
||||
REA follows `HERMES_HOME` whitespace trimming, environment-variable expansion,
|
||||
and home expansion before resolving that profile. Setup previews the resolved
|
||||
configuration and skill destinations; doctor and uninstall use those same paths.
|
||||
|
||||
### DeepSeek Harness
|
||||
|
||||
DeepSeek Harness uses a Cordis YAML patch sequence rather than a `mcpServers`
|
||||
object. REA's `setup --client` does not edit this format. For Harness
|
||||
`0.2.0-rc.2`, append the following entry to `$DSH_HOME/cordis.patch.yml`
|
||||
(`~/.dsh/cordis.patch.yml` when `DSH_HOME` is unset). Preserve existing patches
|
||||
and replace the executable paths with absolute paths from your installation:
|
||||
|
||||
```yaml
|
||||
- insert:
|
||||
- id: rea-mcp
|
||||
name: "@deepseek-ai/dsh-mcp-client"
|
||||
config:
|
||||
serverName: rea
|
||||
transport: stdio
|
||||
command: /absolute/path/to/node
|
||||
args: ["/absolute/path/to/rea/scripts/rea.mjs", mcp]
|
||||
cwd: !!js process.cwd()
|
||||
```
|
||||
|
||||
For a global npm installation, the launcher is under
|
||||
`$(npm root -g)/rea-agents/scripts/rea.mjs`. Check the Node executable with
|
||||
`command -v node`. Register `serverName: rea` only once in each active profile,
|
||||
then restart Harness. It exposes tools as `mcp__rea__<tool_name>`.
|
||||
Run `rea setup --skill --dry-run`, review the destination, then
|
||||
`rea setup --skill --yes` to install the workflow in `~/.agents/skills`.
|
||||
Harness discovers that directory, or `$DSH_AGENTS_HOME/skills` when configured;
|
||||
its native `skill` tool can load `reverse-engineer-anything`.
|
||||
|
||||
REA's optional [native client verification](testing.md#end-to-end-integration-and-golden-evidence)
|
||||
checks headless chat, skill loading, all tool input schemas and actual analysis
|
||||
using the installed Harness and a local model fixture. This establishes the
|
||||
Harness integration, with live DeepSeek API compatibility remaining unverified.
|
||||
See the [Harness MCP guide](https://github.com/deepseek-ai/deepseek-harness/blob/639ed015397290b3745d163aafe02ffee4aa3f84/packages/mcp/mcp-client/README.md)
|
||||
for its native configuration contract.
|
||||
|
||||
### Other client settings
|
||||
|
||||
For OpenCode, setup writes the V1 `mcp.rea` entry, which OpenCode V1 and V2
|
||||
both load. If the configuration already uses OpenCode V2's native
|
||||
`mcp.servers` table, setup registers REA there instead and replaces any earlier
|
||||
|
||||
@@ -144,6 +144,12 @@ if retention is unavailable or fails, the diagnostic reports that reason.
|
||||
REA accepts ordinary `tools/call` progress tokens. Updates are monotonic,
|
||||
rate-bounded to at most one intermediate update per 100 ms, and always allow a
|
||||
terminal update. Unknown totals are omitted; REA does not fabricate percentages.
|
||||
`capture_process_scenario` uses that boundary only when the client supplies a
|
||||
progress token. Notifications set `progress` to the count of collected terminal
|
||||
frames, process samples, and interaction events, omit `total`, and put the
|
||||
lifecycle phase, elapsed time, and final cleanup status in `message`. A client
|
||||
that does not send a progress token receives no progress notifications. The
|
||||
tool result is unchanged either way.
|
||||
Provider calls receive the request cancellation signal. Artifact traversal,
|
||||
hashing, version comparisons, Hopper requests, and process capture
|
||||
check the same signal. Cancellation is distinct from timeout. A cleanup failure
|
||||
|
||||
@@ -51,6 +51,34 @@ format is TOON. The file contains the complete capture Evidence record.
|
||||
Choose an output file distinct from the scenario input: shell redirection opens
|
||||
and truncates the output before REA reads the scenario.
|
||||
|
||||
While the capture runs, REA writes live status to stderr as one JSON object per
|
||||
line. Stdout stays the final Evidence document:
|
||||
|
||||
```json
|
||||
{
|
||||
"rea_progress": {
|
||||
"phase": "running",
|
||||
"completed": 3,
|
||||
"total": null,
|
||||
"message": "elapsed_ms=1200 frames=1 samples=2 interactions=0",
|
||||
"sequence": 4
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
`phase` is the observed lifecycle stage: `prepare`, `running`, `settling`, or
|
||||
`cleanup`. `completed` counts collected terminal frames, process samples, and
|
||||
interaction events. `total` stays null; REA does not invent a unit total or a
|
||||
percentage. `message` reports elapsed time and those counts. The final line uses
|
||||
`phase` `cleanup`, sets `terminal` to true, and adds `disposition` (`exited`,
|
||||
`timeout`, `idle_timeout`, `cancelled`, or `failed`) plus the owned-process,
|
||||
renderer, and temporary-root cleanup states. Updates use the shared progress
|
||||
boundary and are limited to one intermediate line per 100 ms; the terminal line
|
||||
is always emitted. If a receiver is slow, intermediate observations are merged
|
||||
into the latest status, and stale live observations are discarded before final
|
||||
cleanup status. Progress never copies child output. Child output remains in the
|
||||
capture Evidence on stdout.
|
||||
|
||||
For example:
|
||||
|
||||
```json
|
||||
|
||||
@@ -102,6 +102,64 @@ cleanup. These POSIX lanes use a deterministic loopback model, so they do not
|
||||
prove live model-provider or native Windows compatibility. Qwen and Pi use
|
||||
caller-configured skill directories to isolate the fixture account from the OS
|
||||
home; this does not prove their default home-directory discovery.
|
||||
Set `REA_VERIFY_HERMES_STICKY_PROFILE=1` to exercise native Hermes selection of
|
||||
a named sticky profile with `HERMES_HOME` still pointing to its root.
|
||||
|
||||
`verify:gemini-client` requires an installed Gemini CLI (verified with
|
||||
`@google/gemini-cli@0.63.0`); select it with `REA_VERIFY_GEMINI_COMMAND`.
|
||||
The optional POSIX lane uses native `GEMINI_CLI_HOME` discovery in an isolated
|
||||
Git project, checks setup plans, backups and idempotence, activates the installed
|
||||
personal skill, validates all forwarded input JSON Schemas against their declared
|
||||
dialect, forwards the complete REA catalog and checks full JavaScript
|
||||
Evidence for a Unicode path. Use `-- chat` for ordinary chat with REA enabled,
|
||||
or `REA_VERIFY_RUNTIME_ROOT` for a production-only installed REA package.
|
||||
The local fixture exercises the real Gemini API adapter, including its
|
||||
`untrusted_context` tool-result envelope. Token counts are synthetic; live
|
||||
Google API and native Windows compatibility remain unverified. The lane disables
|
||||
the client's memory-based relaunch to preserve the caller's Node heap budget.
|
||||
|
||||
`verify:opencode-client` requires an installed OpenCode (verified with
|
||||
`opencode-ai@1.18.35`); select it with `REA_VERIFY_OPENCODE_COMMAND`.
|
||||
The optional POSIX lane configures isolated XDG roots and `OPENCODE_CONFIG_DIR`,
|
||||
checks setup plans, backups, preserved JSONC comments and idempotence, activates
|
||||
the installed skill, validates all forwarded input schemas and verifies complete
|
||||
JavaScript Evidence for a Unicode path. JSONC is the default fixture; set
|
||||
`REA_VERIFY_OPENCODE_CONFIG_FORMAT=json` for JSON. Use `-- chat` for ordinary
|
||||
chat or `REA_VERIFY_RUNTIME_ROOT` for a production-only installed package.
|
||||
The native core runs with external plugins disabled through `OPENCODE_PURE`;
|
||||
the local OpenAI-compatible fixture has a caller-declared one-million-token
|
||||
context and synthetic usage. Skills use an explicit isolated `skills.paths`
|
||||
directory, so default OS-home discovery remains unverified. Live model APIs and
|
||||
native Windows are also unverified.
|
||||
|
||||
`verify:claude-client` requires installed Claude Code (verified with
|
||||
`@anthropic-ai/claude-code@2.1.296`); select it with `REA_VERIFY_CLAUDE_COMMAND`.
|
||||
The optional POSIX lane uses native `CLAUDE_CONFIG_DIR` discovery, an independent
|
||||
Git workspace, user settings and default built-in tools. It preserves caller
|
||||
preferences and backups, checks idempotent setup, waits through the native
|
||||
`WaitForMcpServers` tool when discovery is pending, and validates the complete
|
||||
catalog and forwarded input schemas. Call mode loads the personal skill through
|
||||
native `Skill`, checks its full body and verifies named-schema JavaScript Evidence
|
||||
for a Unicode path. Use `-- chat` for ordinary chat with REA enabled, or
|
||||
`REA_VERIFY_RUNTIME_ROOT` for a production-only installed package. The local
|
||||
Anthropic Messages/SSE fixture preserves native resource-hint envelopes in its
|
||||
request artifacts. Usage is synthetic; live Anthropic API, native Windows and
|
||||
bare-mode personal-skill activation remain unverified by this lane.
|
||||
|
||||
`verify:deepseek-client` requires an installed DeepSeek Harness (`dsh`;
|
||||
verified with `@deepseek-ai/dsh@0.2.0-rc.2`) and Git. Set
|
||||
`REA_VERIFY_DEEPSEEK_COMMAND` to select its executable. This optional POSIX lane
|
||||
installs the skill through `rea setup --skill`, writes the native Cordis MCP
|
||||
patch into an isolated `DSH_HOME`, and uses `DSH_AGENTS_HOME` for native personal
|
||||
skill discovery. A separate Git root prevents inherited project skills from
|
||||
masking a missing installation. The default `call` mode checks skill loading,
|
||||
complete catalog discovery, the actual forwarded input schemas and regexes,
|
||||
and full JavaScript Evidence for a Unicode path. Use `-- chat` for ordinary
|
||||
chat with REA enabled, or `REA_VERIFY_RUNTIME_ROOT` for an installed package.
|
||||
The fixture uses Harness's custom OpenAI adapter and the one-million-token
|
||||
context capacity declared by its default DeepSeek Flash model; it does not
|
||||
establish live DeepSeek API or native Windows coverage. Receipts include
|
||||
request artifacts, result digests and owned-process lineage.
|
||||
|
||||
Full E2E tests invoke the production command dispatcher and real providers,
|
||||
without fake launchers, runners or responses. `verify:keyed-archive` writes an
|
||||
|
||||
@@ -180,8 +180,12 @@
|
||||
"verify:package": "npm run build:cached && node scripts/verify-package.mjs",
|
||||
"verify:package:windows": "npm run build:cached && node scripts/verify-windows-package.mjs",
|
||||
"verify:qwen-client": "npm run build:cached && node scripts/verify-qwen-client.mjs",
|
||||
"verify:gemini-client": "npm run build:cached && node scripts/verify-gemini-client.mjs",
|
||||
"verify:opencode-client": "npm run build:cached && node scripts/verify-opencode-client.mjs",
|
||||
"verify:claude-client": "npm run build:cached && node scripts/verify-claude-client.mjs",
|
||||
"verify:pi-client": "npm run build:cached && node scripts/verify-native-agent-client.mjs pi",
|
||||
"verify:hermes-client": "npm run build:cached && node scripts/verify-native-agent-client.mjs hermes",
|
||||
"verify:deepseek-client": "npm run build:cached && node scripts/verify-deepseek-client.mjs",
|
||||
"probe:windows-capabilities": "npm run build:cached && node scripts/windows-capabilities.mjs",
|
||||
"verify:published": "node scripts/verify-published-package.mjs",
|
||||
"config:print": "node scripts/print-mcp-config.mjs",
|
||||
|
||||
@@ -0,0 +1,135 @@
|
||||
"""Optionally audit external website links; network failures stay distinct from missing targets."""
|
||||
|
||||
import argparse
|
||||
from concurrent.futures import ThreadPoolExecutor
|
||||
from functools import lru_cache
|
||||
from html.parser import HTMLParser
|
||||
import json
|
||||
from pathlib import Path
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
from urllib.error import HTTPError, URLError
|
||||
from urllib.parse import quote, unquote, urlsplit
|
||||
from urllib.request import Request, urlopen
|
||||
|
||||
from website import authored_markdown
|
||||
|
||||
|
||||
@lru_cache(maxsize=None)
|
||||
def github_api(endpoint):
|
||||
"""Read GitHub evidence through the caller's gh installation and authentication."""
|
||||
result = subprocess.run(["gh", "api", endpoint], capture_output=True, text=True, timeout=20)
|
||||
if result.returncode:
|
||||
raise ValueError(result.stderr.strip())
|
||||
return json.loads(result.stdout)
|
||||
|
||||
|
||||
def github_target(url):
|
||||
"""Resolve repository URLs, including branch names containing slashes."""
|
||||
parts = [unquote(part) for part in url.path.strip("/").split("/")]
|
||||
if len(parts) < 2:
|
||||
return None
|
||||
repo = f"repos/{parts[0]}/{parts[1]}"
|
||||
if url.hostname == "raw.githubusercontent.com" and len(parts) >= 4:
|
||||
return f"{repo}/contents/{'/'.join(parts[3:])}?ref={quote(parts[2], safe='')}"
|
||||
if len(parts) == 2:
|
||||
return repo
|
||||
kind = parts[2]
|
||||
if kind in ("blob", "tree") and len(parts) >= 4:
|
||||
ref = parts[3]
|
||||
# GitHub uses the longest matching branch name before the source path.
|
||||
if not re.fullmatch(r"[0-9a-f]{40}", ref):
|
||||
references = github_api(f"{repo}/git/matching-refs/heads/{quote(ref, safe='')}")
|
||||
references += github_api(f"{repo}/git/matching-refs/tags/{quote(ref, safe='')}")
|
||||
suffix = "/".join(parts[3:])
|
||||
matches = [item["ref"].split("/", 2)[2] for item in references]
|
||||
matches = [name for name in matches if suffix == name or suffix.startswith(name + "/")]
|
||||
if matches:
|
||||
ref = max(matches, key=len)
|
||||
path = "/".join(parts[3:])[len(ref):].lstrip("/")
|
||||
return f"{repo}/contents/{quote(path, safe='/')}?ref={quote(ref, safe='')}"
|
||||
if kind in ("issues", "pull") and len(parts) == 4 and parts[3].isdigit():
|
||||
return f"{repo}/{'pulls' if kind == 'pull' else 'issues'}/{parts[3]}"
|
||||
if kind == "commit" and len(parts) == 4:
|
||||
return f"{repo}/commits/{parts[3]}"
|
||||
if kind == "releases" and len(parts) >= 5 and parts[3] in ("tag", "download"):
|
||||
return f"{repo}/releases/tags/{quote(parts[4], safe='')}"
|
||||
return None
|
||||
|
||||
|
||||
def audit_url(item):
|
||||
"""Classify confirmed missing links separately from blocked or unsupported probes."""
|
||||
value, sources = item
|
||||
result = {"url": value, "sources": sorted(set(sources))}
|
||||
url = urlsplit(value)
|
||||
try:
|
||||
if url.hostname in ("github.com", "raw.githubusercontent.com"):
|
||||
endpoint = github_target(url)
|
||||
if endpoint is None:
|
||||
return dict(result, status="unknown", reason="GitHub UI route; check in a browser")
|
||||
data = github_api(endpoint)
|
||||
parts = url.path.strip("/").split("/")
|
||||
if len(parts) >= 6 and parts[2:4] == ["releases", "download"]:
|
||||
if unquote(parts[5]) not in [asset["name"] for asset in data.get("assets", [])]:
|
||||
return dict(result, status="broken", reason="Release asset is missing")
|
||||
return dict(result, status="ok", via="gh api", endpoint=endpoint)
|
||||
request = Request(value.split("#", 1)[0], headers={
|
||||
"User-Agent": "REA-Website-Verifier/1.0 (+https://github.com/morluto/rea)",
|
||||
})
|
||||
with urlopen(request, timeout=15) as response:
|
||||
return dict(result, status="ok", http_status=response.status, final_url=response.url)
|
||||
except HTTPError as error:
|
||||
return dict(result, status="broken" if error.code in (404, 410) else "unknown", reason=str(error))
|
||||
except ValueError as error:
|
||||
return dict(result, status="broken" if "HTTP 404" in str(error) else "unknown", reason=str(error))
|
||||
except (OSError, URLError, TimeoutError, subprocess.TimeoutExpired) as error:
|
||||
return dict(result, status="unknown", reason=str(error))
|
||||
|
||||
|
||||
def external_links(root):
|
||||
"""Discover authored external links, excluding locally checked site and preview URLs."""
|
||||
references = {}
|
||||
|
||||
def add(value, source):
|
||||
url = urlsplit(value)
|
||||
if url.scheme in ("http", "https") and url.hostname not in ("rea.tools", "localhost", "127.0.0.1", "::1"):
|
||||
references.setdefault(value, []).append(str(source.relative_to(root)))
|
||||
|
||||
class Links(HTMLParser):
|
||||
def handle_starttag(self, tag, attrs):
|
||||
for key, value in attrs:
|
||||
if key in ("href", "src") and value:
|
||||
add(value, path)
|
||||
|
||||
for path in sorted((root / "website/public").rglob("*.html")):
|
||||
Links().feed(path.read_text(encoding="utf-8"))
|
||||
for path in authored_markdown(root):
|
||||
for value in re.findall(r"(?:\]\(|<)(https?://[^\s<>\)]+)", path.read_text(encoding="utf-8")):
|
||||
add(value, path)
|
||||
return references
|
||||
|
||||
|
||||
def main():
|
||||
"""Run an explicit network audit without making PR checks depend on third-party uptime."""
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--report", type=Path, help="Write the complete JSON report outside public assets")
|
||||
args = parser.parse_args()
|
||||
root = Path(__file__).resolve().parent.parent
|
||||
with ThreadPoolExecutor(max_workers=4) as pool:
|
||||
results = list(pool.map(audit_url, external_links(root).items()))
|
||||
if args.report:
|
||||
if args.report.resolve().is_relative_to(root / "website/public"):
|
||||
parser.error("Keep audit reports outside website/public.")
|
||||
args.report.write_text(json.dumps(results, indent=2) + "\n", encoding="utf-8")
|
||||
counts = {status: sum(item["status"] == status for item in results) for status in ("ok", "broken", "unknown")}
|
||||
print(f"External links: {counts['ok']} reachable, {counts['broken']} missing, {counts['unknown']} need manual verification.")
|
||||
print("GitHub checks establish target existence; external fragment IDs are not checked.")
|
||||
for item in results:
|
||||
if item["status"] != "ok":
|
||||
print(f"{item['status']}: {item['url']} — {item['reason']}")
|
||||
return 1 if counts["broken"] else 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -16,6 +16,9 @@ import { verifyGhidraBoundaries } from "./real-ghidra-boundaries.mjs";
|
||||
const defaultEntrypoint = fileURLToPath(new URL("../rea.mjs", import.meta.url));
|
||||
const environment = () => ({
|
||||
PATH: process.env.PATH ?? "/usr/bin:/bin",
|
||||
...(process.env.NODE_OPTIONS === undefined
|
||||
? {}
|
||||
: { NODE_OPTIONS: process.env.NODE_OPTIONS }),
|
||||
REA_LOG_LEVEL: "silent",
|
||||
REA_ANALYSIS_PROVIDER: "ghidra",
|
||||
HOPPER_LAUNCHER_PATH: "/rea-unconfigured-deep-provider/hopper",
|
||||
|
||||
@@ -40,7 +40,11 @@ export async function verifyGhidraBoundaries(
|
||||
ajv.validateSchema(tool[key]),
|
||||
`${tool.name} ${key}: ${JSON.stringify(ajv.errors)}`,
|
||||
);
|
||||
validators.set(tool.name, ajv.compile(tool.outputSchema));
|
||||
validators.set(
|
||||
tool.name,
|
||||
(tool.outputSchema?.$id && ajv.getSchema(tool.outputSchema.$id)) ||
|
||||
ajv.compile(tool.outputSchema),
|
||||
);
|
||||
}
|
||||
let successfulCalls = 0;
|
||||
let rejectedCalls = 0;
|
||||
|
||||
@@ -42,7 +42,11 @@ export async function verifyHopperBoundaryContracts(
|
||||
ajv.validateSchema(tool.outputSchema),
|
||||
`${tool.name} output schema`,
|
||||
);
|
||||
validators.set(tool.name, ajv.compile(tool.outputSchema));
|
||||
validators.set(
|
||||
tool.name,
|
||||
(tool.outputSchema?.$id && ajv.getSchema(tool.outputSchema.$id)) ||
|
||||
ajv.compile(tool.outputSchema),
|
||||
);
|
||||
}
|
||||
let successfulCalls = 0;
|
||||
let rejectedCalls = 0;
|
||||
|
||||
@@ -1,16 +1,14 @@
|
||||
"""Prepare downloads, the sitemap and the sharing image for the static website."""
|
||||
|
||||
from html.parser import HTMLParser
|
||||
from io import BytesIO
|
||||
from pathlib import Path
|
||||
import re
|
||||
import sys
|
||||
from urllib.parse import quote
|
||||
import xml.etree.ElementTree as ET
|
||||
from zipfile import ZIP_DEFLATED, ZipFile, ZipInfo
|
||||
|
||||
from website import PageMetadata, page_url
|
||||
|
||||
|
||||
SITE_ORIGIN = "https://rea.tools"
|
||||
EXAMPLE_FILES = (
|
||||
"package.json",
|
||||
"main.js",
|
||||
@@ -21,47 +19,20 @@ EXAMPLE_FILES = (
|
||||
)
|
||||
|
||||
|
||||
class IndexPolicy(HTMLParser):
|
||||
"""Read indexing directives from the authored HTML head."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.in_head = False
|
||||
self.noindex = False
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
if tag == "head":
|
||||
self.in_head = True
|
||||
if tag == "meta" and self.in_head:
|
||||
attributes = dict(attrs)
|
||||
if (attributes.get("name") or "").lower() in ("robots", "googlebot"):
|
||||
directives = re.split(
|
||||
r"[\s,]+", (attributes.get("content") or "").lower()
|
||||
)
|
||||
self.noindex |= bool(set(directives) & {"noindex", "none"})
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag == "head":
|
||||
self.in_head = False
|
||||
|
||||
|
||||
def prepare_sitemap(site):
|
||||
"""Discover HTML routes automatically, excluding pages marked noindex."""
|
||||
namespace = "http://www.sitemaps.org/schemas/sitemap/0.9"
|
||||
ET.register_namespace("", namespace)
|
||||
sitemap = ET.Element(f"{{{namespace}}}urlset")
|
||||
for path in sorted(site.rglob("*.html")):
|
||||
policy = IndexPolicy()
|
||||
policy = PageMetadata()
|
||||
policy.feed(path.read_text(encoding="utf-8"))
|
||||
if policy.noindex:
|
||||
continue
|
||||
route = path.relative_to(site).as_posix()
|
||||
if path.name == "index.html":
|
||||
route = route.removesuffix("index.html")
|
||||
entry = ET.SubElement(sitemap, f"{{{namespace}}}url")
|
||||
ET.SubElement(
|
||||
entry, f"{{{namespace}}}loc"
|
||||
).text = f"{SITE_ORIGIN}/{quote(route, safe='/')}"
|
||||
).text = page_url(site, path)
|
||||
ET.indent(sitemap, space=" ")
|
||||
ET.ElementTree(sitemap).write(
|
||||
site / "sitemap.xml", encoding="utf-8", xml_declaration=True
|
||||
|
||||
@@ -6,7 +6,11 @@ import io
|
||||
from pathlib import Path
|
||||
import shutil
|
||||
import tempfile
|
||||
from threading import Thread
|
||||
import unittest
|
||||
from http.server import ThreadingHTTPServer
|
||||
from urllib.error import HTTPError
|
||||
from urllib.request import urlopen
|
||||
import xml.etree.ElementTree as ET
|
||||
|
||||
|
||||
@@ -23,6 +27,7 @@ def load_script(name):
|
||||
|
||||
PREPARE = load_script("prepare-website")
|
||||
VERIFY = load_script("verify-website")
|
||||
WEBSITE = load_script("website")
|
||||
|
||||
|
||||
class WebsiteSearchChecks(unittest.TestCase):
|
||||
@@ -126,5 +131,116 @@ class WebsiteSearchChecks(unittest.TestCase):
|
||||
)
|
||||
|
||||
|
||||
class WebsiteMaintenanceChecks(unittest.TestCase):
|
||||
"""Exercise contributor edits and the static preview through real consumers."""
|
||||
|
||||
def test_shared_edits_preserve_body_and_catch_drift_before_rewriting(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
for name in ("public", "templates"):
|
||||
shutil.copytree(ROOT / "website" / name, root / "website" / name)
|
||||
page = root / "website/public/blog/touhou-reconstruction/index.html"
|
||||
original = page.read_text()
|
||||
body = original.split('<main id="main"', 1)[1].split("</main>", 1)[0]
|
||||
template = root / "website/templates/header.html.tmpl"
|
||||
template.write_text(template.read_text().replace("Reverse Engineer Anything", "REA test navigation"))
|
||||
with self.assertRaisesRegex(ValueError, "Shared HTML is stale"):
|
||||
WEBSITE.sync_pages(root, check=True)
|
||||
self.assertEqual(page.read_text(), original)
|
||||
WEBSITE.sync_pages(root)
|
||||
updated = page.read_text()
|
||||
self.assertIn("REA test navigation", updated)
|
||||
self.assertEqual(updated.split('<main id="main"', 1)[1].split("</main>", 1)[0], body)
|
||||
self.assertEqual(WEBSITE.sync_pages(root), [])
|
||||
page.write_text(updated.replace(' <!-- website:header:end -->', '', 1))
|
||||
with self.assertRaisesRegex(ValueError, "needs one header region"):
|
||||
WEBSITE.sync_pages(root)
|
||||
|
||||
def test_new_page_escapes_metadata_stays_a_draft_and_joins_sitemap_when_ready(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
for name in ("public", "templates"):
|
||||
shutil.copytree(ROOT / "website" / name, root / "website" / name)
|
||||
site = root / "website/public"
|
||||
page = WEBSITE.new_page(root, "blog/new-example", 'A <test> & "result"', 'Check "quotes" & <markup>.')
|
||||
source = page.read_text()
|
||||
self.assertIn('href="../../blog/" aria-current="page"', source)
|
||||
self.assertIn('href="../../assets/styles.css"', source)
|
||||
self.assertIn("A <test> & "result"", source)
|
||||
with self.assertRaisesRegex(ValueError, "Page already exists"):
|
||||
WEBSITE.new_page(root, "blog/new-example", "Another page", "Description")
|
||||
with self.assertRaises(ValueError):
|
||||
WEBSITE.new_page(root, "../outside", "Title", "Description")
|
||||
WEBSITE.sync_pages(root, check=True)
|
||||
PREPARE.prepare_sitemap(site)
|
||||
self.assertNotIn("https://rea.tools/blog/new-example/", (site / "sitemap.xml").read_text())
|
||||
page.write_text(source.replace(' <meta name="robots" content="noindex" />\n', ''))
|
||||
PREPARE.prepare_sitemap(site)
|
||||
self.assertIn("https://rea.tools/blog/new-example/", (site / "sitemap.xml").read_text())
|
||||
self.assertEqual(VERIFY.check_site(site)[3], [])
|
||||
|
||||
def test_links_in_prompts_fragments_and_copy_controls_are_verified(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
site = Path(directory) / "public"
|
||||
shutil.copytree(ROOT / "website/public", site)
|
||||
page = site / "faq/index.html"
|
||||
original = page.read_text()
|
||||
cases = (
|
||||
('<a href="https://rea.tools/deleted/">Broken</a>', "missing local target"),
|
||||
('<code>https://rea.tools/guides/native/#deleted</code>', "missing HTML fragment"),
|
||||
('<code>https://morluto.github.io/rea/examples/notes-web/</code>', "obsolete website URL"),
|
||||
('<button data-copy="deleted">Copy</button>', "missing copy target"),
|
||||
('<a href="https://[">Malformed</a>', "invalid URL"),
|
||||
)
|
||||
for inserted, message in cases:
|
||||
with self.subTest(message=message):
|
||||
page.write_text(original.replace("</main>", inserted + "</main>", 1))
|
||||
self.assertTrue(any(message in error for error in VERIFY.check_site(site)[3]))
|
||||
|
||||
def test_repository_links_reject_missing_files_and_old_markdown_anchors(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
root = Path(directory)
|
||||
(root / "website/public").mkdir(parents=True)
|
||||
(root / "docs").mkdir()
|
||||
(root / "docs/guide.md").write_text("# Guide\n## Set up REA\n")
|
||||
page = root / "website/README.md"
|
||||
page.write_text("[Guide](../docs/guide.md#set-up-rea)\n")
|
||||
(root / "website/.venv").mkdir()
|
||||
(root / "website/.venv/vendor.md").write_text("[File](missing.md)")
|
||||
self.assertEqual(VERIFY.check_repository_links(root), [])
|
||||
page.write_text("[Guide](../docs/guide.md#removed)\n[File](../docs/removed.md)\n")
|
||||
errors = VERIFY.check_repository_links(root)
|
||||
self.assertTrue(any("missing Markdown fragment" in error for error in errors))
|
||||
self.assertTrue(any("missing repository target" in error for error in errors))
|
||||
|
||||
def test_preview_preserves_pages_prefix_for_assets_and_directory_redirects(self):
|
||||
with tempfile.TemporaryDirectory() as directory:
|
||||
site = Path(directory)
|
||||
(site / "guide").mkdir()
|
||||
(site / "guide/index.html").write_text("<h1>Guide</h1>")
|
||||
(site / "asset.css").write_text("body { color: black; }")
|
||||
for prefix in ("/", "/rea/"):
|
||||
with self.subTest(prefix=prefix), ThreadingHTTPServer(("127.0.0.1", 0), WEBSITE.preview_handler(site, prefix)) as server:
|
||||
worker = Thread(target=server.serve_forever, daemon=True)
|
||||
worker.start()
|
||||
try:
|
||||
base = f"http://127.0.0.1:{server.server_port}"
|
||||
with urlopen(base + prefix + "guide?test=1") as response:
|
||||
self.assertEqual(response.url, base + prefix + "guide/?test=1")
|
||||
self.assertEqual(response.read(), b"<h1>Guide</h1>")
|
||||
with urlopen(base + prefix + "asset.css") as response:
|
||||
self.assertIn(b"color: black", response.read())
|
||||
with self.assertRaises(HTTPError) as error:
|
||||
urlopen(base + prefix + "missing")
|
||||
self.assertEqual(error.exception.code, 404)
|
||||
if prefix != "/":
|
||||
with self.assertRaises(HTTPError) as error:
|
||||
urlopen(base + "/guide/")
|
||||
self.assertEqual(error.exception.code, 404)
|
||||
finally:
|
||||
server.shutdown()
|
||||
worker.join()
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
unittest.main()
|
||||
|
||||
@@ -0,0 +1,368 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import Ajv2020 from "ajv/dist/2020.js";
|
||||
import {
|
||||
TOOL_CONTRACTS,
|
||||
toolContract,
|
||||
} from "../dist/contracts/toolContracts.js";
|
||||
import { exec } from "./lib/verify-package-core.mjs";
|
||||
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import { createAnthropicModelFixture } from "./verify/clients/anthropic-model-fixture.mjs";
|
||||
|
||||
assert(
|
||||
process.platform !== "win32",
|
||||
"Native Claude Code verifier requires POSIX; Windows is unverified",
|
||||
);
|
||||
const repo = fileURLToPath(new URL("..", import.meta.url));
|
||||
const runtimeRoot = process.env.REA_VERIFY_RUNTIME_ROOT ?? repo;
|
||||
const command = process.env.REA_VERIFY_CLAUDE_COMMAND ?? "claude";
|
||||
const mode = process.argv[2] ?? "call";
|
||||
assert(
|
||||
["chat", "call"].includes(mode),
|
||||
"Usage: verify-claude-client.mjs [chat|call]",
|
||||
);
|
||||
const verifier = createVerifierRun();
|
||||
const lab = await mkdtemp(join(tmpdir(), "rea-claude-client-"));
|
||||
const profile = join(lab, "selected profile");
|
||||
const workspace = join(lab, "workspace");
|
||||
const configPath = join(profile, ".claude.json");
|
||||
const skillDirectory = join(profile, "skills", "reverse-engineer-anything");
|
||||
await Promise.all([mkdir(profile), mkdir(workspace)]);
|
||||
await exec("git", ["init", "--quiet", workspace], { timeout: 30_000 });
|
||||
const environment = {
|
||||
...process.env,
|
||||
CLAUDE_CONFIG_DIR: profile,
|
||||
DISABLE_AUTOUPDATER: "1",
|
||||
CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: "1",
|
||||
REA_PROCESS_RUN_ID: verifier.run_id,
|
||||
};
|
||||
let clientVersion;
|
||||
try {
|
||||
clientVersion = (
|
||||
await exec(command, ["--version"], { env: environment, timeout: 30_000 })
|
||||
).stdout.trim();
|
||||
} catch (cause) {
|
||||
throw new Error(
|
||||
`Claude Code preflight failed for ${command}; install Claude Code or set REA_VERIFY_CLAUDE_COMMAND. ${String(cause)}`,
|
||||
);
|
||||
}
|
||||
const target = join(lab, "fixture α测试");
|
||||
await mkdir(target);
|
||||
await writeFile(
|
||||
join(target, "app.js"),
|
||||
'export function result() { return { clientCompatibility: "REA_CLIENT_FIXTURE", count: 7 }; }\n',
|
||||
);
|
||||
let skillRequested = false;
|
||||
let skillLoaded = false;
|
||||
let expectedSkillBody;
|
||||
let evidenceSeen = false;
|
||||
let finalSeen = false;
|
||||
let catalogSize = 0;
|
||||
let schemasChecked = 0;
|
||||
let pendingServerWaits = 0;
|
||||
let artifactDigest;
|
||||
const schemaValidator = new Ajv2020({ strict: false, validateFormats: false });
|
||||
const containsText = (value, text) => {
|
||||
if (typeof value === "string") return value.includes(text);
|
||||
if (value && typeof value === "object")
|
||||
return Object.values(value).some((nested) => containsText(nested, text));
|
||||
return false;
|
||||
};
|
||||
const extractEvidence = (value) => {
|
||||
if (typeof value === "string") {
|
||||
try {
|
||||
// Native Claude appends this resource hint to tool results. Original bodies remain intact in request artifacts.
|
||||
const json = value.replace(
|
||||
/\n\n<system-reminder>\n<total_tokens>\d+ tokens left<\/total_tokens>\n<\/system-reminder>$/u,
|
||||
"",
|
||||
);
|
||||
return extractEvidence(JSON.parse(json));
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
if (
|
||||
typeof value.evidence_id === "string" &&
|
||||
value.normalized_result?.graph?.nodes?.length > 0
|
||||
)
|
||||
return value;
|
||||
for (const nested of Object.values(value)) {
|
||||
const evidence = extractEvidence(nested);
|
||||
if (evidence) return evidence;
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
};
|
||||
const fixture = await createAnthropicModelFixture({
|
||||
directory: lab,
|
||||
onRequest: async ({ body, tools, requestIndex }) => {
|
||||
if (tools.length === 0)
|
||||
return [{ type: "text", text: "REA fixture title" }];
|
||||
assert(requestIndex <= 8, "Local model workflow exceeded its turn budget");
|
||||
const call = (name, input) => [
|
||||
{ type: "tool_use", id: `toolu_rea_${requestIndex}`, name, input },
|
||||
];
|
||||
const analysis = tools.find((t) =>
|
||||
t.name.endsWith("analyze_javascript_application"),
|
||||
);
|
||||
if (!analysis) {
|
||||
// Native automatic discovery can begin the conversation while MCP is still connecting.
|
||||
const wait = tools.find((t) => t.name === "WaitForMcpServers");
|
||||
assert(
|
||||
wait,
|
||||
"Claude must expose REA tools or its native pending-server wait",
|
||||
);
|
||||
pendingServerWaits++;
|
||||
return call(wait.name, { servers: ["rea"] });
|
||||
}
|
||||
const prefix = analysis.name.slice(
|
||||
0,
|
||||
-"analyze_javascript_application".length,
|
||||
);
|
||||
const expected = TOOL_CONTRACTS.map((t) => prefix + t.name).sort();
|
||||
const reaTools = tools.filter((t) => t.name.startsWith(prefix));
|
||||
assert.deepEqual(
|
||||
reaTools.map((t) => t.name).sort(),
|
||||
expected,
|
||||
"Claude must forward the complete REA catalog after connection",
|
||||
);
|
||||
catalogSize = expected.length;
|
||||
if (schemasChecked === 0) {
|
||||
for (const tool of reaTools) {
|
||||
assert(
|
||||
tool.input_schema,
|
||||
`${tool.name}: missing advertised input schema`,
|
||||
);
|
||||
assert(
|
||||
schemaValidator.validateSchema(tool.input_schema),
|
||||
`${tool.name}: invalid input schema: ${JSON.stringify(schemaValidator.errors)}`,
|
||||
);
|
||||
schemasChecked++;
|
||||
}
|
||||
}
|
||||
skillLoaded ||=
|
||||
expectedSkillBody !== undefined &&
|
||||
containsText(body.messages, expectedSkillBody) &&
|
||||
containsText(body.messages, skillDirectory);
|
||||
const observed = extractEvidence(body.messages);
|
||||
if (observed) {
|
||||
const evidence = toolContract(
|
||||
"analyze_javascript_application",
|
||||
).outputSchema.parse(observed);
|
||||
assert.equal(evidence.subject.local_path, target);
|
||||
const shape = evidence.normalized_result.graph.nodes
|
||||
.flatMap((n) => n.observations)
|
||||
.map((o) => o.properties)
|
||||
.find(
|
||||
(p) =>
|
||||
p.semantic_role === "export-return-shapes" &&
|
||||
p.exported_name === "result",
|
||||
);
|
||||
assert(shape?.return_shape_coverage?.projection_complete);
|
||||
const fields = shape.static_return_shapes.flatMap((s) => s.fields);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) =>
|
||||
f.path === "/clientCompatibility" &&
|
||||
f.state === "literal" &&
|
||||
f.value === "REA_CLIENT_FIXTURE",
|
||||
),
|
||||
);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) => f.path === "/count" && f.state === "literal" && f.value === 7,
|
||||
),
|
||||
);
|
||||
const bytes = JSON.stringify(evidence);
|
||||
artifactDigest = createHash("sha256").update(bytes).digest("hex");
|
||||
await writeFile(join(lab, "claude-evidence.json"), bytes);
|
||||
evidenceSeen = true;
|
||||
}
|
||||
if (mode === "chat" || evidenceSeen) {
|
||||
finalSeen = true;
|
||||
return [{ type: "text", text: "REA_CLIENT_COMPATIBILITY_OK" }];
|
||||
}
|
||||
if (!skillRequested) {
|
||||
const skill = tools.find((t) => t.name === "Skill");
|
||||
assert(skill, "Claude must expose its native Skill tool");
|
||||
skillRequested = true;
|
||||
return call(skill.name, { skill: "reverse-engineer-anything" });
|
||||
}
|
||||
assert(
|
||||
skillLoaded,
|
||||
"Claude must load the complete installed personal REA skill",
|
||||
);
|
||||
return call(analysis.name, { input_path: target, format: "directory" });
|
||||
},
|
||||
});
|
||||
const original = JSON.stringify({ theme: "light", mcpServers: {} }, null, 2);
|
||||
await writeFile(configPath, original);
|
||||
let failure;
|
||||
try {
|
||||
for (const args of [
|
||||
["setup", "--client", "claude_code", "--dry-run"],
|
||||
["setup", "--client", "claude_code", "--yes"],
|
||||
["doctor", "--client", "claude_code", "--skill"],
|
||||
]) {
|
||||
const result = await exec(
|
||||
process.execPath,
|
||||
[join(runtimeRoot, "scripts/rea.mjs"), ...args, "--json"],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
await writeFile(
|
||||
join(lab, `${args[0]}${args.includes("--dry-run") ? "-plan" : ""}.json`),
|
||||
result.stdout,
|
||||
);
|
||||
const parsed = JSON.parse(result.stdout);
|
||||
if (args[0] === "doctor") assert.equal(parsed.healthy, true);
|
||||
else {
|
||||
assert.equal(
|
||||
parsed.status,
|
||||
args.includes("--dry-run") ? "planned" : "ready",
|
||||
);
|
||||
if (args.includes("--dry-run")) {
|
||||
assert(parsed.plannedActions.some((a) => a.target === configPath));
|
||||
assert(parsed.plannedActions.some((a) => a.target === skillDirectory));
|
||||
assert(
|
||||
parsed.plannedActions.every(
|
||||
(a) =>
|
||||
a.target === configPath || a.target.startsWith(skillDirectory),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
const configured = await readFile(configPath, "utf8");
|
||||
assert.equal(JSON.parse(configured).theme, "light");
|
||||
const repeated = await exec(
|
||||
process.execPath,
|
||||
[
|
||||
join(runtimeRoot, "scripts/rea.mjs"),
|
||||
"setup",
|
||||
"--client",
|
||||
"claude_code",
|
||||
"--yes",
|
||||
"--json",
|
||||
],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
assert.deepEqual(JSON.parse(repeated.stdout).appliedActions, []);
|
||||
assert.equal(await readFile(configPath, "utf8"), configured);
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
const installedSkill = await readFile(
|
||||
join(skillDirectory, "SKILL.md"),
|
||||
"utf8",
|
||||
);
|
||||
assert(installedSkill.includes("name: reverse-engineer-anything"));
|
||||
const lines = installedSkill.split("\n");
|
||||
const headerEnd = lines.indexOf("---", 1);
|
||||
assert(
|
||||
lines[0] === "---" && headerEnd > 0,
|
||||
"Installed skill must have its authored frontmatter",
|
||||
);
|
||||
expectedSkillBody = lines
|
||||
.slice(headerEnd + 1)
|
||||
.join("\n")
|
||||
.trim();
|
||||
assert(expectedSkillBody.length > 0);
|
||||
const execution = exec(
|
||||
command,
|
||||
[
|
||||
"--setting-sources",
|
||||
"user",
|
||||
"--print",
|
||||
"--output-format",
|
||||
"json",
|
||||
"--no-session-persistence",
|
||||
"--model",
|
||||
"claude-sonnet-4-6",
|
||||
"--tools",
|
||||
"default",
|
||||
"--permission-mode",
|
||||
"dontAsk",
|
||||
"--settings",
|
||||
JSON.stringify({
|
||||
permissions: {
|
||||
allow: [
|
||||
"Skill",
|
||||
"WaitForMcpServers",
|
||||
"mcp__rea__analyze_javascript_application",
|
||||
],
|
||||
},
|
||||
}),
|
||||
mode === "chat"
|
||||
? "Say hello briefly."
|
||||
: `Use the REA skill and tools to analyze the JavaScript directory ${target}. Report the result.`,
|
||||
],
|
||||
{
|
||||
env: {
|
||||
...environment,
|
||||
ANTHROPIC_API_KEY: "local-fixture-key",
|
||||
ANTHROPIC_AUTH_TOKEN: "",
|
||||
ANTHROPIC_BASE_URL: fixture.baseUrl,
|
||||
},
|
||||
cwd: workspace,
|
||||
timeout: 120_000,
|
||||
maxBuffer: 10 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
execution.child.stdin.end();
|
||||
const response = await execution;
|
||||
await writeFile(join(lab, `${mode}.stdout`), response.stdout);
|
||||
await writeFile(join(lab, `${mode}.stderr`), response.stderr);
|
||||
assert.equal(fixture.failure, undefined);
|
||||
const parsed = JSON.parse(response.stdout);
|
||||
assert.equal(parsed.is_error, false);
|
||||
assert.equal(parsed.subtype, "success");
|
||||
assert.equal(parsed.result, "REA_CLIENT_COMPATIBILITY_OK");
|
||||
assert.deepEqual(parsed.permission_denials, []);
|
||||
assert(finalSeen);
|
||||
if (mode === "call") assert(evidenceSeen && skillLoaded);
|
||||
} catch (cause) {
|
||||
failure = cause;
|
||||
if (typeof cause?.stdout === "string")
|
||||
await writeFile(join(lab, `${mode}.stdout`), cause.stdout);
|
||||
if (typeof cause?.stderr === "string")
|
||||
await writeFile(join(lab, `${mode}.stderr`), cause.stderr);
|
||||
} finally {
|
||||
await fixture.close();
|
||||
const receipt = {
|
||||
client: "Claude Code",
|
||||
clientVersion,
|
||||
mode,
|
||||
passed: failure === undefined,
|
||||
artifacts: lab,
|
||||
runtimeRoot,
|
||||
host: {
|
||||
platform: process.platform,
|
||||
architecture: process.arch,
|
||||
node: process.versions.node,
|
||||
},
|
||||
modelFixture:
|
||||
"loopback Anthropic Messages/SSE; synthetic usage and native resource hints; no live API claim",
|
||||
discovery:
|
||||
"native CLAUDE_CONFIG_DIR user configuration and skills; separate Git root, user settings only, default built-in tools",
|
||||
bareMode:
|
||||
"not used; native bare print mode did not load the personal skill",
|
||||
catalogSize,
|
||||
schemasChecked,
|
||||
pendingServerWaits,
|
||||
evidenceSeen,
|
||||
skillLoaded,
|
||||
artifactDigest,
|
||||
finalSeen,
|
||||
requests: fixture.requests,
|
||||
probes: fixture.probes,
|
||||
fixtureFailure: fixture.failure,
|
||||
verifier: await completeVerifierRun(verifier),
|
||||
};
|
||||
await writeFile(join(lab, "receipt.json"), JSON.stringify(receipt, null, 2));
|
||||
console.log(JSON.stringify(receipt));
|
||||
}
|
||||
if (failure !== undefined) throw failure;
|
||||
@@ -0,0 +1,346 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { dirname, join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { Ajv2020 } from "ajv/dist/2020.js";
|
||||
import {
|
||||
TOOL_CONTRACTS,
|
||||
toolContract,
|
||||
} from "../dist/contracts/toolContracts.js";
|
||||
import { exec } from "./lib/verify-package-core.mjs";
|
||||
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import { createOpenAiModelFixture } from "./verify/clients/model-fixture.mjs";
|
||||
|
||||
const mode = process.argv[2] ?? "call";
|
||||
assert(["chat", "call"].includes(mode), "Select chat or call.");
|
||||
assert(process.platform !== "win32", "Native Windows coverage is unverified.");
|
||||
const repo = fileURLToPath(new URL("..", import.meta.url));
|
||||
const runtimeRoot = process.env.REA_VERIFY_RUNTIME_ROOT ?? repo;
|
||||
const command = process.env.REA_VERIFY_DEEPSEEK_COMMAND ?? "dsh";
|
||||
const lab = await mkdtemp(join(tmpdir(), "rea-deepseek-client-"));
|
||||
const account = join(lab, "account");
|
||||
const profile = join(lab, "selected profile");
|
||||
const workspace = join(lab, "workspace");
|
||||
const target = join(workspace, "fixture α测试");
|
||||
const skillPath = join(
|
||||
account,
|
||||
".agents",
|
||||
"skills",
|
||||
"reverse-engineer-anything",
|
||||
"SKILL.md",
|
||||
);
|
||||
const cli = join(runtimeRoot, "scripts", "rea.mjs");
|
||||
const verifier = createVerifierRun();
|
||||
await Promise.all([
|
||||
mkdir(account),
|
||||
mkdir(profile),
|
||||
mkdir(target, { recursive: true }),
|
||||
]);
|
||||
const environment = {
|
||||
PATH: process.env.PATH ?? "",
|
||||
USERPROFILE: account,
|
||||
DSH_HOME: profile,
|
||||
DSH_AGENTS_HOME: join(account, ".agents"),
|
||||
OPENAI_API_KEY: "local-fixture-key",
|
||||
REA_PROCESS_RUN_ID: verifier.run_id,
|
||||
};
|
||||
// A temporary directory under the checkout must not inherit its project skills or AGENTS.md.
|
||||
await exec(
|
||||
"git",
|
||||
["-c", "init.defaultBranch=main", "init", "--quiet", workspace],
|
||||
{
|
||||
env: environment,
|
||||
timeout: 30_000,
|
||||
},
|
||||
);
|
||||
await writeFile(
|
||||
join(target, "app.js"),
|
||||
'export function result() { return { clientCompatibility: "REA_CLIENT_FIXTURE", count: 7 }; }\n',
|
||||
);
|
||||
const clientVersion = (
|
||||
await exec(command, ["--version"], {
|
||||
env: environment,
|
||||
cwd: workspace,
|
||||
timeout: 30_000,
|
||||
})
|
||||
).stdout.trim();
|
||||
for (const args of [
|
||||
["setup", "--skill", "--dry-run"],
|
||||
["setup", "--skill", "--yes"],
|
||||
]) {
|
||||
const result = await exec(process.execPath, [cli, ...args, "--json"], {
|
||||
env: environment,
|
||||
cwd: workspace,
|
||||
timeout: 60_000,
|
||||
});
|
||||
const parsed = JSON.parse(result.stdout);
|
||||
assert.equal(parsed.status, args.includes("--dry-run") ? "planned" : "ready");
|
||||
if (args.includes("--dry-run")) {
|
||||
assert.equal(parsed.plannedActions.length, 1);
|
||||
assert.equal(parsed.plannedActions[0].kind, "install_skill");
|
||||
assert.equal(parsed.plannedActions[0].target, dirname(skillPath));
|
||||
}
|
||||
await writeFile(
|
||||
join(lab, args.includes("--dry-run") ? "setup-plan.json" : "setup.json"),
|
||||
result.stdout,
|
||||
);
|
||||
}
|
||||
assert(
|
||||
(await readFile(skillPath, "utf8")).includes(
|
||||
"name: reverse-engineer-anything",
|
||||
),
|
||||
);
|
||||
|
||||
let catalog;
|
||||
let patternCount = 0;
|
||||
let skillRequested = false;
|
||||
let skillLoaded = false;
|
||||
let evidenceSeen = false;
|
||||
let finalSeen = false;
|
||||
let artifactDigest;
|
||||
let mainRequests = 0;
|
||||
const ajv = new Ajv2020({ strict: false, validateFormats: false });
|
||||
const patterns = new Set();
|
||||
const validatePatterns = (value) => {
|
||||
if (!value || typeof value !== "object") return;
|
||||
for (const [key, child] of Object.entries(value)) {
|
||||
if (key === "pattern" && typeof child === "string") {
|
||||
// Check the representation the native client actually forwards to its model adapter.
|
||||
for (const flags of ["", "u", "v"]) new RegExp(child, flags);
|
||||
patterns.add(child);
|
||||
patternCount++;
|
||||
} else validatePatterns(child);
|
||||
}
|
||||
};
|
||||
const extractEvidence = (value) => {
|
||||
if (typeof value === "string") {
|
||||
try {
|
||||
return extractEvidence(JSON.parse(value));
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
if (
|
||||
typeof value.evidence_id === "string" &&
|
||||
value.normalized_result?.graph?.nodes
|
||||
)
|
||||
return value;
|
||||
for (const child of Object.values(value)) {
|
||||
const found = extractEvidence(child);
|
||||
if (found) return found;
|
||||
}
|
||||
}
|
||||
};
|
||||
const fixture = await createOpenAiModelFixture({
|
||||
directory: lab,
|
||||
prefix: `deepseek-${mode}`,
|
||||
onRequest: async ({ body, tools, requestIndex }) => {
|
||||
// Harness generates a session title in a separate, tool-free model request.
|
||||
if (tools.length === 0)
|
||||
return { role: "assistant", content: "REA validation" };
|
||||
assert(
|
||||
++mainRequests <= 4,
|
||||
"Harness did not complete the bounded fixture workflow.",
|
||||
);
|
||||
const rea = tools.filter((tool) => tool.name.startsWith("mcp__rea__"));
|
||||
const observedCatalog = rea
|
||||
.map((tool) => tool.name.slice("mcp__rea__".length))
|
||||
.sort();
|
||||
assert.deepEqual(
|
||||
observedCatalog,
|
||||
TOOL_CONTRACTS.map((tool) => tool.name).sort(),
|
||||
);
|
||||
if (catalog === undefined) {
|
||||
catalog = observedCatalog;
|
||||
for (const tool of rea) {
|
||||
assert(
|
||||
ajv.validateSchema(tool.parameters),
|
||||
`${tool.name}: ${ajv.errorsText(ajv.errors)}`,
|
||||
);
|
||||
validatePatterns(tool.parameters);
|
||||
}
|
||||
assert(
|
||||
patternCount > 0,
|
||||
"The advertised regex constraints must reach the model.",
|
||||
);
|
||||
}
|
||||
const toolMessages = (body.messages ?? []).filter(
|
||||
(message) => message.role === "tool",
|
||||
);
|
||||
const serialized = JSON.stringify(toolMessages);
|
||||
skillLoaded ||=
|
||||
serialized.includes(
|
||||
'<skill_content name=\\"reverse-engineer-anything\\">',
|
||||
) && serialized.includes(dirname(skillPath));
|
||||
for (const message of toolMessages) {
|
||||
const found = extractEvidence(message.content);
|
||||
if (found === undefined) continue;
|
||||
const evidence = toolContract(
|
||||
"analyze_javascript_application",
|
||||
).outputSchema.parse(found);
|
||||
assert.equal(evidence.subject.local_path, target);
|
||||
const shape = evidence.normalized_result.graph.nodes
|
||||
.flatMap((node) => node.observations)
|
||||
.map((observation) => observation.properties)
|
||||
.find(
|
||||
(properties) =>
|
||||
properties.semantic_role === "export-return-shapes" &&
|
||||
properties.exported_name === "result",
|
||||
);
|
||||
assert(shape?.return_shape_coverage?.projection_complete);
|
||||
const fields = shape.static_return_shapes.flatMap(
|
||||
(entry) => entry.fields,
|
||||
);
|
||||
assert(
|
||||
fields.some(
|
||||
(field) =>
|
||||
field.path === "/clientCompatibility" &&
|
||||
field.state === "literal" &&
|
||||
field.value === "REA_CLIENT_FIXTURE",
|
||||
),
|
||||
);
|
||||
assert(
|
||||
fields.some(
|
||||
(field) =>
|
||||
field.path === "/count" &&
|
||||
field.state === "literal" &&
|
||||
field.value === 7,
|
||||
),
|
||||
);
|
||||
const text = JSON.stringify(evidence);
|
||||
await writeFile(join(lab, "evidence.json"), text);
|
||||
artifactDigest = createHash("sha256").update(text).digest("hex");
|
||||
evidenceSeen = true;
|
||||
}
|
||||
if (mode === "chat" || evidenceSeen) {
|
||||
finalSeen = true;
|
||||
return { role: "assistant", content: "REA_CLIENT_COMPATIBILITY_OK" };
|
||||
}
|
||||
const call = (name, args) => ({
|
||||
role: "assistant",
|
||||
content: null,
|
||||
tool_calls: [
|
||||
{
|
||||
id: `call_rea_${requestIndex}`,
|
||||
type: "function",
|
||||
function: { name, arguments: JSON.stringify(args) },
|
||||
},
|
||||
],
|
||||
});
|
||||
if (!skillRequested) {
|
||||
assert(tools.some((tool) => tool.name === "skill"));
|
||||
skillRequested = true;
|
||||
return call("skill", { name: "reverse-engineer-anything" });
|
||||
}
|
||||
assert(
|
||||
skillLoaded,
|
||||
"Harness must load the installed skill before analysis.",
|
||||
);
|
||||
return call("mcp__rea__analyze_javascript_application", {
|
||||
input_path: target,
|
||||
format: "directory",
|
||||
});
|
||||
},
|
||||
});
|
||||
let failure;
|
||||
try {
|
||||
// Use the client's native Cordis patch DSL; generic `rea setup --client` does not edit it.
|
||||
await writeFile(
|
||||
join(profile, "cordis.patch.yml"),
|
||||
`
|
||||
- id: llm-pi-ai
|
||||
config:
|
||||
providers:
|
||||
rea-fixture:
|
||||
apiKeyEnv: OPENAI_API_KEY
|
||||
api: openai-completions
|
||||
baseURL: ${fixture.baseUrl}
|
||||
defaultMaxTokens: 4096
|
||||
retryPolicy:
|
||||
mode: normal
|
||||
maxRetries: 0
|
||||
models:
|
||||
- id: rea-client-fixture
|
||||
contextWindow: 1000000
|
||||
- id: agent-default-model
|
||||
config:
|
||||
provider: rea-fixture
|
||||
model: rea-client-fixture
|
||||
- insert:
|
||||
- id: rea-mcp
|
||||
name: '@deepseek-ai/dsh-mcp-client'
|
||||
config:
|
||||
serverName: rea
|
||||
transport: stdio
|
||||
command: ${JSON.stringify(process.execPath)}
|
||||
args: ${JSON.stringify([cli, "mcp"])}
|
||||
cwd: !!js process.cwd()
|
||||
env:
|
||||
REA_PROCESS_RUN_ID: ${JSON.stringify(verifier.run_id)}
|
||||
`,
|
||||
);
|
||||
const execution = exec(
|
||||
command,
|
||||
[
|
||||
"--profile",
|
||||
"headless",
|
||||
"--json",
|
||||
mode === "chat" ? "Say hello briefly." : `Use REA to analyze ${target}.`,
|
||||
],
|
||||
{
|
||||
env: environment,
|
||||
cwd: workspace,
|
||||
timeout: 120_000,
|
||||
maxBuffer: 10 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
execution.child.stdin.end();
|
||||
const result = await execution;
|
||||
await writeFile(join(lab, "client.stdout"), result.stdout);
|
||||
await writeFile(join(lab, "client.stderr"), result.stderr);
|
||||
assert.equal(fixture.failure, undefined);
|
||||
assert(finalSeen && result.stdout.includes("REA_CLIENT_COMPATIBILITY_OK"));
|
||||
if (mode === "call") assert(evidenceSeen && skillLoaded);
|
||||
} catch (cause) {
|
||||
failure = cause;
|
||||
if (typeof cause?.stdout === "string")
|
||||
await writeFile(join(lab, "client.stdout"), cause.stdout);
|
||||
if (typeof cause?.stderr === "string")
|
||||
await writeFile(join(lab, "client.stderr"), cause.stderr);
|
||||
} finally {
|
||||
await fixture.close();
|
||||
const receipt = {
|
||||
client: "deepseek-harness",
|
||||
clientVersion,
|
||||
mode,
|
||||
passed: failure === undefined,
|
||||
artifacts: lab,
|
||||
runtimeRoot,
|
||||
host: {
|
||||
platform: process.platform,
|
||||
architecture: process.arch,
|
||||
node: process.versions.node,
|
||||
},
|
||||
modelFixture:
|
||||
"loopback custom OpenAI-compatible adapter; no live DeepSeek provider claim",
|
||||
modelContextWindow: 1000000,
|
||||
skillDiscovery:
|
||||
"native DSH_AGENTS_HOME personal directory; isolated project root",
|
||||
catalogSize: catalog?.length,
|
||||
patternCount,
|
||||
uniquePatterns: patterns.size,
|
||||
skillLoaded,
|
||||
evidenceSeen,
|
||||
artifactDigest,
|
||||
finalSeen,
|
||||
requests: fixture.requests,
|
||||
fixtureFailure: fixture.failure,
|
||||
verifier: await completeVerifierRun(verifier),
|
||||
};
|
||||
await writeFile(join(lab, "receipt.json"), JSON.stringify(receipt, null, 2));
|
||||
console.log(JSON.stringify(receipt));
|
||||
}
|
||||
if (failure !== undefined) throw failure;
|
||||
@@ -0,0 +1,378 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import Ajv2020 from "ajv/dist/2020.js";
|
||||
import {
|
||||
TOOL_CONTRACTS,
|
||||
toolContract,
|
||||
} from "../dist/contracts/toolContracts.js";
|
||||
import { exec } from "./lib/verify-package-core.mjs";
|
||||
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import { createGeminiModelFixture } from "./verify/clients/gemini-model-fixture.mjs";
|
||||
|
||||
assert(
|
||||
process.platform !== "win32",
|
||||
"Native Gemini verifier requires POSIX; Windows is unverified",
|
||||
);
|
||||
const repo = fileURLToPath(new URL("..", import.meta.url));
|
||||
const runtimeRoot = process.env.REA_VERIFY_RUNTIME_ROOT ?? repo;
|
||||
const command = process.env.REA_VERIFY_GEMINI_COMMAND ?? "gemini";
|
||||
const mode = process.argv[2] ?? "call";
|
||||
assert(
|
||||
["chat", "call"].includes(mode),
|
||||
"Usage: verify-gemini-client.mjs [chat|call]",
|
||||
);
|
||||
const verifier = createVerifierRun();
|
||||
const lab = await mkdtemp(join(tmpdir(), "rea-gemini-client-"));
|
||||
const account = join(lab, "account");
|
||||
const profile = join(lab, "selected profile");
|
||||
const workspace = join(lab, "workspace");
|
||||
const configPath = join(profile, ".gemini", "settings.json");
|
||||
const skillPath = join(
|
||||
profile,
|
||||
".agents",
|
||||
"skills",
|
||||
"reverse-engineer-anything",
|
||||
"SKILL.md",
|
||||
);
|
||||
await Promise.all([
|
||||
mkdir(account),
|
||||
mkdir(workspace),
|
||||
mkdir(join(profile, ".gemini"), { recursive: true }),
|
||||
]);
|
||||
await exec("git", ["init", "--quiet", workspace], { timeout: 30_000 });
|
||||
await writeFile(join(lab, "system-settings.json"), "{}\n");
|
||||
await writeFile(join(lab, "system-defaults.json"), "{}\n");
|
||||
const environment = {
|
||||
PATH: process.env.PATH ?? "",
|
||||
USERPROFILE: account,
|
||||
GEMINI_CLI_HOME: profile,
|
||||
GEMINI_CLI_SYSTEM_SETTINGS_PATH: join(lab, "system-settings.json"),
|
||||
GEMINI_CLI_SYSTEM_DEFAULTS_PATH: join(lab, "system-defaults.json"),
|
||||
// Preserve the caller's bounded Node heap instead of the launcher's host-memory auto-sizing.
|
||||
GEMINI_CLI_NO_RELAUNCH: "1",
|
||||
GEMINI_CLI_TRUST_WORKSPACE: "true",
|
||||
REA_PROCESS_RUN_ID: verifier.run_id,
|
||||
};
|
||||
let clientVersion;
|
||||
try {
|
||||
clientVersion = (
|
||||
await exec(command, ["--version"], { env: environment, timeout: 30_000 })
|
||||
).stdout.trim();
|
||||
} catch (cause) {
|
||||
throw new Error(
|
||||
`Gemini preflight failed for ${command}; install Gemini CLI or set REA_VERIFY_GEMINI_COMMAND. ${String(cause)}`,
|
||||
);
|
||||
}
|
||||
const original = JSON.stringify(
|
||||
{
|
||||
security: {
|
||||
auth: { selectedType: "gemini-api-key" },
|
||||
folderTrust: { enabled: false },
|
||||
},
|
||||
telemetry: { enabled: false },
|
||||
advanced: { autoConfigureMemory: false },
|
||||
model: { name: "gemini-2.5-flash", maxSessionTurns: 8 },
|
||||
mcpServers: { other: { command: "unrelated-server" } },
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
await writeFile(configPath, original);
|
||||
for (const args of [
|
||||
["setup", "--client", "gemini_cli", "--dry-run"],
|
||||
["setup", "--client", "gemini_cli", "--yes"],
|
||||
["doctor", "--client", "gemini_cli", "--skill"],
|
||||
]) {
|
||||
const result = await exec(
|
||||
process.execPath,
|
||||
[join(runtimeRoot, "scripts/rea.mjs"), ...args, "--json"],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
const parsed = JSON.parse(result.stdout);
|
||||
if (args[0] === "doctor") assert.equal(parsed.healthy, true);
|
||||
else {
|
||||
assert.equal(
|
||||
parsed.status,
|
||||
args.includes("--dry-run") ? "planned" : "ready",
|
||||
);
|
||||
if (args.includes("--dry-run")) {
|
||||
assert(parsed.plannedActions.some((a) => a.target === configPath));
|
||||
assert(
|
||||
parsed.plannedActions.some((a) =>
|
||||
a.target.startsWith(join(profile, ".agents", "skills") + "/"),
|
||||
),
|
||||
);
|
||||
assert(
|
||||
parsed.plannedActions.every((a) => a.target.startsWith(profile + "/")),
|
||||
);
|
||||
}
|
||||
}
|
||||
await writeFile(
|
||||
join(lab, `${args[0]}${args.includes("--dry-run") ? "-plan" : ""}.json`),
|
||||
result.stdout,
|
||||
);
|
||||
}
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
const configured = await readFile(configPath, "utf8");
|
||||
assert.deepEqual(JSON.parse(configured).mcpServers.other, {
|
||||
command: "unrelated-server",
|
||||
});
|
||||
const repeated = await exec(
|
||||
process.execPath,
|
||||
[
|
||||
join(runtimeRoot, "scripts/rea.mjs"),
|
||||
"setup",
|
||||
"--client",
|
||||
"gemini_cli",
|
||||
"--yes",
|
||||
"--json",
|
||||
],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
assert.deepEqual(JSON.parse(repeated.stdout).appliedActions, []);
|
||||
assert.equal(await readFile(configPath, "utf8"), configured);
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
assert(
|
||||
(await readFile(skillPath, "utf8")).includes(
|
||||
"name: reverse-engineer-anything",
|
||||
),
|
||||
);
|
||||
const target = join(lab, "fixture α测试");
|
||||
await mkdir(target);
|
||||
await writeFile(
|
||||
join(target, "app.js"),
|
||||
'export function result() { return { clientCompatibility: "REA_CLIENT_FIXTURE", count: 7 }; }\n',
|
||||
);
|
||||
let evidenceSeen = false;
|
||||
let skillLoaded = false;
|
||||
let skillRequested = false;
|
||||
let finalSeen = false;
|
||||
let catalogSize = 0;
|
||||
let schemasChecked = 0;
|
||||
let artifactDigest;
|
||||
const schemaValidator = new Ajv2020({ strict: false, validateFormats: false });
|
||||
const extractEvidence = (value) => {
|
||||
if (typeof value === "string") {
|
||||
if (
|
||||
value.startsWith("<untrusted_context>\n") &&
|
||||
value.endsWith("\n</untrusted_context>")
|
||||
) {
|
||||
return extractEvidence(
|
||||
value.slice(
|
||||
"<untrusted_context>\n".length,
|
||||
-"\n</untrusted_context>".length,
|
||||
),
|
||||
);
|
||||
}
|
||||
try {
|
||||
return extractEvidence(JSON.parse(value));
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
if (
|
||||
typeof value.evidence_id === "string" &&
|
||||
value.normalized_result?.graph?.nodes?.length > 0
|
||||
)
|
||||
return value;
|
||||
for (const nested of Object.values(value)) {
|
||||
const evidence = extractEvidence(nested);
|
||||
if (evidence) return evidence;
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
};
|
||||
const fixture = await createGeminiModelFixture({
|
||||
directory: lab,
|
||||
onRequest: async ({ body, tools }) => {
|
||||
const analysis = tools.find((t) =>
|
||||
t.name.endsWith("analyze_javascript_application"),
|
||||
);
|
||||
assert(analysis, "Gemini must expose the REA analysis tool");
|
||||
const prefix = analysis.name.slice(
|
||||
0,
|
||||
-"analyze_javascript_application".length,
|
||||
);
|
||||
const expected = TOOL_CONTRACTS.map((t) => prefix + t.name).sort();
|
||||
assert.deepEqual(
|
||||
tools
|
||||
.filter((t) => expected.includes(t.name))
|
||||
.map((t) => t.name)
|
||||
.sort(),
|
||||
expected,
|
||||
"Gemini must forward the complete REA tool catalog",
|
||||
);
|
||||
catalogSize = expected.length;
|
||||
if (schemasChecked === 0) {
|
||||
for (const tool of tools.filter((t) => expected.includes(t.name))) {
|
||||
assert(
|
||||
tool.parametersJsonSchema,
|
||||
`${tool.name}: missing advertised JSON Schema`,
|
||||
);
|
||||
assert(
|
||||
schemaValidator.validateSchema(tool.parametersJsonSchema),
|
||||
`${tool.name}: invalid advertised JSON Schema: ${JSON.stringify(schemaValidator.errors)}`,
|
||||
);
|
||||
schemasChecked++;
|
||||
}
|
||||
}
|
||||
const responses = body.contents
|
||||
.flatMap((c) => c.parts ?? [])
|
||||
.filter((p) => p.functionResponse)
|
||||
.map((p) => p.functionResponse);
|
||||
skillLoaded ||= responses.some(
|
||||
(r) =>
|
||||
r.name === "activate_skill" &&
|
||||
r.response?.output?.includes(
|
||||
`<activated_skill name="reverse-engineer-anything">`,
|
||||
) &&
|
||||
r.response.output.includes(
|
||||
join(profile, ".agents", "skills", "reverse-engineer-anything"),
|
||||
),
|
||||
);
|
||||
const observed = extractEvidence(responses);
|
||||
if (observed) {
|
||||
const evidence = toolContract(
|
||||
"analyze_javascript_application",
|
||||
).outputSchema.parse(observed);
|
||||
assert.equal(evidence.subject.local_path, target);
|
||||
const shape = evidence.normalized_result.graph.nodes
|
||||
.flatMap((n) => n.observations)
|
||||
.map((o) => o.properties)
|
||||
.find(
|
||||
(p) =>
|
||||
p.semantic_role === "export-return-shapes" &&
|
||||
p.exported_name === "result",
|
||||
);
|
||||
assert(shape?.return_shape_coverage?.projection_complete);
|
||||
const fields = shape.static_return_shapes.flatMap((s) => s.fields);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) =>
|
||||
f.path === "/clientCompatibility" &&
|
||||
f.state === "literal" &&
|
||||
f.value === "REA_CLIENT_FIXTURE",
|
||||
),
|
||||
);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) => f.path === "/count" && f.state === "literal" && f.value === 7,
|
||||
),
|
||||
);
|
||||
const bytes = JSON.stringify(evidence);
|
||||
artifactDigest = createHash("sha256").update(bytes).digest("hex");
|
||||
await writeFile(join(lab, "gemini-evidence.json"), bytes);
|
||||
evidenceSeen = true;
|
||||
}
|
||||
if (mode === "chat" || evidenceSeen) {
|
||||
finalSeen = true;
|
||||
return [{ text: "REA_CLIENT_COMPATIBILITY_OK" }];
|
||||
}
|
||||
if (!skillRequested) {
|
||||
const skill = tools.find((t) => t.name === "activate_skill");
|
||||
assert(skill, "Gemini must expose its native skill activation tool");
|
||||
skillRequested = true;
|
||||
return [
|
||||
{
|
||||
functionCall: {
|
||||
name: skill.name,
|
||||
args: { name: "reverse-engineer-anything" },
|
||||
},
|
||||
},
|
||||
];
|
||||
}
|
||||
assert(skillLoaded, "Gemini must load the installed personal REA skill");
|
||||
return [
|
||||
{
|
||||
functionCall: {
|
||||
name: analysis.name,
|
||||
args: { input_path: target, format: "directory" },
|
||||
},
|
||||
},
|
||||
];
|
||||
},
|
||||
});
|
||||
let failure;
|
||||
try {
|
||||
const response = await exec(
|
||||
command,
|
||||
[
|
||||
"--model",
|
||||
"gemini-2.5-flash",
|
||||
"--approval-mode",
|
||||
mode === "chat" ? "default" : "yolo",
|
||||
"--allowed-mcp-server-names",
|
||||
"rea",
|
||||
"--output-format",
|
||||
"stream-json",
|
||||
"-p",
|
||||
mode === "chat"
|
||||
? "Say hello briefly."
|
||||
: `Use REA to analyze the JavaScript directory ${target}. Report the result.`,
|
||||
],
|
||||
{
|
||||
env: {
|
||||
...environment,
|
||||
GEMINI_API_KEY: "local-fixture-key",
|
||||
GOOGLE_GEMINI_BASE_URL: fixture.baseUrl,
|
||||
},
|
||||
cwd: workspace,
|
||||
timeout: 120_000,
|
||||
maxBuffer: 10 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
await writeFile(join(lab, `${mode}.stdout`), response.stdout);
|
||||
await writeFile(join(lab, `${mode}.stderr`), response.stderr);
|
||||
const events = response.stdout
|
||||
.split("\n")
|
||||
.filter(Boolean)
|
||||
.map((line) => JSON.parse(line));
|
||||
assert.equal(events.findLast((e) => e.type === "result")?.status, "success");
|
||||
assert.equal(fixture.failure, undefined);
|
||||
assert(finalSeen && response.stdout.includes("REA_CLIENT_COMPATIBILITY_OK"));
|
||||
if (mode === "call") assert(evidenceSeen && skillLoaded);
|
||||
} catch (cause) {
|
||||
failure = cause;
|
||||
if (typeof cause?.stdout === "string")
|
||||
await writeFile(join(lab, `${mode}.stdout`), cause.stdout);
|
||||
if (typeof cause?.stderr === "string")
|
||||
await writeFile(join(lab, `${mode}.stderr`), cause.stderr);
|
||||
} finally {
|
||||
await fixture.close();
|
||||
const lineage = await completeVerifierRun(verifier);
|
||||
const receipt = {
|
||||
client: "Gemini CLI",
|
||||
clientVersion,
|
||||
mode,
|
||||
passed: failure === undefined,
|
||||
artifacts: lab,
|
||||
runtimeRoot,
|
||||
host: {
|
||||
platform: process.platform,
|
||||
architecture: process.arch,
|
||||
node: process.versions.node,
|
||||
},
|
||||
modelFixture:
|
||||
"loopback native Gemini API adapter; token counts synthetic; no live Google API claim",
|
||||
skillDiscovery:
|
||||
"native GEMINI_CLI_HOME personal shared directory; isolated Git project",
|
||||
catalogSize,
|
||||
schemasChecked,
|
||||
evidenceSeen,
|
||||
skillLoaded,
|
||||
artifactDigest,
|
||||
finalSeen,
|
||||
requests: fixture.requests,
|
||||
probes: fixture.probes,
|
||||
fixtureFailure: fixture.failure,
|
||||
verifier: lineage,
|
||||
};
|
||||
await writeFile(join(lab, "receipt.json"), JSON.stringify(receipt, null, 2));
|
||||
console.log(JSON.stringify(receipt));
|
||||
}
|
||||
if (failure !== undefined) throw failure;
|
||||
@@ -27,11 +27,16 @@ const command =
|
||||
const lab = await mkdtemp(join(tmpdir(), `rea-${client}-client-`));
|
||||
const account = join(lab, "account");
|
||||
const profile = join(lab, "selected profile");
|
||||
const stickyHermes =
|
||||
client === "hermes" && process.env.REA_VERIFY_HERMES_STICKY_PROFILE === "1";
|
||||
const selectedProfile = stickyHermes
|
||||
? join(profile, "profiles", "coder")
|
||||
: profile;
|
||||
const workspace = join(lab, "workspace");
|
||||
const target = join(workspace, "fixture α测试");
|
||||
const artifactPath = join(workspace, "evidence.json");
|
||||
const skillPath = join(
|
||||
client === "pi" ? join(account, ".agents") : profile,
|
||||
client === "pi" ? join(account, ".agents") : selectedProfile,
|
||||
"skills",
|
||||
"reverse-engineer-anything",
|
||||
"SKILL.md",
|
||||
@@ -39,7 +44,8 @@ const skillPath = join(
|
||||
const verifier = createVerifierRun();
|
||||
await Promise.all([
|
||||
mkdir(account),
|
||||
mkdir(profile),
|
||||
mkdir(profile, { recursive: true }),
|
||||
...(stickyHermes ? [mkdir(selectedProfile, { recursive: true })] : []),
|
||||
mkdir(target, { recursive: true }),
|
||||
]);
|
||||
await writeFile(
|
||||
@@ -53,7 +59,11 @@ const environment = {
|
||||
PI_OFFLINE: "1",
|
||||
REA_PROCESS_RUN_ID: verifier.run_id,
|
||||
};
|
||||
const configPath = join(profile, client === "pi" ? "mcp.json" : "config.yaml");
|
||||
const configPath = join(
|
||||
selectedProfile,
|
||||
client === "pi" ? "mcp.json" : "config.yaml",
|
||||
);
|
||||
if (stickyHermes) await writeFile(join(profile, "active_profile"), "coder\n");
|
||||
const original =
|
||||
client === "pi"
|
||||
? JSON.stringify({
|
||||
@@ -440,6 +450,7 @@ try {
|
||||
client === "pi"
|
||||
? "caller-configured isolated shared directory; default OS home discovery unverified"
|
||||
: "native HERMES_HOME personal directory",
|
||||
stickyHermes,
|
||||
catalogSize: catalog?.length,
|
||||
evidenceSeen,
|
||||
skillLoaded,
|
||||
|
||||
@@ -0,0 +1,377 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, mkdtemp, readFile, writeFile } from "node:fs/promises";
|
||||
import { tmpdir } from "node:os";
|
||||
import { join } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import Ajv2020 from "ajv/dist/2020.js";
|
||||
import {
|
||||
TOOL_CONTRACTS,
|
||||
toolContract,
|
||||
} from "../dist/contracts/toolContracts.js";
|
||||
import { exec } from "./lib/verify-package-core.mjs";
|
||||
import { createVerifierRun, completeVerifierRun } from "./lib/verifier-run.mjs";
|
||||
import { createOpenAiModelFixture } from "./verify/clients/model-fixture.mjs";
|
||||
|
||||
assert(
|
||||
process.platform !== "win32",
|
||||
"Native OpenCode verifier requires POSIX; Windows is unverified",
|
||||
);
|
||||
const repo = fileURLToPath(new URL("..", import.meta.url));
|
||||
const runtimeRoot = process.env.REA_VERIFY_RUNTIME_ROOT ?? repo;
|
||||
const command = process.env.REA_VERIFY_OPENCODE_COMMAND ?? "opencode";
|
||||
const mode = process.argv[2] ?? "call";
|
||||
const configFormat = process.env.REA_VERIFY_OPENCODE_CONFIG_FORMAT ?? "jsonc";
|
||||
assert(
|
||||
["chat", "call"].includes(mode),
|
||||
"Usage: verify-opencode-client.mjs [chat|call]",
|
||||
);
|
||||
assert(
|
||||
["json", "jsonc"].includes(configFormat),
|
||||
"REA_VERIFY_OPENCODE_CONFIG_FORMAT must be json or jsonc",
|
||||
);
|
||||
const verifier = createVerifierRun();
|
||||
const lab = await mkdtemp(join(tmpdir(), "rea-opencode-client-"));
|
||||
const account = join(lab, "account");
|
||||
const profile = join(lab, "selected profile");
|
||||
const workspace = join(lab, "workspace");
|
||||
const configPath = join(profile, `opencode.${configFormat}`);
|
||||
const skillDirectory = join(
|
||||
account,
|
||||
".agents",
|
||||
"skills",
|
||||
"reverse-engineer-anything",
|
||||
);
|
||||
await Promise.all([mkdir(account), mkdir(profile), mkdir(workspace)]);
|
||||
await exec("git", ["init", "--quiet", workspace], { timeout: 30_000 });
|
||||
const environment = {
|
||||
USERPROFILE: account,
|
||||
OPENCODE_CONFIG_DIR: profile,
|
||||
XDG_CONFIG_HOME: join(lab, "config"),
|
||||
XDG_CACHE_HOME: join(lab, "cache"),
|
||||
XDG_DATA_HOME: join(lab, "data"),
|
||||
XDG_STATE_HOME: join(lab, "state"),
|
||||
OPENCODE_DISABLE_AUTOUPDATE: "true",
|
||||
OPENCODE_DISABLE_MODELS_FETCH: "true",
|
||||
// Use the native core without external account plugins.
|
||||
OPENCODE_PURE: "true",
|
||||
REA_PROCESS_RUN_ID: verifier.run_id,
|
||||
};
|
||||
let clientVersion;
|
||||
try {
|
||||
clientVersion = (
|
||||
await exec(command, ["--version"], { env: environment, timeout: 30_000 })
|
||||
).stdout.trim();
|
||||
} catch (cause) {
|
||||
throw new Error(
|
||||
`OpenCode preflight failed for ${command}; install OpenCode or set REA_VERIFY_OPENCODE_COMMAND. ${String(cause)}`,
|
||||
);
|
||||
}
|
||||
const target = join(lab, "fixture α测试");
|
||||
await mkdir(target);
|
||||
await writeFile(
|
||||
join(target, "app.js"),
|
||||
'export function result() { return { clientCompatibility: "REA_CLIENT_FIXTURE", count: 7 }; }\n',
|
||||
);
|
||||
let skillRequested = false;
|
||||
let skillLoaded = false;
|
||||
let expectedSkillBody;
|
||||
let evidenceSeen = false;
|
||||
let finalSeen = false;
|
||||
let catalogSize = 0;
|
||||
let schemasChecked = 0;
|
||||
let artifactDigest;
|
||||
const schemaValidator = new Ajv2020({ strict: false, validateFormats: false });
|
||||
const extractEvidence = (value) => {
|
||||
if (typeof value === "string") {
|
||||
try {
|
||||
return extractEvidence(JSON.parse(value));
|
||||
} catch {
|
||||
return undefined;
|
||||
}
|
||||
}
|
||||
if (value && typeof value === "object") {
|
||||
if (
|
||||
typeof value.evidence_id === "string" &&
|
||||
value.normalized_result?.graph?.nodes?.length > 0
|
||||
)
|
||||
return value;
|
||||
for (const nested of Object.values(value)) {
|
||||
const evidence = extractEvidence(nested);
|
||||
if (evidence) return evidence;
|
||||
}
|
||||
}
|
||||
return undefined;
|
||||
};
|
||||
const fixture = await createOpenAiModelFixture({
|
||||
directory: lab,
|
||||
prefix: "opencode",
|
||||
onRequest: async ({ body, tools, requestIndex }) => {
|
||||
// Native session-title requests do not execute the analyst's workflow.
|
||||
if (tools.length === 0)
|
||||
return { role: "assistant", content: "REA fixture title" };
|
||||
const analysis = tools.find((t) =>
|
||||
t.name.endsWith("analyze_javascript_application"),
|
||||
);
|
||||
assert(analysis, "OpenCode must expose the REA analysis tool");
|
||||
const prefix = analysis.name.slice(
|
||||
0,
|
||||
-"analyze_javascript_application".length,
|
||||
);
|
||||
const expected = TOOL_CONTRACTS.map((t) => prefix + t.name).sort();
|
||||
const reaTools = tools.filter((t) => expected.includes(t.name));
|
||||
assert.deepEqual(
|
||||
reaTools.map((t) => t.name).sort(),
|
||||
expected,
|
||||
"OpenCode must forward the complete REA catalog",
|
||||
);
|
||||
catalogSize = expected.length;
|
||||
if (schemasChecked === 0) {
|
||||
for (const tool of reaTools) {
|
||||
assert(
|
||||
tool.parameters,
|
||||
`${tool.name}: missing advertised input schema`,
|
||||
);
|
||||
assert(
|
||||
schemaValidator.validateSchema(tool.parameters),
|
||||
`${tool.name}: invalid input schema: ${JSON.stringify(schemaValidator.errors)}`,
|
||||
);
|
||||
schemasChecked++;
|
||||
}
|
||||
}
|
||||
const replies = body.messages.filter((m) => m.role === "tool");
|
||||
skillLoaded ||= replies.some(
|
||||
(m) =>
|
||||
typeof m.content === "string" &&
|
||||
expectedSkillBody !== undefined &&
|
||||
m.content.includes(skillDirectory) &&
|
||||
m.content.includes(expectedSkillBody),
|
||||
);
|
||||
const observed = extractEvidence(replies);
|
||||
if (observed) {
|
||||
const evidence = toolContract(
|
||||
"analyze_javascript_application",
|
||||
).outputSchema.parse(observed);
|
||||
assert.equal(evidence.subject.local_path, target);
|
||||
const shape = evidence.normalized_result.graph.nodes
|
||||
.flatMap((n) => n.observations)
|
||||
.map((o) => o.properties)
|
||||
.find(
|
||||
(p) =>
|
||||
p.semantic_role === "export-return-shapes" &&
|
||||
p.exported_name === "result",
|
||||
);
|
||||
assert(shape?.return_shape_coverage?.projection_complete);
|
||||
const fields = shape.static_return_shapes.flatMap((s) => s.fields);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) =>
|
||||
f.path === "/clientCompatibility" &&
|
||||
f.state === "literal" &&
|
||||
f.value === "REA_CLIENT_FIXTURE",
|
||||
),
|
||||
);
|
||||
assert(
|
||||
fields.some(
|
||||
(f) => f.path === "/count" && f.state === "literal" && f.value === 7,
|
||||
),
|
||||
);
|
||||
const bytes = JSON.stringify(evidence);
|
||||
artifactDigest = createHash("sha256").update(bytes).digest("hex");
|
||||
await writeFile(join(lab, "opencode-evidence.json"), bytes);
|
||||
evidenceSeen = true;
|
||||
}
|
||||
if (mode === "chat" || evidenceSeen) {
|
||||
finalSeen = true;
|
||||
return { role: "assistant", content: "REA_CLIENT_COMPATIBILITY_OK" };
|
||||
}
|
||||
assert(requestIndex <= 8, "Local model workflow exceeded its turn budget");
|
||||
const call = (name, args) => ({
|
||||
role: "assistant",
|
||||
content: null,
|
||||
tool_calls: [
|
||||
{
|
||||
id: `call_rea_fixture_${requestIndex}`,
|
||||
type: "function",
|
||||
function: { name, arguments: JSON.stringify(args) },
|
||||
},
|
||||
],
|
||||
});
|
||||
if (!skillRequested) {
|
||||
const skill = tools.find((t) => t.name === "skill");
|
||||
assert(skill, "OpenCode must expose its native skill tool");
|
||||
skillRequested = true;
|
||||
return call(skill.name, { name: "reverse-engineer-anything" });
|
||||
}
|
||||
assert(skillLoaded, "OpenCode must load the installed personal REA skill");
|
||||
return call(analysis.name, { input_path: target, format: "directory" });
|
||||
},
|
||||
});
|
||||
const original =
|
||||
(configFormat === "jsonc" ? "// Keep caller configuration.\n" : "") +
|
||||
JSON.stringify(
|
||||
{
|
||||
autoupdate: false,
|
||||
skills: { paths: [join(account, ".agents", "skills")] },
|
||||
permission: { "*": "allow" },
|
||||
provider: {
|
||||
"rea-fixture": {
|
||||
npm: "@ai-sdk/openai-compatible",
|
||||
name: "REA local model fixture",
|
||||
options: { baseURL: fixture.baseUrl, apiKey: "local-fixture-key" },
|
||||
models: {
|
||||
"rea-client-fixture": {
|
||||
name: "REA fixture",
|
||||
tool_call: true,
|
||||
limit: { context: 1_000_000, output: 4096 },
|
||||
},
|
||||
},
|
||||
},
|
||||
},
|
||||
mcp: {
|
||||
other: { type: "local", command: ["unrelated-server"], enabled: false },
|
||||
},
|
||||
},
|
||||
null,
|
||||
2,
|
||||
);
|
||||
await writeFile(configPath, original);
|
||||
let failure;
|
||||
try {
|
||||
for (const args of [
|
||||
["setup", "--client", "opencode", "--dry-run"],
|
||||
["setup", "--client", "opencode", "--yes"],
|
||||
["doctor", "--client", "opencode", "--skill"],
|
||||
]) {
|
||||
const result = await exec(
|
||||
process.execPath,
|
||||
[join(runtimeRoot, "scripts/rea.mjs"), ...args, "--json"],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
await writeFile(
|
||||
join(lab, `${args[0]}${args.includes("--dry-run") ? "-plan" : ""}.json`),
|
||||
result.stdout,
|
||||
);
|
||||
const parsed = JSON.parse(result.stdout);
|
||||
if (args[0] === "doctor") assert.equal(parsed.healthy, true);
|
||||
else {
|
||||
assert.equal(
|
||||
parsed.status,
|
||||
args.includes("--dry-run") ? "planned" : "ready",
|
||||
);
|
||||
if (args.includes("--dry-run")) {
|
||||
assert(parsed.plannedActions.some((a) => a.target === configPath));
|
||||
assert(parsed.plannedActions.some((a) => a.target === skillDirectory));
|
||||
assert(
|
||||
parsed.plannedActions.every(
|
||||
(a) =>
|
||||
a.target === configPath || a.target.startsWith(skillDirectory),
|
||||
),
|
||||
);
|
||||
}
|
||||
}
|
||||
}
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
const configured = await readFile(configPath, "utf8");
|
||||
assert(configured.includes("unrelated-server"));
|
||||
if (configFormat === "jsonc")
|
||||
assert(configured.includes("// Keep caller configuration."));
|
||||
const repeated = await exec(
|
||||
process.execPath,
|
||||
[
|
||||
join(runtimeRoot, "scripts/rea.mjs"),
|
||||
"setup",
|
||||
"--client",
|
||||
"opencode",
|
||||
"--yes",
|
||||
"--json",
|
||||
],
|
||||
{ env: environment, cwd: workspace, timeout: 60_000 },
|
||||
);
|
||||
assert.deepEqual(JSON.parse(repeated.stdout).appliedActions, []);
|
||||
assert.equal(await readFile(configPath, "utf8"), configured);
|
||||
assert.equal(await readFile(`${configPath}.rea.backup`, "utf8"), original);
|
||||
const installedSkill = await readFile(
|
||||
join(skillDirectory, "SKILL.md"),
|
||||
"utf8",
|
||||
);
|
||||
assert(installedSkill.includes("name: reverse-engineer-anything"));
|
||||
const skillLines = installedSkill.split("\n");
|
||||
const headerEnd = skillLines.indexOf("---", 1);
|
||||
assert(
|
||||
skillLines[0] === "---" && headerEnd > 0,
|
||||
"Installed skill must have its authored frontmatter",
|
||||
);
|
||||
expectedSkillBody = skillLines
|
||||
.slice(headerEnd + 1)
|
||||
.join("\n")
|
||||
.trim();
|
||||
assert(expectedSkillBody.length > 0);
|
||||
const execution = exec(
|
||||
command,
|
||||
[
|
||||
"run",
|
||||
"--format",
|
||||
"json",
|
||||
"--model",
|
||||
"rea-fixture/rea-client-fixture",
|
||||
mode === "chat"
|
||||
? "Say hello briefly."
|
||||
: `Use REA to analyze the JavaScript directory ${target}. Report the result.`,
|
||||
],
|
||||
{
|
||||
env: environment,
|
||||
cwd: workspace,
|
||||
timeout: 120_000,
|
||||
maxBuffer: 10 * 1024 * 1024,
|
||||
},
|
||||
);
|
||||
execution.child.stdin.end();
|
||||
const response = await execution;
|
||||
await writeFile(join(lab, `${mode}.stdout`), response.stdout);
|
||||
await writeFile(join(lab, `${mode}.stderr`), response.stderr);
|
||||
assert.equal(fixture.failure, undefined);
|
||||
assert(finalSeen && response.stdout.includes("REA_CLIENT_COMPATIBILITY_OK"));
|
||||
if (mode === "call") assert(evidenceSeen && skillLoaded);
|
||||
} catch (cause) {
|
||||
failure = cause;
|
||||
if (typeof cause?.stdout === "string")
|
||||
await writeFile(join(lab, `${mode}.stdout`), cause.stdout);
|
||||
if (typeof cause?.stderr === "string")
|
||||
await writeFile(join(lab, `${mode}.stderr`), cause.stderr);
|
||||
} finally {
|
||||
await fixture.close();
|
||||
const lineage = await completeVerifierRun(verifier);
|
||||
const receipt = {
|
||||
client: "OpenCode",
|
||||
clientVersion,
|
||||
mode,
|
||||
configFormat,
|
||||
passed: failure === undefined,
|
||||
artifacts: lab,
|
||||
runtimeRoot,
|
||||
host: {
|
||||
platform: process.platform,
|
||||
architecture: process.arch,
|
||||
node: process.versions.node,
|
||||
},
|
||||
modelFixture:
|
||||
"loopback custom OpenAI-compatible provider; one-million-token fixture capacity and synthetic usage; no live provider claim",
|
||||
skillDiscovery:
|
||||
"caller-configured isolated shared directory; default OS home discovery unverified",
|
||||
externalPlugins: "disabled through native OPENCODE_PURE",
|
||||
catalogSize,
|
||||
schemasChecked,
|
||||
evidenceSeen,
|
||||
skillLoaded,
|
||||
artifactDigest,
|
||||
finalSeen,
|
||||
requests: fixture.requests,
|
||||
probes: fixture.probes,
|
||||
fixtureFailure: fixture.failure,
|
||||
verifier: lineage,
|
||||
};
|
||||
await writeFile(join(lab, "receipt.json"), JSON.stringify(receipt, null, 2));
|
||||
console.log(JSON.stringify(receipt));
|
||||
}
|
||||
if (failure !== undefined) throw failure;
|
||||
+103
-18
@@ -5,13 +5,79 @@ from pathlib import Path
|
||||
import re
|
||||
import struct
|
||||
import sys
|
||||
from urllib.parse import quote, unquote, urlsplit
|
||||
import unicodedata
|
||||
from urllib.parse import unquote, urlsplit
|
||||
import xml.etree.ElementTree as ET
|
||||
from zipfile import BadZipFile, ZipFile
|
||||
|
||||
from website import NOTES_FIXTURES, SITE_ORIGIN, authored_markdown, page_url, sync_pages
|
||||
|
||||
SITE_ORIGIN = "https://rea.tools"
|
||||
NOTES_FIXTURES = {"examples/notes-electron/index.html", "examples/notes-web/index.html"}
|
||||
LEGACY_ORIGIN = "morluto.github.io"
|
||||
SITE_TEXT_URL = re.compile(
|
||||
r"https?://(?:rea\.tools|morluto\.github\.io)/[^\s<>\"'`]+", re.IGNORECASE
|
||||
)
|
||||
|
||||
|
||||
def markdown_ids(path):
|
||||
"""Collect GitHub heading anchors and explicit HTML IDs in local Markdown."""
|
||||
source = path.read_text(encoding="utf-8")
|
||||
parser = HtmlReferences()
|
||||
parser.feed(source)
|
||||
identifiers = set(parser.ids)
|
||||
counts = {}
|
||||
fenced = False
|
||||
for line in source.splitlines():
|
||||
if line.lstrip().startswith(("```", "~~~")):
|
||||
fenced = not fenced
|
||||
if fenced:
|
||||
continue
|
||||
heading = re.match(r"^ {0,3}#{1,6}\s+(.+?)(?:\s+#+)?\s*$", line)
|
||||
if not heading:
|
||||
continue
|
||||
text = re.sub(r"<[^>]*>", "", heading[1]).lower()
|
||||
slug = "".join(c for c in text if c in "-_ " or unicodedata.category(c)[0] in "LN").replace(" ", "-")
|
||||
count = counts.get(slug, 0)
|
||||
identifiers.add(f"{slug}-{count}" if count else slug)
|
||||
counts[slug] = count + 1
|
||||
return identifiers
|
||||
|
||||
|
||||
def check_repository_links(root):
|
||||
"""Check local links in website Markdown and current-repository source links."""
|
||||
errors = []
|
||||
sources = {}
|
||||
for path in authored_markdown(root):
|
||||
text = re.sub(r"(?ms)^\s*(```|~~~).*?^\s*\1[^\n]*$", "", path.read_text(encoding="utf-8"))
|
||||
text = re.sub(r"`[^`]*`", "", text)
|
||||
sources[path] = re.findall(r"\[[^\]\n]*\]\(([^\s)]+)\)", text)
|
||||
for path in sorted((root / "website/public").rglob("*.html")):
|
||||
parser = HtmlReferences()
|
||||
parser.feed(path.read_text(encoding="utf-8"))
|
||||
sources[path] = parser.references
|
||||
for path, references in sources.items():
|
||||
for reference in references:
|
||||
try:
|
||||
url = urlsplit(reference)
|
||||
except ValueError as error:
|
||||
errors.append(f"{path.relative_to(root)}: invalid URL {reference!r}: {error}")
|
||||
continue
|
||||
if url.hostname == LEGACY_ORIGIN and (url.path == "/rea" or url.path.startswith("/rea/")):
|
||||
errors.append(f"{path.relative_to(root)}: obsolete website URL: {reference}")
|
||||
continue
|
||||
if url.hostname == "github.com":
|
||||
match = re.match(r"^/morluto/rea/(?:blob|tree)/main/(.+)$", url.path)
|
||||
if not match:
|
||||
continue
|
||||
target = (root / unquote(match[1])).resolve()
|
||||
elif url.scheme or url.netloc or path.suffix == ".html":
|
||||
continue
|
||||
else:
|
||||
target = (path.parent / unquote(url.path)).resolve() if url.path else path
|
||||
if not target.is_relative_to(root) or not target.exists():
|
||||
errors.append(f"{path.relative_to(root)}: missing repository target: {reference}")
|
||||
elif target.suffix == ".md" and url.fragment and unquote(url.fragment) not in markdown_ids(target):
|
||||
errors.append(f"{path.relative_to(root)}: missing Markdown fragment: {reference}")
|
||||
return errors
|
||||
|
||||
|
||||
class HtmlReferences(HTMLParser):
|
||||
@@ -30,6 +96,8 @@ class HtmlReferences(HTMLParser):
|
||||
self.canonicals = []
|
||||
self.lang = None
|
||||
self.h1_count = 0
|
||||
self.text = []
|
||||
self.copy_targets = []
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
attributes = dict(attrs)
|
||||
@@ -67,6 +135,8 @@ class HtmlReferences(HTMLParser):
|
||||
reference = attributes.get(attribute)
|
||||
if reference is not None:
|
||||
self.references.append(reference)
|
||||
if attributes.get("data-copy"):
|
||||
self.copy_targets.append(attributes["data-copy"])
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag == "head":
|
||||
@@ -75,6 +145,7 @@ class HtmlReferences(HTMLParser):
|
||||
self.in_title = False
|
||||
|
||||
def handle_data(self, data):
|
||||
self.text.append(data)
|
||||
if self.in_title:
|
||||
self.titles[-1] += data
|
||||
|
||||
@@ -104,15 +175,7 @@ def check_search_metadata(site, pages):
|
||||
)
|
||||
if page.noindex():
|
||||
continue
|
||||
route = (
|
||||
path.relative_to(site).parent.as_posix()
|
||||
if path.name == "index.html"
|
||||
else label
|
||||
)
|
||||
route = "" if route == "." else route
|
||||
url = f"{SITE_ORIGIN}/{quote(route, safe='/')}" + (
|
||||
"/" if route and path.name == "index.html" else ""
|
||||
)
|
||||
url = page_url(site, path)
|
||||
indexable.add(url)
|
||||
if page.canonicals != [url]:
|
||||
errors.append(f"{label}: needs exactly one head canonical for {url}")
|
||||
@@ -233,15 +296,32 @@ def check_site(site):
|
||||
label = path.relative_to(site)
|
||||
for identifier in page.duplicate_ids:
|
||||
errors.append(f"{label}: duplicate ID {identifier!r}")
|
||||
for reference in page.references:
|
||||
url = urlsplit(reference)
|
||||
if url.scheme or url.netloc:
|
||||
for identifier in page.copy_targets:
|
||||
if identifier not in page.ids:
|
||||
errors.append(f"{label}: missing copy target: {identifier}")
|
||||
text_urls = [match.group().rstrip(".,;)") for match in SITE_TEXT_URL.finditer(" ".join(page.text))]
|
||||
for reference in page.references + text_urls:
|
||||
try:
|
||||
url = urlsplit(reference)
|
||||
except ValueError as error:
|
||||
errors.append(f"{label}: invalid URL {reference!r}: {error}")
|
||||
continue
|
||||
references += 1
|
||||
if url.path.startswith("/"):
|
||||
if url.hostname == LEGACY_ORIGIN and (url.path == "/rea" or url.path.startswith("/rea/")):
|
||||
errors.append(f"{label}: obsolete website URL: {reference}; use rea.tools")
|
||||
continue
|
||||
if url.hostname == "rea.tools":
|
||||
if url.scheme != "https" or url.netloc != "rea.tools":
|
||||
errors.append(f"{label}: website URL must use {SITE_ORIGIN}: {reference}")
|
||||
continue
|
||||
target = (site / unquote(url.path).lstrip("/")).resolve()
|
||||
elif url.scheme or url.netloc:
|
||||
continue
|
||||
elif url.path.startswith("/"):
|
||||
errors.append(f"{label}: use a relative site reference: {reference}")
|
||||
continue
|
||||
target = (path.parent / unquote(url.path)).resolve() if url.path else path
|
||||
else:
|
||||
target = (path.parent / unquote(url.path)).resolve() if url.path else path
|
||||
references += 1
|
||||
if not target.is_relative_to(site):
|
||||
errors.append(f"{label}: reference leaves the website: {reference}")
|
||||
continue
|
||||
@@ -323,6 +403,11 @@ def main():
|
||||
pages, references, indexable, errors = check_site(root / "website/public")
|
||||
errors.extend(check_example_archive(root / "website/public"))
|
||||
errors.extend(check_publisher(root))
|
||||
errors.extend(check_repository_links(root))
|
||||
try:
|
||||
sync_pages(root, check=True)
|
||||
except (OSError, ValueError, KeyError) as error:
|
||||
errors.append(str(error))
|
||||
if errors:
|
||||
print("Website checks failed:\n" + "\n".join(errors), file=sys.stderr)
|
||||
return 1
|
||||
|
||||
@@ -0,0 +1,158 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createServer } from "node:http";
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
/** Exercise native Anthropic adapters locally, without live-provider claims. */
|
||||
export const createAnthropicModelFixture = async ({ directory, onRequest }) => {
|
||||
const requests = [];
|
||||
const probes = [];
|
||||
let incoming = 0;
|
||||
let failure;
|
||||
const server = createServer(async (request, response) => {
|
||||
try {
|
||||
const chunks = [];
|
||||
let bytes = 0;
|
||||
for await (const chunk of request) {
|
||||
bytes += chunk.length;
|
||||
assert(
|
||||
bytes <= 10 * 1024 * 1024,
|
||||
"Model fixture request exceeds 10 MiB budget",
|
||||
);
|
||||
chunks.push(chunk);
|
||||
}
|
||||
const raw = Buffer.concat(chunks).toString("utf8");
|
||||
const body = raw.length === 0 ? null : JSON.parse(raw);
|
||||
const path = new URL(request.url, "http://localhost").pathname;
|
||||
// Retain producer bodies and URLs, without transport authentication headers.
|
||||
await writeFile(
|
||||
join(directory, `claude-incoming-${++incoming}.json`),
|
||||
JSON.stringify({ method: request.method, path: request.url, body }),
|
||||
);
|
||||
if (path === "/v1/messages/count_tokens") {
|
||||
probes.push({ path, kind: "synthetic-token-count" });
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(JSON.stringify({ input_tokens: 100 }));
|
||||
return;
|
||||
}
|
||||
if (path !== "/v1/messages") {
|
||||
probes.push({ path, status: 404 });
|
||||
response.statusCode = 404;
|
||||
response.end(
|
||||
JSON.stringify({
|
||||
error: { message: "Unsupported fixture endpoint" },
|
||||
}),
|
||||
);
|
||||
return;
|
||||
}
|
||||
assert.equal(request.method, "POST");
|
||||
assert(body && typeof body === "object" && !Array.isArray(body));
|
||||
assert(Array.isArray(body.messages));
|
||||
const tools = body.tools ?? [];
|
||||
requests.push({
|
||||
path: request.url,
|
||||
stream: body.stream,
|
||||
tools: tools.map((t) => t.name),
|
||||
messageRoles: body.messages.map((m) => m.role),
|
||||
});
|
||||
const content = await onRequest({
|
||||
body,
|
||||
tools,
|
||||
requestIndex: requests.length,
|
||||
});
|
||||
const stopReason = content.some((c) => c.type === "tool_use")
|
||||
? "tool_use"
|
||||
: "end_turn";
|
||||
const usage = {
|
||||
input_tokens: 100,
|
||||
output_tokens: 20,
|
||||
cache_creation_input_tokens: 0,
|
||||
cache_read_input_tokens: 0,
|
||||
};
|
||||
const result = {
|
||||
id: `msg_rea_${requests.length}`,
|
||||
type: "message",
|
||||
role: "assistant",
|
||||
model: body.model,
|
||||
content,
|
||||
stop_reason: stopReason,
|
||||
stop_sequence: null,
|
||||
usage,
|
||||
};
|
||||
if (body.stream) {
|
||||
response.setHeader("Content-Type", "text/event-stream");
|
||||
const emit = (event, data) =>
|
||||
response.write(
|
||||
`event: ${event}\ndata: ${JSON.stringify({ type: event, ...data })}\n\n`,
|
||||
);
|
||||
emit("message_start", {
|
||||
message: {
|
||||
...result,
|
||||
content: [],
|
||||
stop_reason: null,
|
||||
usage: { ...usage, output_tokens: 0 },
|
||||
},
|
||||
});
|
||||
for (const [index, block] of content.entries()) {
|
||||
emit("content_block_start", {
|
||||
index,
|
||||
content_block:
|
||||
block.type === "tool_use"
|
||||
? { ...block, input: {} }
|
||||
: { type: "text", text: "" },
|
||||
});
|
||||
if (block.type === "tool_use") {
|
||||
const json = JSON.stringify(block.input);
|
||||
const split = Math.floor(json.length / 2);
|
||||
for (const partialJson of [
|
||||
json.slice(0, split),
|
||||
json.slice(split),
|
||||
]) {
|
||||
emit("content_block_delta", {
|
||||
index,
|
||||
delta: { type: "input_json_delta", partial_json: partialJson },
|
||||
});
|
||||
}
|
||||
} else {
|
||||
emit("content_block_delta", {
|
||||
index,
|
||||
delta: { type: "text_delta", text: block.text },
|
||||
});
|
||||
}
|
||||
emit("content_block_stop", { index });
|
||||
}
|
||||
emit("message_delta", {
|
||||
delta: { stop_reason: stopReason, stop_sequence: null },
|
||||
usage: { output_tokens: 20 },
|
||||
});
|
||||
emit("message_stop", {});
|
||||
response.end();
|
||||
} else {
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(JSON.stringify(result));
|
||||
}
|
||||
} catch (cause) {
|
||||
failure = String(cause);
|
||||
response.statusCode = 400;
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(
|
||||
JSON.stringify({
|
||||
type: "error",
|
||||
error: { type: "invalid_request_error", message: failure },
|
||||
}),
|
||||
);
|
||||
}
|
||||
});
|
||||
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
|
||||
const address = server.address();
|
||||
assert(address !== null && typeof address !== "string");
|
||||
return {
|
||||
baseUrl: `http://127.0.0.1:${address.port}`,
|
||||
requests,
|
||||
probes,
|
||||
get failure() {
|
||||
return failure;
|
||||
},
|
||||
close: () => new Promise((resolve) => server.close(resolve)),
|
||||
};
|
||||
};
|
||||
@@ -0,0 +1,104 @@
|
||||
import assert from "node:assert/strict";
|
||||
import { createServer } from "node:http";
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
/** Exercise the native Gemini API adapter against a local model, without cloud claims. */
|
||||
export const createGeminiModelFixture = async ({ directory, onRequest }) => {
|
||||
const requests = [];
|
||||
const probes = [];
|
||||
let incoming = 0;
|
||||
let failure;
|
||||
const server = createServer(async (request, response) => {
|
||||
try {
|
||||
const chunks = [];
|
||||
let bytes = 0;
|
||||
for await (const chunk of request) {
|
||||
bytes += chunk.length;
|
||||
assert(
|
||||
bytes <= 10 * 1024 * 1024,
|
||||
"Model fixture request exceeds 10 MiB budget",
|
||||
);
|
||||
chunks.push(chunk);
|
||||
}
|
||||
const raw = Buffer.concat(chunks).toString("utf8");
|
||||
const body = raw.length === 0 ? null : JSON.parse(raw);
|
||||
await writeFile(
|
||||
join(directory, `gemini-incoming-${++incoming}.json`),
|
||||
JSON.stringify({ method: request.method, path: request.url, body }),
|
||||
);
|
||||
const path = new URL(request.url, "http://localhost").pathname;
|
||||
if (path.endsWith(":countTokens")) {
|
||||
probes.push({ path, kind: "synthetic-token-count" });
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(JSON.stringify({ totalTokens: 100 }));
|
||||
return;
|
||||
}
|
||||
if (
|
||||
!/\/models\/[^/]+:(?:streamGenerateContent|generateContent)$/u.test(
|
||||
path,
|
||||
)
|
||||
) {
|
||||
probes.push({ path, status: 404 });
|
||||
response.statusCode = 404;
|
||||
response.end(
|
||||
JSON.stringify({
|
||||
error: { message: "Unsupported fixture endpoint" },
|
||||
}),
|
||||
);
|
||||
return;
|
||||
}
|
||||
assert.equal(request.method, "POST");
|
||||
assert(body && typeof body === "object" && !Array.isArray(body));
|
||||
assert(Array.isArray(body.contents));
|
||||
const tools = (body.tools ?? []).flatMap(
|
||||
(t) => t.functionDeclarations ?? [],
|
||||
);
|
||||
requests.push({
|
||||
path,
|
||||
tools: tools.map((t) => t.name),
|
||||
contentRoles: body.contents.map((c) => c.role),
|
||||
});
|
||||
const parts = await onRequest({
|
||||
body,
|
||||
tools,
|
||||
requestIndex: requests.length,
|
||||
});
|
||||
const result = {
|
||||
candidates: [
|
||||
{ index: 0, content: { role: "model", parts }, finishReason: "STOP" },
|
||||
],
|
||||
usageMetadata: {
|
||||
promptTokenCount: 100,
|
||||
candidatesTokenCount: 20,
|
||||
totalTokenCount: 120,
|
||||
},
|
||||
modelVersion: "local-rea-fixture",
|
||||
};
|
||||
if (path.endsWith(":streamGenerateContent")) {
|
||||
response.setHeader("Content-Type", "text/event-stream");
|
||||
response.end(`data: ${JSON.stringify(result)}\n\n`);
|
||||
} else {
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(JSON.stringify(result));
|
||||
}
|
||||
} catch (cause) {
|
||||
failure = String(cause);
|
||||
response.statusCode = 400;
|
||||
response.setHeader("Content-Type", "application/json");
|
||||
response.end(JSON.stringify({ error: { message: failure, code: 400 } }));
|
||||
}
|
||||
});
|
||||
await new Promise((resolve) => server.listen(0, "127.0.0.1", resolve));
|
||||
const address = server.address();
|
||||
assert(address !== null && typeof address !== "string");
|
||||
return {
|
||||
baseUrl: `http://127.0.0.1:${address.port}`,
|
||||
requests,
|
||||
probes,
|
||||
get failure() {
|
||||
return failure;
|
||||
},
|
||||
close: () => new Promise((resolve) => server.close(resolve)),
|
||||
};
|
||||
};
|
||||
@@ -88,7 +88,10 @@ window.loadFile("renderer.html");require("node:fs").writeFileSync(${JSON.stringi
|
||||
ajv.compile(tool.inputSchema);
|
||||
return [
|
||||
tool.name,
|
||||
tool.outputSchema ? ajv.compile(tool.outputSchema) : undefined,
|
||||
tool.outputSchema
|
||||
? (tool.outputSchema.$id && ajv.getSchema(tool.outputSchema.$id)) ||
|
||||
ajv.compile(tool.outputSchema)
|
||||
: undefined,
|
||||
];
|
||||
}),
|
||||
);
|
||||
|
||||
@@ -0,0 +1,246 @@
|
||||
"""Maintain shared HTML and run the static website's contributor commands."""
|
||||
|
||||
import argparse
|
||||
from functools import partial
|
||||
from html import escape
|
||||
from html.parser import HTMLParser
|
||||
from http.server import SimpleHTTPRequestHandler, ThreadingHTTPServer
|
||||
from pathlib import Path, PurePosixPath
|
||||
from string import Template
|
||||
import subprocess
|
||||
import sys
|
||||
from textwrap import indent
|
||||
from urllib.parse import quote, urlsplit
|
||||
|
||||
|
||||
SITE_ORIGIN = "https://rea.tools"
|
||||
NOTES_FIXTURES = {"examples/notes-electron/index.html", "examples/notes-web/index.html"}
|
||||
NAVIGATION = (
|
||||
("Showcases", "showcase/"),
|
||||
("Blog", "blog/"),
|
||||
("Get started", "get-started/"),
|
||||
("Guides", "guides/"),
|
||||
("FAQ", "faq/"),
|
||||
)
|
||||
|
||||
|
||||
def authored_markdown(root):
|
||||
"""Discover website documentation while excluding local environments and vendors."""
|
||||
site = root / "website"
|
||||
return [
|
||||
path for path in sorted(site.rglob("*.md"))
|
||||
if not any(part.startswith(".") or part in ("node_modules", "__pycache__")
|
||||
for part in path.relative_to(site).parts)
|
||||
]
|
||||
|
||||
|
||||
class PageMetadata(HTMLParser):
|
||||
"""Read the authored title, description and indexing policy from the head."""
|
||||
|
||||
def __init__(self):
|
||||
super().__init__()
|
||||
self.in_head = False
|
||||
self.in_title = False
|
||||
self.titles = []
|
||||
self.descriptions = []
|
||||
self.noindex = False
|
||||
|
||||
def handle_starttag(self, tag, attrs):
|
||||
if tag == "head":
|
||||
self.in_head = True
|
||||
if not self.in_head:
|
||||
return
|
||||
if tag == "title":
|
||||
self.in_title = True
|
||||
self.titles.append("")
|
||||
if tag == "meta":
|
||||
attributes = dict(attrs)
|
||||
name = (attributes.get("name") or "").lower()
|
||||
content = attributes.get("content") or ""
|
||||
if name == "description":
|
||||
self.descriptions.append(content)
|
||||
if name in ("robots", "googlebot"):
|
||||
self.noindex |= bool(
|
||||
set(content.lower().replace(",", " ").split()) & {"noindex", "none"}
|
||||
)
|
||||
|
||||
def handle_endtag(self, tag):
|
||||
if tag == "head":
|
||||
self.in_head = False
|
||||
if tag == "title":
|
||||
self.in_title = False
|
||||
|
||||
def handle_data(self, data):
|
||||
if self.in_title:
|
||||
self.titles[-1] += data
|
||||
|
||||
|
||||
def page_route(site, path):
|
||||
"""Map an HTML file to its public route without a separate page registry."""
|
||||
route = path.relative_to(site).as_posix()
|
||||
return route.removesuffix("index.html") if path.name == "index.html" else route
|
||||
|
||||
|
||||
def page_url(site, path):
|
||||
"""Return the canonical public URL of an authored HTML file."""
|
||||
return f"{SITE_ORIGIN}/{quote(page_route(site, path), safe='/')}"
|
||||
|
||||
|
||||
def shared_blocks(root, path, source):
|
||||
"""Render shared regions while keeping the page's body and metadata authored."""
|
||||
site = root / "website/public"
|
||||
metadata = PageMetadata()
|
||||
metadata.feed(source)
|
||||
for name, values in (("title", metadata.titles), ("description", metadata.descriptions)):
|
||||
if len(values) != 1 or not values[0].strip():
|
||||
raise ValueError(f"{path.relative_to(site)}: needs one nonempty head {name}")
|
||||
depth = len(path.relative_to(site).parent.parts)
|
||||
base = "../" * depth or "./"
|
||||
route = page_route(site, path)
|
||||
links = []
|
||||
for label, destination in NAVIGATION:
|
||||
attributes = ' class="nav-start"' if destination == "get-started/" else ""
|
||||
if route.startswith(destination):
|
||||
attributes += ' aria-current="page"'
|
||||
links.append(f' <a href="{base}{destination}"{attributes}>{label}</a>')
|
||||
values = {
|
||||
"base": base,
|
||||
"navigation": "\n" + "\n".join(links) + "\n ",
|
||||
"canonical": escape(page_url(site, path), quote=True),
|
||||
"origin": SITE_ORIGIN,
|
||||
"title": escape(metadata.titles[0].strip(), quote=True),
|
||||
"description": escape(metadata.descriptions[0].strip(), quote=True),
|
||||
}
|
||||
templates = root / "website/templates"
|
||||
return {
|
||||
name: indent(Template((templates / f"{name}.html.tmpl").read_text(encoding="utf-8")).substitute(values), " ")
|
||||
for name in ("sharing", "header", "footer")
|
||||
}
|
||||
|
||||
|
||||
def sync_pages(root, check=False):
|
||||
"""Update shared regions, or reject drift without changing any authored file."""
|
||||
site = root / "website/public"
|
||||
changes = []
|
||||
for path in sorted(site.rglob("*.html")):
|
||||
if path.relative_to(site).as_posix() in NOTES_FIXTURES:
|
||||
continue
|
||||
original = path.read_text(encoding="utf-8")
|
||||
source = original
|
||||
for name, block in shared_blocks(root, path, source).items():
|
||||
start = f" <!-- website:{name}:start -->\n"
|
||||
end = f" <!-- website:{name}:end -->"
|
||||
if source.count(start) != 1 or source.count(end) != 1:
|
||||
raise ValueError(f"{path.relative_to(site)}: needs one {name} region; use new-page for a new reading page")
|
||||
before, _, remaining = source.partition(start)
|
||||
_, found, after = remaining.partition(end)
|
||||
if not found:
|
||||
raise ValueError(f"{path.relative_to(site)}: {name} region is out of order")
|
||||
source = before + start + block + end + after
|
||||
if source != original:
|
||||
changes.append((path, source))
|
||||
if check and changes:
|
||||
names = ", ".join(str(path.relative_to(site)) for path, _ in changes)
|
||||
raise ValueError(f"Shared HTML is stale: {names}. Run python3 scripts/website.py sync and commit the updated pages.")
|
||||
if not check:
|
||||
for path, source in changes:
|
||||
path.write_text(source, encoding="utf-8")
|
||||
print(f"{'Checked' if check else 'Synced'} shared HTML ({len(changes)} pages changed).")
|
||||
return [path for path, _ in changes]
|
||||
|
||||
|
||||
def new_page(root, route, title, description):
|
||||
"""Create a draft reading page with correct depth, metadata and shared regions."""
|
||||
parts = PurePosixPath(route)
|
||||
if not route or parts.is_absolute() or ".." in parts.parts or "\\" in route or parts.suffix:
|
||||
raise ValueError("Use a relative directory route, such as blog/my-article.")
|
||||
site = root / "website/public"
|
||||
path = site.joinpath(*parts.parts, "index.html")
|
||||
if not path.resolve().is_relative_to(site.resolve()):
|
||||
raise ValueError("The new page must stay inside website/public.")
|
||||
if path.exists():
|
||||
raise ValueError(f"Page already exists: {path.relative_to(site)}")
|
||||
base = "../" * len(parts.parts) or "./"
|
||||
source = Template((root / "website/templates/page.html").read_text(encoding="utf-8")).substitute(
|
||||
title=escape(title, quote=True), description=escape(description, quote=True), base=base,
|
||||
)
|
||||
# Render before writing, so invalid input cannot leave an incomplete page.
|
||||
blocks = shared_blocks(root, path, source)
|
||||
for name, block in blocks.items():
|
||||
source = source.replace(f" <!-- website:{name}:start -->\n", f" <!-- website:{name}:start -->\n{block}")
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
path.write_text(source, encoding="utf-8")
|
||||
print(f"Created {path.relative_to(root)}. Write the page, add its index link, then remove the Draft label and noindex directive when ready.")
|
||||
return path
|
||||
|
||||
|
||||
def run_script(root, name, arguments=()):
|
||||
"""Use the active Python environment for the existing preparation and checks."""
|
||||
subprocess.run([sys.executable, str(root / "scripts" / name), *arguments], cwd=root, check=True)
|
||||
|
||||
|
||||
def preview_handler(site, prefix):
|
||||
"""Serve one static directory at root or a Pages prefix, preserving redirects."""
|
||||
class Handler(SimpleHTTPRequestHandler):
|
||||
def send_head(self):
|
||||
if not urlsplit(self.path).path.startswith(prefix):
|
||||
self.send_error(404)
|
||||
return None
|
||||
return super().send_head()
|
||||
|
||||
def translate_path(self, path):
|
||||
return super().translate_path("/" + path[len(prefix):])
|
||||
|
||||
return partial(Handler, directory=str(site))
|
||||
|
||||
|
||||
def main():
|
||||
"""Expose one small command for synchronizing, checking and previewing the site."""
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
commands = parser.add_subparsers(dest="command", required=True)
|
||||
sync = commands.add_parser("sync", help="Update shared HTML after editing templates or page metadata")
|
||||
sync.add_argument("--check", action="store_true", help="Report drift without rewriting pages")
|
||||
commands.add_parser("check", help="Check shared HTML, prepare assets, verify links and run regression tests")
|
||||
links = commands.add_parser("links", help="Audit external targets using gh and HTTP; separate from offline checks")
|
||||
links.add_argument("--report", help="Write the full external-link JSON report")
|
||||
create = commands.add_parser("new-page", help="Create a draft reading page")
|
||||
create.add_argument("route")
|
||||
create.add_argument("--title", required=True)
|
||||
create.add_argument("--description", required=True)
|
||||
serve = commands.add_parser("serve", help="Prepare and preview the static site")
|
||||
serve.add_argument("--port", type=int, default=4173)
|
||||
serve.add_argument("--base-path", choices=("/", "/rea/"), default="/")
|
||||
args = parser.parse_args()
|
||||
root = Path(__file__).resolve().parent.parent
|
||||
try:
|
||||
if args.command == "new-page":
|
||||
new_page(root, args.route, args.title, args.description)
|
||||
elif args.command == "sync":
|
||||
sync_pages(root, check=args.check)
|
||||
elif args.command == "check":
|
||||
sync_pages(root, check=True)
|
||||
for name in ("prepare-website.py", "verify-website.py", "test-website.py"):
|
||||
run_script(root, name)
|
||||
elif args.command == "links":
|
||||
run_script(root, "audit-website-links.py", ["--report", args.report] if args.report else [])
|
||||
else:
|
||||
sync_pages(root)
|
||||
run_script(root, "prepare-website.py")
|
||||
prefix = args.base_path
|
||||
|
||||
handler = preview_handler(root / "website/public", prefix)
|
||||
with ThreadingHTTPServer(("127.0.0.1", args.port), handler) as server:
|
||||
print(f"Preview: http://127.0.0.1:{server.server_port}{prefix}", flush=True)
|
||||
server.serve_forever()
|
||||
except (OSError, ValueError, KeyError) as error:
|
||||
print(str(error), file=sys.stderr)
|
||||
return 1
|
||||
except subprocess.CalledProcessError as error:
|
||||
return error.returncode
|
||||
except KeyboardInterrupt:
|
||||
return 0
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,150 @@
|
||||
import { lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
|
||||
import {
|
||||
basename,
|
||||
dirname,
|
||||
isAbsolute,
|
||||
join,
|
||||
relative,
|
||||
resolve,
|
||||
sep,
|
||||
} from "node:path";
|
||||
|
||||
/** An unresolved Hermes profile must not be configured as the default home. */
|
||||
export class HermesClientPathError extends Error {
|
||||
constructor(
|
||||
readonly path: string,
|
||||
message: string,
|
||||
) {
|
||||
super(message);
|
||||
this.name = "HermesClientPathError";
|
||||
}
|
||||
}
|
||||
|
||||
const defaultDirectory = (
|
||||
home: string,
|
||||
platform: NodeJS.Platform,
|
||||
env: Readonly<NodeJS.ProcessEnv>,
|
||||
): string => {
|
||||
const suffix = env.HERMES_DATA_DIR_SUFFIX ?? "";
|
||||
return platform === "win32"
|
||||
? join(
|
||||
env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"),
|
||||
`hermes${suffix}`,
|
||||
)
|
||||
: join(home, `.hermes${suffix}`);
|
||||
};
|
||||
const expandedDirectory = (
|
||||
home: string,
|
||||
platform: NodeJS.Platform,
|
||||
env: Readonly<NodeJS.ProcessEnv>,
|
||||
): string | undefined => {
|
||||
const override = env.HERMES_HOME?.trim();
|
||||
if (!override) return undefined;
|
||||
const variables = override.replace(
|
||||
/\$(\w+|\{[^}]*\})/gu,
|
||||
(match, variable: string) => {
|
||||
const key = variable.startsWith("{") ? variable.slice(1, -1) : variable;
|
||||
return env[key] ?? match;
|
||||
},
|
||||
);
|
||||
const expanded =
|
||||
platform === "win32"
|
||||
? variables.replace(
|
||||
/%([^%]+)%/gu,
|
||||
(match, variable: string) => env[variable] ?? match,
|
||||
)
|
||||
: variables;
|
||||
if (expanded === "~") return home;
|
||||
if (
|
||||
expanded.startsWith("~/") ||
|
||||
(platform === "win32" && expanded.startsWith("~\\"))
|
||||
)
|
||||
return join(home, expanded.slice(2));
|
||||
return resolve(expanded);
|
||||
};
|
||||
const physicalPath = (path: string): string => {
|
||||
try {
|
||||
return realpathSync(path);
|
||||
} catch {
|
||||
return resolve(path);
|
||||
}
|
||||
};
|
||||
const within = (root: string, path: string): boolean => {
|
||||
const difference = relative(physicalPath(root), physicalPath(path));
|
||||
return (
|
||||
difference === "" ||
|
||||
(!isAbsolute(difference) &&
|
||||
difference !== ".." &&
|
||||
!difference.startsWith(`..${sep}`))
|
||||
);
|
||||
};
|
||||
const PROFILE_MARKERS = [
|
||||
"config.yaml",
|
||||
".env",
|
||||
"SOUL.md",
|
||||
"profile.yaml",
|
||||
"auth.json",
|
||||
"state.db",
|
||||
];
|
||||
const RESERVED_PROFILES = new Set(["hermes", "test", "tmp", "root", "sudo"]);
|
||||
const liveProfile = (path: string): boolean => {
|
||||
try {
|
||||
if (!statSync(path).isDirectory()) return false;
|
||||
try {
|
||||
statSync(join(dirname(path), ".deleted", basename(path)));
|
||||
return false;
|
||||
} catch {
|
||||
/* No tombstone. */
|
||||
}
|
||||
return PROFILE_MARKERS.some((marker) => {
|
||||
try {
|
||||
const status = lstatSync(join(path, marker));
|
||||
return status.isFile() || status.isSymbolicLink();
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
});
|
||||
} catch {
|
||||
return false;
|
||||
}
|
||||
};
|
||||
|
||||
/** Match Hermes CLI sticky-profile selection while retaining the configured path spelling. */
|
||||
export const resolveHermesClientHome = (
|
||||
home: string,
|
||||
platform: NodeJS.Platform,
|
||||
env: Readonly<NodeJS.ProcessEnv>,
|
||||
): string => {
|
||||
const native = defaultDirectory(home, platform, env);
|
||||
const root = expandedDirectory(home, platform, env) ?? native;
|
||||
// An explicit named profile bypasses the root's sticky selection in Hermes CLI.
|
||||
if (basename(dirname(root)) === "profiles") return root;
|
||||
const stickyRoot = within(native, root) ? native : root;
|
||||
let name: string;
|
||||
try {
|
||||
// Python uses utf-8-sig and ignores unreadable / invalid-UTF8 active_profile files.
|
||||
name = new TextDecoder("utf-8", { fatal: true })
|
||||
.decode(readFileSync(join(stickyRoot, "active_profile")))
|
||||
.trim();
|
||||
} catch {
|
||||
return root;
|
||||
}
|
||||
if (name === "" || name === "default") return root;
|
||||
const canonical = name.toLowerCase();
|
||||
if (canonical === "default") return root;
|
||||
if (
|
||||
!/^[a-z0-9][a-z0-9_-]{0,63}$/u.test(canonical) ||
|
||||
RESERVED_PROFILES.has(canonical)
|
||||
)
|
||||
throw new HermesClientPathError(
|
||||
join(stickyRoot, "active_profile"),
|
||||
`Invalid saved Hermes profile ${JSON.stringify(name)}. Run 'hermes profile use default' or repair active_profile.`,
|
||||
);
|
||||
const selected = join(root, "profiles", canonical);
|
||||
if (!liveProfile(selected))
|
||||
throw new HermesClientPathError(
|
||||
selected,
|
||||
`Saved Hermes profile ${JSON.stringify(name)} is missing, deleted, or has no profile identity. Run 'hermes profile use default' or restore that profile before configuring it.`,
|
||||
);
|
||||
return selected;
|
||||
};
|
||||
@@ -0,0 +1,33 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import { createProgressReporter } from "./ProgressReporter.js";
|
||||
|
||||
it("limits intermediate sends to 100 ms and always delivers terminal status", async () => {
|
||||
let now = 0;
|
||||
const sent: number[] = [];
|
||||
const reporter = createProgressReporter(
|
||||
async () => {
|
||||
sent.push(now);
|
||||
},
|
||||
{ now: () => now },
|
||||
);
|
||||
for (const [completed, elapsed] of [0, 25, 50, 99, 100, 199, 200].entries()) {
|
||||
now = elapsed;
|
||||
await reporter.report({
|
||||
phase: "running",
|
||||
completed,
|
||||
total: null,
|
||||
message: "Observed capture status",
|
||||
});
|
||||
}
|
||||
expect(sent).toEqual([0, 100, 200]);
|
||||
now = 201;
|
||||
await reporter.report({
|
||||
phase: "cleanup",
|
||||
completed: 7,
|
||||
total: null,
|
||||
message: "Owned cleanup complete",
|
||||
terminal: true,
|
||||
});
|
||||
expect(sent).toEqual([0, 100, 200, 201]);
|
||||
});
|
||||
@@ -1,6 +1,10 @@
|
||||
import { dirname, isAbsolute, join, resolve, win32 } from "node:path";
|
||||
import { fileURLToPath } from "node:url";
|
||||
import { lstatSync } from "node:fs";
|
||||
import {
|
||||
HermesClientPathError,
|
||||
resolveHermesClientHome,
|
||||
} from "./HermesClientHome.js";
|
||||
|
||||
/** One supported client configuration location. */
|
||||
export interface SetupClient {
|
||||
@@ -115,49 +119,8 @@ const qwenCodeDirectory = ({ home, env }: ClientPathContext): string => {
|
||||
const grokDirectory = ({ home, env }: ClientPathContext): string =>
|
||||
env.GROK_HOME || join(home, ".grok");
|
||||
|
||||
/**
|
||||
* Hermes Agent home. `HERMES_HOME` wins; otherwise the platform default mirrors
|
||||
* Hermes's own resolver (`%LOCALAPPDATA%\\hermes` on Windows, `~/.hermes`
|
||||
* elsewhere), including the optional `HERMES_DATA_DIR_SUFFIX` that is appended
|
||||
* to the literal `hermes`/`.hermes` directory name.
|
||||
*/
|
||||
const hermesDirectory = ({
|
||||
home,
|
||||
platform,
|
||||
env,
|
||||
}: ClientPathContext): string => {
|
||||
const override = env.HERMES_HOME?.trim();
|
||||
if (override) {
|
||||
const expandedVariables = override.replace(
|
||||
/\$(\w+|\{[^}]*\})/gu,
|
||||
(match, variable: string) => {
|
||||
const key = variable.startsWith("{") ? variable.slice(1, -1) : variable;
|
||||
return env[key] ?? match;
|
||||
},
|
||||
);
|
||||
const expanded =
|
||||
platform === "win32"
|
||||
? expandedVariables.replace(
|
||||
/%([^%]+)%/gu,
|
||||
(match, variable: string) => env[variable] ?? match,
|
||||
)
|
||||
: expandedVariables;
|
||||
if (expanded === "~") return home;
|
||||
if (
|
||||
expanded.startsWith("~/") ||
|
||||
(platform === "win32" && expanded.startsWith("~\\"))
|
||||
)
|
||||
return join(home, expanded.slice(2));
|
||||
return resolve(expanded);
|
||||
}
|
||||
const suffix = env.HERMES_DATA_DIR_SUFFIX ?? "";
|
||||
return platform === "win32"
|
||||
? join(
|
||||
env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local"),
|
||||
`hermes${suffix}`,
|
||||
)
|
||||
: join(home, `.hermes${suffix}`);
|
||||
};
|
||||
const hermesDirectory = ({ home, platform, env }: ClientPathContext): string =>
|
||||
resolveHermesClientHome(home, platform, env);
|
||||
|
||||
/** Grok Bot uses an absolute SAND_DATA_ROOT; anything else stays ~/.grokbot. */
|
||||
const grokBotDirectory = ({ home, env }: ClientPathContext): string => {
|
||||
@@ -577,6 +540,14 @@ export const supportedClients = (
|
||||
format: definition.format,
|
||||
};
|
||||
} catch (cause: unknown) {
|
||||
if (cause instanceof HermesClientPathError)
|
||||
return {
|
||||
name: definition.name,
|
||||
displayName: definition.displayName,
|
||||
format: definition.format,
|
||||
configPath: cause.path,
|
||||
configPathError: cause.message,
|
||||
};
|
||||
if (definition.name !== "pi") throw cause;
|
||||
return {
|
||||
name: definition.name,
|
||||
@@ -611,14 +582,21 @@ export const clientSkillDirectories = (
|
||||
const destinations = new Map<string, { client: string; directory: string }>();
|
||||
for (const client of selected) {
|
||||
const definition = definitions.find(({ name }) => name === client);
|
||||
const directory =
|
||||
definition?.skillPath === undefined
|
||||
? join(home, ".agents", "skills")
|
||||
: resolvePath(definition.skillPath, {
|
||||
home,
|
||||
platform,
|
||||
env: environment,
|
||||
});
|
||||
let directory: string;
|
||||
try {
|
||||
directory =
|
||||
definition?.skillPath === undefined
|
||||
? join(home, ".agents", "skills")
|
||||
: resolvePath(definition.skillPath, {
|
||||
home,
|
||||
platform,
|
||||
env: environment,
|
||||
});
|
||||
} catch (cause: unknown) {
|
||||
// Registration diagnostics own an unresolved profile; never fall back to another skill root.
|
||||
if (cause instanceof HermesClientPathError) continue;
|
||||
throw cause;
|
||||
}
|
||||
if (!destinations.has(directory))
|
||||
destinations.set(directory, {
|
||||
client:
|
||||
|
||||
@@ -42,6 +42,46 @@ describe("JavaScript analysis cancellation before publication", () => {
|
||||
expect(phases).not.toContain("validate_javascript_application_result");
|
||||
});
|
||||
|
||||
it("handles control turns and cancellation inside one large source file (#1462)", async () => {
|
||||
const root = await createTestTempDirectory("rea-js-cancel-in-file-");
|
||||
await writeFile(
|
||||
join(root, "index.js"),
|
||||
Array.from(
|
||||
{ length: 1200 },
|
||||
(_, index) =>
|
||||
`export function f${index}(){return {name:'f${index}',value:${index}};}`,
|
||||
).join("\n"),
|
||||
);
|
||||
const controller = new AbortController();
|
||||
const phases: string[] = [];
|
||||
let turns = 0;
|
||||
// Count event-loop turns once the file starts; parsing, analysis and
|
||||
// projection of this one file must leave room for them.
|
||||
const tick = (): void => {
|
||||
turns += 1;
|
||||
if (turns === 3) controller.abort();
|
||||
else if (!controller.signal.aborted) setImmediate(tick);
|
||||
};
|
||||
const result = await analyzeJavaScriptApplication(
|
||||
{ input_path: root, format: "directory" },
|
||||
{
|
||||
signal: controller.signal,
|
||||
progress: {
|
||||
async report(event) {
|
||||
phases.push(event.phase);
|
||||
if (event.phase === "parse_javascript_source") setImmediate(tick);
|
||||
},
|
||||
},
|
||||
},
|
||||
);
|
||||
if (result.ok) throw new Error("Cancelled analysis must not publish");
|
||||
expect(projectAnalysisError(result.error)).toMatchObject({
|
||||
code: "cancelled",
|
||||
});
|
||||
expect(phases).toContain("parse_javascript_source");
|
||||
expect(phases).not.toContain("build_javascript_application_graph");
|
||||
});
|
||||
|
||||
it.each([
|
||||
"parse_javascript_source",
|
||||
"build_javascript_application_graph",
|
||||
|
||||
@@ -2,9 +2,9 @@ import { createHash } from "node:crypto";
|
||||
import { setImmediate } from "node:timers/promises";
|
||||
|
||||
import { resolveJavaScriptSourceMapReference } from "../../domain/javascript/javascriptSourceMapPaths.js";
|
||||
import { analyzeParsedJavaScriptStaticSource } from "../../domain/javascript/javascriptStaticAnalysis.js";
|
||||
import { analyzeParsedJavaScriptStaticSourceSteps } from "../../domain/javascript/javascriptStaticAnalysis.js";
|
||||
import {
|
||||
analyzeParsedJavaScriptSemantics,
|
||||
analyzeParsedJavaScriptSemanticsSteps,
|
||||
classifyParsedJavaScriptOpenReceivers,
|
||||
} from "../../domain/javascript/javascriptSemanticAnalysis.js";
|
||||
import type { JavaScriptSemanticIr } from "../../domain/javascript/javascriptSemanticIr.js";
|
||||
@@ -33,6 +33,7 @@ import type {
|
||||
JavaScriptSourceMapOriginal,
|
||||
} from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
import { analyzeJavaScriptJsonModule } from "./JavaScriptJsonModules.js";
|
||||
import { completeJavaScriptAnalysisSteps } from "./JavaScriptAnalysisControl.js";
|
||||
import { htmlArtifactReferences } from "../../domain/javascript/htmlArtifactReferences.js";
|
||||
|
||||
interface MutableArtifactAnalysis<
|
||||
@@ -56,34 +57,44 @@ interface ArtifactAnalysisContext<
|
||||
readonly projectSemantics: (
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
) => SemanticIr;
|
||||
) => Generator<void, SemanticIr>;
|
||||
}
|
||||
|
||||
/** Analyze every text source from the artifact without a result quota. */
|
||||
export const analyzeJavaScriptArtifactFiles = (
|
||||
fileSet: JavaScriptArtifactFileSet,
|
||||
): JavaScriptArtifactAnalysis =>
|
||||
analyzeArtifactFiles(fileSet, (_file, ir) => ir);
|
||||
analyzeArtifactFiles(fileSet, function* (_file, ir) {
|
||||
// The full IR needs no projection; one step keeps the shared protocol.
|
||||
yield;
|
||||
return ir;
|
||||
});
|
||||
|
||||
/** Project each file's full IR immediately, retaining only later module facts. */
|
||||
/**
|
||||
* Project each file's full IR immediately, retaining only later module facts.
|
||||
* Parsing, analysis and each projection pass run as separate steps, so control
|
||||
* messages and cancellation are handled within one large file as well.
|
||||
*/
|
||||
export const analyzeAndProjectJavaScriptArtifactFiles = async (
|
||||
fileSet: JavaScriptArtifactFileSet,
|
||||
projectSemantics: (
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
) => void,
|
||||
) => Iterator<void, void> | void,
|
||||
beforeFile?: (
|
||||
file: JavaScriptArtifactFile,
|
||||
completed: number,
|
||||
total: number,
|
||||
) => Promise<void>,
|
||||
signal?: AbortSignal,
|
||||
): Promise<JavaScriptModuleArtifactAnalysis> => {
|
||||
const state = emptyArtifactAnalysis<JavaScriptModuleSemanticIr>();
|
||||
const projectFileSemantics = (
|
||||
const projectFileSemantics = function* (
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
): JavaScriptModuleSemanticIr => {
|
||||
projectSemantics(file, ir);
|
||||
): Generator<void, JavaScriptModuleSemanticIr> {
|
||||
const projection = projectSemantics(file, ir);
|
||||
if (projection !== undefined) while (projection.next().done !== true) yield;
|
||||
const programScopes = ir.scopes.filter(({ kind }) => kind === "program");
|
||||
const programScopeId = programScopes[0]?.scopeId;
|
||||
const localNames = new Set(
|
||||
@@ -111,7 +122,10 @@ export const analyzeAndProjectJavaScriptArtifactFiles = async (
|
||||
// Let progress, cancellation and garbage collection run between files.
|
||||
await setImmediate();
|
||||
await beforeFile?.(file, index, fileSet.files.length);
|
||||
analyzeArtifactFile(file, context);
|
||||
await completeJavaScriptAnalysisSteps(
|
||||
analyzeArtifactFileSteps(file, context),
|
||||
signal,
|
||||
);
|
||||
}
|
||||
return finalizeArtifactAnalysis(state);
|
||||
};
|
||||
@@ -122,7 +136,10 @@ const analyzeArtifactFiles = <SemanticIr extends JavaScriptModuleSemanticIr>(
|
||||
): JavaScriptArtifactAnalysis<SemanticIr> => {
|
||||
const state = emptyArtifactAnalysis<SemanticIr>();
|
||||
const context = { state, projectSemantics };
|
||||
for (const file of fileSet.files) analyzeArtifactFile(file, context);
|
||||
for (const file of fileSet.files) {
|
||||
const steps = analyzeArtifactFileSteps(file, context);
|
||||
while (steps.next().done !== true);
|
||||
}
|
||||
return finalizeArtifactAnalysis(state);
|
||||
};
|
||||
|
||||
@@ -148,10 +165,12 @@ const finalizeArtifactAnalysis = <
|
||||
};
|
||||
};
|
||||
|
||||
const analyzeArtifactFile = <SemanticIr extends JavaScriptModuleSemanticIr>(
|
||||
function* analyzeArtifactFileSteps<
|
||||
SemanticIr extends JavaScriptModuleSemanticIr,
|
||||
>(
|
||||
file: JavaScriptArtifactFile,
|
||||
context: ArtifactAnalysisContext<SemanticIr>,
|
||||
): void => {
|
||||
): Generator<void, void> {
|
||||
const { state } = context;
|
||||
addStructuredObservations(file, state);
|
||||
if (file.kind === "html" && file.text.included)
|
||||
@@ -162,6 +181,7 @@ const analyzeArtifactFile = <SemanticIr extends JavaScriptModuleSemanticIr>(
|
||||
return;
|
||||
}
|
||||
const parsed = parseJavaScriptSource(file.text.value, file.path);
|
||||
yield;
|
||||
if (parsed === null) {
|
||||
const analysis = failedJavaScriptStaticAnalysis();
|
||||
state.files.push({ file, javascript: analysis, semantic: null });
|
||||
@@ -169,23 +189,26 @@ const analyzeArtifactFile = <SemanticIr extends JavaScriptModuleSemanticIr>(
|
||||
return;
|
||||
}
|
||||
const openReceiverFacts = classifyParsedJavaScriptOpenReceivers(parsed);
|
||||
const analysis = analyzeParsedJavaScriptStaticSource(
|
||||
yield;
|
||||
const analysis = yield* analyzeParsedJavaScriptStaticSourceSteps(
|
||||
file.text.value,
|
||||
parsed,
|
||||
openReceiverFacts,
|
||||
);
|
||||
const staticFindings = findingCount(analysis);
|
||||
yield;
|
||||
const semantics =
|
||||
analysis.parse_status === "complete" || analysis.parse_status === "partial"
|
||||
? analyzeParsedJavaScriptSemantics(parsed)
|
||||
? yield* analyzeParsedJavaScriptSemanticsSteps(parsed)
|
||||
: null;
|
||||
const projected =
|
||||
semantics === null
|
||||
? null
|
||||
: yield* context.projectSemantics(file, semantics);
|
||||
state.files.push({
|
||||
file,
|
||||
javascript: analysis,
|
||||
semantic:
|
||||
semantics === null
|
||||
? null
|
||||
: { ir: context.projectSemantics(file, semantics) },
|
||||
semantic: projected === null ? null : { ir: projected },
|
||||
});
|
||||
state.visitedNodes += analysis.visited_ast_nodes;
|
||||
state.findings += staticFindings + (semantics?.moduleLinks.length ?? 0);
|
||||
@@ -194,7 +217,7 @@ const analyzeArtifactFile = <SemanticIr extends JavaScriptModuleSemanticIr>(
|
||||
0,
|
||||
);
|
||||
if (analysis.parse_status === "failed") state.parseFailures += 1;
|
||||
};
|
||||
}
|
||||
|
||||
const addSourceMap = (
|
||||
file: JavaScriptArtifactFile,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
import type { ArtifactInventorySnapshot } from "../../domain/artifactInventorySnapshot.js";
|
||||
import {
|
||||
createJavaScriptApplicationGraph,
|
||||
createImmutableJavaScriptApplicationGraphSteps,
|
||||
sealTransferredJavaScriptApplicationGraphSteps,
|
||||
type JavaScriptApplicationGraph,
|
||||
} from "../../domain/javascript/javascriptApplicationGraph.js";
|
||||
import type { JavaScriptModuleArtifactAnalysis } from "./JavaScriptArtifactAnalysisTypes.js";
|
||||
@@ -15,9 +15,9 @@ import {
|
||||
addJavaScriptHtmlRoles,
|
||||
addJavaScriptSourceMapOriginals,
|
||||
} from "./JavaScriptArtifactGraphDocuments.js";
|
||||
import { addJavaScriptStaticFindings } from "./JavaScriptArtifactGraphFindings.js";
|
||||
import { addJavaScriptStaticFindingsSteps } from "./JavaScriptArtifactGraphFindings.js";
|
||||
import {
|
||||
addJavaScriptModuleRelationships,
|
||||
addJavaScriptModuleRelationshipsSteps,
|
||||
type JavaScriptModuleRelationshipOmissions,
|
||||
addJavaScriptSourceModules,
|
||||
} from "./JavaScriptModuleRelationships.js";
|
||||
@@ -51,24 +51,42 @@ export const buildJavaScriptArtifactGraph = (
|
||||
analysis: JavaScriptModuleArtifactAnalysis,
|
||||
): JavaScriptApplicationGraph =>
|
||||
createJavaScriptApplicationGraph(
|
||||
buildJavaScriptArtifactGraphInput(snapshot, fileSet, analysis),
|
||||
completeSynchronously(
|
||||
buildJavaScriptArtifactGraphInputSteps(snapshot, fileSet, analysis),
|
||||
),
|
||||
);
|
||||
|
||||
/** Build a validated application graph with cooperative immutable ownership. */
|
||||
export const buildImmutableJavaScriptArtifactGraphSteps = (
|
||||
/**
|
||||
* Build a validated application graph with cooperative immutable ownership.
|
||||
* Constructing the graph input also runs in steps: projecting every module
|
||||
* relationship and finding at once held the event loop for seconds.
|
||||
*/
|
||||
export function* buildImmutableJavaScriptArtifactGraphSteps(
|
||||
snapshot: ArtifactInventorySnapshot,
|
||||
fileSet: JavaScriptArtifactFileSet,
|
||||
analysis: JavaScriptModuleArtifactAnalysis,
|
||||
): Generator<void, JavaScriptApplicationGraph> =>
|
||||
createImmutableJavaScriptApplicationGraphSteps(
|
||||
buildJavaScriptArtifactGraphInput(snapshot, fileSet, analysis),
|
||||
): Generator<void, JavaScriptApplicationGraph> {
|
||||
const input = yield* buildJavaScriptArtifactGraphInputSteps(
|
||||
snapshot,
|
||||
fileSet,
|
||||
analysis,
|
||||
);
|
||||
// The input was built here and is not retained, so it can be transferred.
|
||||
return yield* sealTransferredJavaScriptApplicationGraphSteps(input);
|
||||
}
|
||||
|
||||
const buildJavaScriptArtifactGraphInput = (
|
||||
const completeSynchronously = <Value>(steps: Iterator<void, Value>): Value => {
|
||||
for (;;) {
|
||||
const step = steps.next();
|
||||
if (step.done === true) return step.value;
|
||||
}
|
||||
};
|
||||
|
||||
function* buildJavaScriptArtifactGraphInputSteps(
|
||||
snapshot: ArtifactInventorySnapshot,
|
||||
fileSet: JavaScriptArtifactFileSet,
|
||||
analysis: JavaScriptModuleArtifactAnalysis,
|
||||
): unknown => {
|
||||
): Generator<void, unknown> {
|
||||
const accumulator = new JavaScriptArtifactGraphAccumulator();
|
||||
const root = createJavaScriptArtifactRootNode(accumulator, snapshot);
|
||||
const context: JavaScriptArtifactGraphContext = {
|
||||
@@ -86,15 +104,23 @@ const buildJavaScriptArtifactGraphInput = (
|
||||
containerNodes: new Map([[snapshot.manifest.root_sha256, root]]),
|
||||
};
|
||||
addJavaScriptArtifactContainers(context);
|
||||
yield;
|
||||
addJavaScriptArtifactFiles(context);
|
||||
yield;
|
||||
const packageRoots = addJavaScriptPackageNodes(context);
|
||||
yield;
|
||||
addJavaScriptSourceModules(context);
|
||||
yield;
|
||||
const bundlerLimitations = addJavaScriptBundlerNodes(context);
|
||||
const relationshipOmissions = addJavaScriptModuleRelationships(context);
|
||||
const findingLimitations = addJavaScriptStaticFindings(context);
|
||||
const relationshipOmissions =
|
||||
yield* addJavaScriptModuleRelationshipsSteps(context);
|
||||
const findingLimitations = yield* addJavaScriptStaticFindingsSteps(context);
|
||||
addElectronBoundaries(context);
|
||||
yield;
|
||||
addJavaScriptHtmlRoles(context);
|
||||
yield;
|
||||
addJavaScriptSourceMapOriginals(context);
|
||||
yield;
|
||||
const coverage = graphCoverage(context);
|
||||
return {
|
||||
schema: "JavaScriptApplicationGraph",
|
||||
@@ -111,7 +137,7 @@ const buildJavaScriptArtifactGraphInput = (
|
||||
...graphLimitations(context, coverage.status, relationshipOmissions),
|
||||
],
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
const graphCoverage = (context: JavaScriptArtifactGraphContext) => {
|
||||
const resourceLimits = semanticResourceLimits(context);
|
||||
|
||||
@@ -44,11 +44,12 @@ interface ResolvedReference {
|
||||
}
|
||||
|
||||
/** Project imports, workers, roles, endpoints, storage, and source-map links. */
|
||||
export const addJavaScriptStaticFindings = (
|
||||
export function* addJavaScriptStaticFindingsSteps(
|
||||
context: JavaScriptArtifactGraphContext,
|
||||
): readonly string[] => {
|
||||
): Generator<void, readonly string[]> {
|
||||
const omissions = { selfReferences: 0 };
|
||||
for (const analyzed of context.analysis.files) {
|
||||
yield;
|
||||
const { file, javascript } = analyzed;
|
||||
const asset = context.assetNodes.get(file.path);
|
||||
if (javascript === null || asset === undefined) continue;
|
||||
@@ -69,7 +70,7 @@ export const addJavaScriptStaticFindings = (
|
||||
["static reference", "static references"],
|
||||
"the referencing module",
|
||||
);
|
||||
};
|
||||
}
|
||||
|
||||
const addReference = (
|
||||
context: JavaScriptArtifactGraphContext,
|
||||
|
||||
@@ -90,7 +90,7 @@ export const reconstructJavaScriptArtifact = async (
|
||||
const semanticProjection = createJavaScriptSemanticGraphProjection();
|
||||
const analysis = await analyzeAndProjectJavaScriptArtifactFiles(
|
||||
files,
|
||||
semanticProjection.projectFile,
|
||||
semanticProjection.projectFileSteps,
|
||||
async (file, completed, total) => {
|
||||
abortIfNeeded(signal);
|
||||
await progress?.report({
|
||||
@@ -101,6 +101,7 @@ export const reconstructJavaScriptArtifact = async (
|
||||
});
|
||||
abortIfNeeded(signal);
|
||||
},
|
||||
signal,
|
||||
);
|
||||
await checkpointJavaScriptAnalysis(signal);
|
||||
abortIfNeeded(signal);
|
||||
|
||||
@@ -136,15 +136,17 @@ export interface JavaScriptModuleRelationshipOmissions {
|
||||
type RelationshipOmissionCounter = { selfImports: number };
|
||||
|
||||
/** Compose bounded CommonJS and ESM binding relationships across artifact files. */
|
||||
export const addJavaScriptModuleRelationships = (
|
||||
export function* addJavaScriptModuleRelationshipsSteps(
|
||||
context: JavaScriptArtifactGraphContext,
|
||||
): JavaScriptModuleRelationshipOmissions => {
|
||||
): Generator<void, JavaScriptModuleRelationshipOmissions> {
|
||||
const omissions = { selfImports: 0 };
|
||||
for (const analyzed of context.analysis.files) {
|
||||
const { file, semantic } = analyzed;
|
||||
const source = context.sourceModuleNodes.get(file.path);
|
||||
if (semantic === null || source === undefined) continue;
|
||||
for (const link of semantic.ir.moduleLinks) {
|
||||
// One module can export thousands of bindings, each with return shapes.
|
||||
yield;
|
||||
const input = { context, file, semantic, source, link };
|
||||
if (isExportLink(link)) addExportRelationship(input, omissions);
|
||||
else if (link.specifier !== null)
|
||||
@@ -155,7 +157,7 @@ export const addJavaScriptModuleRelationships = (
|
||||
}
|
||||
}
|
||||
return omissions;
|
||||
};
|
||||
}
|
||||
|
||||
const addExportRelationship = (
|
||||
input: RelationshipInput,
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
import {
|
||||
createJavaScriptSemanticGraph,
|
||||
createImmutableJavaScriptSemanticGraphSteps,
|
||||
sealTransferredJavaScriptSemanticGraphSteps,
|
||||
type JavaScriptSemanticGraph,
|
||||
} from "../../domain/javascript/javascriptSemanticGraph.js";
|
||||
import type {
|
||||
@@ -130,6 +130,11 @@ export interface JavaScriptSemanticGraphProjection {
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
) => void;
|
||||
/** Project one file in steps between its projection passes. */
|
||||
readonly projectFileSteps: (
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
) => Generator<void, void>;
|
||||
readonly finish: (
|
||||
rootArtifactSha256: string,
|
||||
applicationGraph: BuilderInput["applicationGraph"],
|
||||
@@ -146,10 +151,10 @@ export const createJavaScriptSemanticGraphProjection =
|
||||
const state = emptyState({ nodes: [] });
|
||||
const fingerprints: JavaScriptSemanticFingerprint[] = [];
|
||||
let truncatedFiles = 0;
|
||||
const projectSource = (
|
||||
const projectSourceSteps = function* (
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
): void => {
|
||||
): Generator<void, void> {
|
||||
if (state.nodes.size >= SEMANTIC_GRAPH_NODE_CEILING) {
|
||||
truncatedFiles += 1;
|
||||
return;
|
||||
@@ -161,7 +166,7 @@ export const createJavaScriptSemanticGraphProjection =
|
||||
remainingTreeBudget,
|
||||
);
|
||||
state.fileNodesDropped = false;
|
||||
fingerprints.push(...projectFile(file, ir, state));
|
||||
fingerprints.push(...(yield* projectFileSteps(file, ir, state)));
|
||||
// Nodes were dropped only if the budget actually blocked creation. A file
|
||||
// that exactly fills its share ends with a zero budget without dropping
|
||||
// anything, so the remaining budget alone cannot decide truncation.
|
||||
@@ -198,7 +203,8 @@ export const createJavaScriptSemanticGraphProjection =
|
||||
evidence_contexts: state.evidenceContexts.contexts,
|
||||
nodes: [...state.nodes.values()],
|
||||
relations,
|
||||
fingerprints,
|
||||
// The input is transferred to the factory; `fingerprints` is cleared below.
|
||||
fingerprints: [...fingerprints],
|
||||
unknowns,
|
||||
coverage: {
|
||||
status: truncatedFiles > 0 ? "partial" : "unknown",
|
||||
@@ -246,7 +252,11 @@ export const createJavaScriptSemanticGraphProjection =
|
||||
return graph;
|
||||
};
|
||||
return {
|
||||
projectFile: projectSource,
|
||||
projectFile: (file, ir) => {
|
||||
const steps = projectSourceSteps(file, ir);
|
||||
while (steps.next().done !== true);
|
||||
},
|
||||
projectFileSteps: projectSourceSteps,
|
||||
finish: (rootArtifactSha256, applicationGraph) =>
|
||||
finishWith(
|
||||
createJavaScriptSemanticGraph,
|
||||
@@ -255,18 +265,19 @@ export const createJavaScriptSemanticGraphProjection =
|
||||
),
|
||||
finishImmutableSteps: (rootArtifactSha256, applicationGraph) =>
|
||||
finishWith(
|
||||
createImmutableJavaScriptSemanticGraphSteps,
|
||||
sealTransferredJavaScriptSemanticGraphSteps,
|
||||
rootArtifactSha256,
|
||||
applicationGraph,
|
||||
),
|
||||
};
|
||||
};
|
||||
|
||||
const projectFile = (
|
||||
function* projectFileSteps(
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
state: BuilderState,
|
||||
): JavaScriptSemanticFingerprint[] => {
|
||||
): Generator<void, JavaScriptSemanticFingerprint[]> {
|
||||
yield;
|
||||
const moduleNode = retainNode(state, file, {
|
||||
kind: "module",
|
||||
roleKey: "module",
|
||||
@@ -276,38 +287,50 @@ const projectFile = (
|
||||
});
|
||||
if (moduleNode === null) return [];
|
||||
state.roots.add(moduleNode.node_id);
|
||||
const callableNodes = new Map(
|
||||
ir.callables.flatMap((callable) => {
|
||||
const node = retainNode(state, file, {
|
||||
kind: "function",
|
||||
roleKey: `callable:${callable.callableId}`,
|
||||
location: callable.location,
|
||||
label: callable.name,
|
||||
functionNodeId: null,
|
||||
// The label is display text; keep the exact name, which may be "".
|
||||
properties: { name: callable.name },
|
||||
});
|
||||
return node === null ? [] : [[callable.callableId, node] as const];
|
||||
}),
|
||||
);
|
||||
// Node creation keeps source order, which the per-file node budget relies
|
||||
// on; yields between nodes do not change it.
|
||||
const callableNodes = new Map<string, JavaScriptSemanticGraphNode>();
|
||||
for (const [index, callable] of ir.callables.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const node = retainNode(state, file, {
|
||||
kind: "function",
|
||||
roleKey: `callable:${callable.callableId}`,
|
||||
location: callable.location,
|
||||
label: callable.name,
|
||||
functionNodeId: null,
|
||||
// The label is display text; keep the exact name, which may be "".
|
||||
properties: { name: callable.name },
|
||||
});
|
||||
if (node !== null) callableNodes.set(callable.callableId, node);
|
||||
}
|
||||
const callableOwnerAt = createSemanticCallableOwnerLookup(ir, callableNodes);
|
||||
const bindingNodes = new Map(
|
||||
ir.bindings.flatMap((binding) => {
|
||||
const location = binding.definitions[0]?.location ?? null;
|
||||
const kind = binding.kind === "parameter" ? "parameter" : "binding";
|
||||
const owner = callableOwnerAt(location);
|
||||
const node = retainNode(state, file, {
|
||||
kind,
|
||||
roleKey: `binding:${binding.bindingId}`,
|
||||
location,
|
||||
label: binding.name,
|
||||
functionNodeId: owner?.node_id ?? null,
|
||||
});
|
||||
return node === null ? [] : [[binding.bindingId, node] as const];
|
||||
}),
|
||||
const bindingNodes = new Map<string, JavaScriptSemanticGraphNode>();
|
||||
for (const [index, binding] of ir.bindings.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const location = binding.definitions[0]?.location ?? null;
|
||||
const kind = binding.kind === "parameter" ? "parameter" : "binding";
|
||||
const owner = callableOwnerAt(location);
|
||||
const node = retainNode(state, file, {
|
||||
kind,
|
||||
roleKey: `binding:${binding.bindingId}`,
|
||||
location,
|
||||
label: binding.name,
|
||||
functionNodeId: owner?.node_id ?? null,
|
||||
});
|
||||
if (node !== null) bindingNodes.set(binding.bindingId, node);
|
||||
}
|
||||
const returnSiteNodes = yield* createReturnSiteNodes(
|
||||
file,
|
||||
ir,
|
||||
callableNodes,
|
||||
state,
|
||||
);
|
||||
const callSiteNodes = yield* createCallSiteNodes(
|
||||
file,
|
||||
ir,
|
||||
callableNodes,
|
||||
state,
|
||||
);
|
||||
const returnSiteNodes = createReturnSiteNodes(file, ir, callableNodes, state);
|
||||
const callSiteNodes = createCallSiteNodes(file, ir, callableNodes, state);
|
||||
const definitions: Omit<FileContext, "referenceNodesWithin"> = {
|
||||
file,
|
||||
ir,
|
||||
@@ -328,42 +351,38 @@ const projectFile = (
|
||||
callableOwnerAt,
|
||||
callSiteAt: createSemanticCallSiteLookup(ir, callSiteNodes),
|
||||
};
|
||||
projectDefinitionsAndReferences(definitions);
|
||||
yield* projectDefinitionsAndReferences(definitions);
|
||||
const context: FileContext = {
|
||||
...definitions,
|
||||
referenceNodesWithin: createSemanticNodeRangeLookup(
|
||||
definitions.referenceNodes,
|
||||
),
|
||||
};
|
||||
projectSemanticValues(context);
|
||||
projectSemanticObjects(context);
|
||||
projectCalls(context);
|
||||
projectSemanticPromises(context);
|
||||
projectSemanticEvents(context);
|
||||
projectSemanticTimers(context);
|
||||
projectSemanticChildProcesses(context);
|
||||
projectSemanticConfiguration(context);
|
||||
projectSemanticRequests(context);
|
||||
projectSemanticBoundaries(context);
|
||||
projectSemanticResources(context);
|
||||
projectSemanticClosureCaptures(context);
|
||||
projectSemanticFrontiers(context);
|
||||
// Each pass completes before the next starts, so yielding between passes
|
||||
// keeps projection order and results unchanged.
|
||||
for (const project of FILE_PROJECTION_PASSES) {
|
||||
yield;
|
||||
const steps = project(context);
|
||||
if (steps !== undefined) while (steps.next().done !== true) yield;
|
||||
}
|
||||
yield;
|
||||
return projectSemanticFunctionFingerprints(
|
||||
file,
|
||||
ir,
|
||||
callableNodes,
|
||||
state.evidenceContexts,
|
||||
);
|
||||
};
|
||||
}
|
||||
|
||||
const createReturnSiteNodes = (
|
||||
function* createReturnSiteNodes(
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
callables: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
|
||||
state: BuilderState,
|
||||
): Map<string, JavaScriptSemanticGraphNode> => {
|
||||
): Generator<void, Map<string, JavaScriptSemanticGraphNode>> {
|
||||
const result = new Map<string, JavaScriptSemanticGraphNode>();
|
||||
for (const callable of ir.callables) {
|
||||
for (const [index, callable] of ir.callables.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const owner = callables.get(callable.callableId);
|
||||
if (owner === undefined) continue;
|
||||
for (const site of callable.returnSites) {
|
||||
@@ -379,16 +398,17 @@ const createReturnSiteNodes = (
|
||||
}
|
||||
}
|
||||
return result;
|
||||
};
|
||||
}
|
||||
|
||||
const createCallSiteNodes = (
|
||||
function* createCallSiteNodes(
|
||||
file: JavaScriptArtifactFile,
|
||||
ir: JavaScriptSemanticIr,
|
||||
callables: ReadonlyMap<string, JavaScriptSemanticGraphNode>,
|
||||
state: BuilderState,
|
||||
): Map<string, JavaScriptSemanticGraphNode> => {
|
||||
): Generator<void, Map<string, JavaScriptSemanticGraphNode>> {
|
||||
const result = new Map<string, JavaScriptSemanticGraphNode>();
|
||||
for (const call of ir.callSites) {
|
||||
for (const [index, call] of ir.callSites.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const owner =
|
||||
call.callerCallableId === null
|
||||
? null
|
||||
@@ -403,12 +423,13 @@ const createCallSiteNodes = (
|
||||
if (node !== null) result.set(call.callSiteId, node);
|
||||
}
|
||||
return result;
|
||||
};
|
||||
}
|
||||
|
||||
const projectDefinitionsAndReferences = (
|
||||
function* projectDefinitionsAndReferences(
|
||||
context: Omit<FileContext, "referenceNodesWithin">,
|
||||
): void => {
|
||||
for (const binding of context.ir.bindings) {
|
||||
): Generator<void, void> {
|
||||
for (const [bindingIndex, binding] of context.ir.bindings.entries()) {
|
||||
if (bindingIndex % 64 === 0) yield;
|
||||
const bindingNode = context.bindingNodes.get(binding.bindingId);
|
||||
if (bindingNode === undefined) continue;
|
||||
for (const [index, definition] of binding.definitions.entries()) {
|
||||
@@ -428,6 +449,7 @@ const projectDefinitionsAndReferences = (
|
||||
}
|
||||
}
|
||||
for (const [index, reference] of context.ir.references.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const expression = retainNode(context.state, context.file, {
|
||||
kind: "expression",
|
||||
roleKey: `reference:${String(index)}:${reference.role}:${reference.name}`,
|
||||
@@ -458,7 +480,7 @@ const projectDefinitionsAndReferences = (
|
||||
resolution: "resolved",
|
||||
});
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
const projectCalls = (context: FileContext): void => {
|
||||
for (const call of context.ir.callSites) {
|
||||
@@ -543,3 +565,22 @@ const createArgumentNode = (
|
||||
: `argument ${String(argument.index)}`,
|
||||
functionNodeId: callNode.function_node_id,
|
||||
});
|
||||
|
||||
/** Per-file projection passes, run in this order with a yield between each. */
|
||||
const FILE_PROJECTION_PASSES: readonly ((
|
||||
context: FileContext,
|
||||
) => Iterator<void, void> | void)[] = [
|
||||
projectSemanticValues,
|
||||
projectSemanticObjects,
|
||||
projectCalls,
|
||||
projectSemanticPromises,
|
||||
projectSemanticEvents,
|
||||
projectSemanticTimers,
|
||||
projectSemanticChildProcesses,
|
||||
projectSemanticConfiguration,
|
||||
projectSemanticRequests,
|
||||
projectSemanticBoundaries,
|
||||
projectSemanticResources,
|
||||
projectSemanticClosureCaptures,
|
||||
projectSemanticFrontiers,
|
||||
];
|
||||
|
||||
@@ -240,10 +240,11 @@ export const projectSemanticClosureCaptures = (
|
||||
};
|
||||
|
||||
/** Retain bounded unresolved dynamic-call, dynamic-property and dynamic-scope frontiers. */
|
||||
export const projectSemanticFrontiers = (
|
||||
export function* projectSemanticFrontiers(
|
||||
context: SemanticFlowProjectionContext,
|
||||
): void => {
|
||||
for (const frontier of context.ir.frontiers) {
|
||||
): Generator<void, void> {
|
||||
for (const [index, frontier] of context.ir.frontiers.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
// Dynamic environments leave identifier reads and writes unresolved.
|
||||
const family =
|
||||
frontier.kind === "dynamic-call"
|
||||
@@ -275,4 +276,4 @@ export const projectSemanticFrontiers = (
|
||||
);
|
||||
addSemanticGraphUnknown(context.state, unknown);
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
@@ -20,13 +20,14 @@ import type { SemanticFlowProjectionContext } from "./JavaScriptSemanticGraphFlo
|
||||
import { semanticPropertySlot } from "./JavaScriptSemanticGraphValueProjection.js";
|
||||
|
||||
/** Project static object reads, writes, spreads, and destructuring. */
|
||||
export const projectSemanticObjects = (
|
||||
export function* projectSemanticObjects(
|
||||
context: SemanticFlowProjectionContext,
|
||||
): void => {
|
||||
): Generator<void, void> {
|
||||
const values = new Map(
|
||||
context.ir.bindings.map((binding) => [binding.bindingId, binding.value]),
|
||||
);
|
||||
for (const operation of context.ir.objectOperations) {
|
||||
for (const [index, operation] of context.ir.objectOperations.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const occurrence = addObjectOccurrence(context, operation);
|
||||
const target = objectTarget(context, values, operation);
|
||||
const ends = objectRelationEnds(context, operation, occurrence, target);
|
||||
@@ -43,7 +44,7 @@ export const projectSemanticObjects = (
|
||||
if (!resolved)
|
||||
addObjectUnknown(context, operation, target.slot ?? occurrence, target);
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
const OBJECT_RELATIONS = {
|
||||
read: "reads-property",
|
||||
|
||||
@@ -15,6 +15,7 @@ import { processTraceSpecificationSchema } from "../../domain/process/processTra
|
||||
import { processScenarioSchema } from "../../domain/process/processScenario.js";
|
||||
import { compareProcessCaptures } from "../../domain/process/processComparison.js";
|
||||
import { parseProcessCapture } from "../../domain/process/processCaptureParsing.js";
|
||||
import { createProgressReporter } from "../ProgressReporter.js";
|
||||
import { captureProcessScenario } from "../../process/capture/ProcessHarness.js";
|
||||
import { PROCESS_PROVIDER } from "../../domain/process/processEvidenceProvider.js";
|
||||
import { createProcessCaptureEvidence } from "./ProcessEvidence.js";
|
||||
@@ -56,11 +57,20 @@ export const captureProcessScenarioFile = async (
|
||||
input,
|
||||
{ cause: parsed.error },
|
||||
);
|
||||
const progress = createProgressReporter(
|
||||
async (update) => {
|
||||
process.stderr.write(`${JSON.stringify({ rea_progress: update })}\n`);
|
||||
},
|
||||
{ minimumIntervalMs: 100 },
|
||||
);
|
||||
const captured = await captureProcessScenario(
|
||||
parsed.data,
|
||||
signal,
|
||||
process.platform,
|
||||
environment,
|
||||
undefined,
|
||||
undefined,
|
||||
progress,
|
||||
);
|
||||
if (!captured.ok) return cliAnalysisError(captured.error);
|
||||
return createProcessCaptureEvidence(parsed.data, captured.value);
|
||||
|
||||
@@ -22,7 +22,11 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
this.#rootPromise = realpath(root);
|
||||
}
|
||||
|
||||
async *entries(signal?: AbortSignal): AsyncIterable<ArtifactEntry> {
|
||||
/** Enumerate entries, optionally restricting descent while retaining directories. */
|
||||
async *entries(
|
||||
signal?: AbortSignal,
|
||||
descendInto?: (path: string) => boolean,
|
||||
): AsyncIterable<ArtifactEntry> {
|
||||
const root = await this.#rootPromise.catch((cause: unknown) => {
|
||||
throw directoryIoFailure("resolve artifact root", this.#rootPath, cause);
|
||||
});
|
||||
@@ -66,7 +70,8 @@ export class DirectoryArtifactReader implements ArtifactReader {
|
||||
? "file"
|
||||
: undefined;
|
||||
if (kind === undefined) continue;
|
||||
if (kind === "directory") directories.push(absolute);
|
||||
if (kind === "directory" && (descendInto?.(path) ?? true))
|
||||
directories.push(absolute);
|
||||
yield {
|
||||
path,
|
||||
kind,
|
||||
|
||||
@@ -148,8 +148,20 @@ export const inspectBundleKeyedArchive = async (input: {
|
||||
// Match inventory spelling while retaining the raw path for I/O and evidence.
|
||||
const wanted = selected.path.normalize("NFC");
|
||||
const matches: ArtifactEntry[] = [];
|
||||
for await (const entry of reader.entries(input.signal)) {
|
||||
for await (const entry of reader.entries(input.signal, (directory) =>
|
||||
wanted.startsWith(`${directory.normalize("NFC")}/`),
|
||||
)) {
|
||||
if (entry.path.normalize("NFC") !== wanted) continue;
|
||||
if (entry.kind !== "file")
|
||||
throw archivePathError(
|
||||
"invalid_value",
|
||||
`Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`,
|
||||
);
|
||||
if ((entry.declaredSize ?? 0) > MAX_BYTES)
|
||||
throw new ArtifactReaderFailure(
|
||||
"limit",
|
||||
"Keyed archive exceeds 64 MiB",
|
||||
);
|
||||
matches.push(entry);
|
||||
}
|
||||
if (matches.length > 1)
|
||||
@@ -163,13 +175,6 @@ export const inspectBundleKeyedArchive = async (input: {
|
||||
"invalid_value",
|
||||
`No regular file exists at ${selected.path} in the active app bundle.`,
|
||||
);
|
||||
if (entry.kind !== "file")
|
||||
throw archivePathError(
|
||||
"invalid_value",
|
||||
`Archive path selects a ${entry.kind}, not a regular file: ${selected.path}`,
|
||||
);
|
||||
if ((entry.declaredSize ?? 0) > MAX_BYTES)
|
||||
throw new ArtifactReaderFailure("limit", "Keyed archive exceeds 64 MiB");
|
||||
const stream = await reader.open(entry, input.signal);
|
||||
const chunks: Buffer[] = [];
|
||||
let size = 0;
|
||||
|
||||
@@ -11,11 +11,13 @@ import {
|
||||
createJavaScriptApplicationGraph,
|
||||
createImmutableJavaScriptApplicationGraphSteps,
|
||||
isValidatedImmutableJavaScriptApplicationGraph,
|
||||
sealTransferredJavaScriptApplicationGraphSteps,
|
||||
} from "./javascriptApplicationGraph.js";
|
||||
import {
|
||||
createJavaScriptSemanticGraph,
|
||||
createImmutableJavaScriptSemanticGraphSteps,
|
||||
isValidatedImmutableJavaScriptSemanticGraph,
|
||||
sealTransferredJavaScriptSemanticGraphSteps,
|
||||
} from "./javascriptSemanticGraph.js";
|
||||
|
||||
const complete = <Value>(steps: Iterator<void, Value>): Value => {
|
||||
@@ -265,3 +267,60 @@ describe("owned JavaScript result bindings", () => {
|
||||
);
|
||||
});
|
||||
});
|
||||
|
||||
describe("graphs transferred to their sealing steps", () => {
|
||||
it("seal the same validated graphs as the copying factories", () => {
|
||||
const input = example();
|
||||
const { graph_id: _applicationId, ...application } = input.graph;
|
||||
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
|
||||
const expectedApplication = createJavaScriptApplicationGraph(application);
|
||||
const expectedSemantic = createJavaScriptSemanticGraph(semantic);
|
||||
const sealedApplication = complete(
|
||||
sealTransferredJavaScriptApplicationGraphSteps(
|
||||
structuredClone(application),
|
||||
),
|
||||
);
|
||||
const sealedSemantic = complete(
|
||||
sealTransferredJavaScriptSemanticGraphSteps(structuredClone(semantic)),
|
||||
);
|
||||
expect(sealedApplication).toEqual(expectedApplication);
|
||||
expect(sealedSemantic).toEqual(expectedSemantic);
|
||||
expect(
|
||||
isValidatedImmutableJavaScriptApplicationGraph(sealedApplication),
|
||||
).toBe(true);
|
||||
expect(isValidatedImmutableJavaScriptSemanticGraph(sealedSemantic)).toBe(
|
||||
true,
|
||||
);
|
||||
});
|
||||
|
||||
it("report the issues a whole-graph parse reports", () => {
|
||||
const input = example();
|
||||
const { graph_id: _applicationId, ...application } = input.graph;
|
||||
const { graph_id: _semanticId, ...semantic } = input.semantic_graph;
|
||||
const node = semantic.nodes[0];
|
||||
const applicationNode = application.nodes[0];
|
||||
if (node === undefined || applicationNode === undefined)
|
||||
throw new Error("Expected semantic and application nodes");
|
||||
const malformed = {
|
||||
...semantic,
|
||||
nodes: [{ ...node, label: 7 }, ...semantic.nodes.slice(1)],
|
||||
};
|
||||
expect(
|
||||
issuesFrom(() =>
|
||||
complete(sealTransferredJavaScriptSemanticGraphSteps(malformed)),
|
||||
),
|
||||
).toEqual(issuesFrom(() => createJavaScriptSemanticGraph(malformed)));
|
||||
const stale = {
|
||||
...application,
|
||||
nodes: [
|
||||
{ ...applicationNode, node_id: `jag_node_${"f".repeat(64)}` },
|
||||
...application.nodes.slice(1),
|
||||
],
|
||||
};
|
||||
expect(
|
||||
issuesFrom(() =>
|
||||
complete(sealTransferredJavaScriptApplicationGraphSteps(stale)),
|
||||
),
|
||||
).toEqual(issuesFrom(() => createJavaScriptApplicationGraph(stale)));
|
||||
});
|
||||
});
|
||||
|
||||
@@ -1,4 +1,9 @@
|
||||
import { z } from "zod";
|
||||
import {
|
||||
arrayContainerSchema,
|
||||
parseElementSteps,
|
||||
} from "../zodCollectionSteps.js";
|
||||
import { canonicalJsonDigestSteps } from "../canonicalJsonDigestSteps.js";
|
||||
import { canonicalJson } from "../comparisonSemantics.js";
|
||||
import { digestCanonicalValue } from "../canonicalDigest.js";
|
||||
import { uniqueSorted } from "../canonicalOrdering.js";
|
||||
@@ -93,11 +98,14 @@ type EdgeSemantic = Omit<ApplicationEdge, "edge_id">;
|
||||
const edgeId = (edge: EdgeSemantic): string =>
|
||||
`jag_edge_${digestCanonicalValue(edge, "JavaScript Application Graph")}`;
|
||||
|
||||
/** The issue sink shared by schema refinement and stepwise checking. */
|
||||
type GraphIssueContext = Pick<z.RefinementCtx, "addIssue">;
|
||||
|
||||
const sortedUniqueIssue = (
|
||||
values: readonly string[],
|
||||
path: PropertyKey[],
|
||||
label: string,
|
||||
context: z.RefinementCtx,
|
||||
context: GraphIssueContext,
|
||||
): void => {
|
||||
for (let index = 1; index < values.length; index += 1) {
|
||||
if (
|
||||
@@ -116,7 +124,7 @@ const sortedUniqueIssue = (
|
||||
const checkEvidenceNormalization = (
|
||||
evidence: ApplicationGraphEvidence,
|
||||
path: PropertyKey[],
|
||||
context: z.RefinementCtx,
|
||||
context: GraphIssueContext,
|
||||
): void => {
|
||||
sortedUniqueIssue(
|
||||
evidence.limitations,
|
||||
@@ -226,7 +234,7 @@ const observationMatchesIdentity = (
|
||||
const checkNode = (
|
||||
node: ApplicationNode,
|
||||
index: number,
|
||||
context: z.RefinementCtx,
|
||||
context: GraphIssueContext,
|
||||
): void => {
|
||||
if (node.node_id !== nodeId(node))
|
||||
context.addIssue({
|
||||
@@ -306,8 +314,16 @@ type GraphRecord = z.infer<typeof javascriptApplicationGraphRecordSchema>;
|
||||
|
||||
const checkGraphContent = (
|
||||
graph: JavaScriptApplicationGraphInput,
|
||||
context: z.RefinementCtx,
|
||||
context: GraphIssueContext,
|
||||
): void => {
|
||||
const steps = checkGraphContentSteps(graph, context);
|
||||
while (steps.next().done !== true);
|
||||
};
|
||||
|
||||
function* checkGraphContentSteps(
|
||||
graph: JavaScriptApplicationGraphInput,
|
||||
context: GraphIssueContext,
|
||||
): Generator<void, void> {
|
||||
sortedUniqueIssue(
|
||||
graph.root_node_ids,
|
||||
["root_node_ids"],
|
||||
@@ -353,9 +369,12 @@ const checkGraphContent = (
|
||||
message: "Root identifier must name a graph node",
|
||||
path: ["root_node_ids"],
|
||||
});
|
||||
for (const [index, node] of graph.nodes.entries())
|
||||
for (const [index, node] of graph.nodes.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
checkNode(node, index, context);
|
||||
}
|
||||
for (const [index, edge] of graph.edges.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const { edge_id: identifier, ...semantic } = edge;
|
||||
if (identifier !== edgeId(semantic))
|
||||
context.addIssue({
|
||||
@@ -394,11 +413,11 @@ const checkGraphContent = (
|
||||
context,
|
||||
);
|
||||
}
|
||||
};
|
||||
}
|
||||
|
||||
const checkGraphInvariants = (
|
||||
graph: GraphRecord,
|
||||
context: z.RefinementCtx,
|
||||
context: GraphIssueContext,
|
||||
): void => {
|
||||
checkGraphContent(graph, context);
|
||||
const { graph_id: identifier, ...semantic } = graph;
|
||||
@@ -475,22 +494,9 @@ export const createJavaScriptApplicationEdge = (
|
||||
export const createJavaScriptApplicationGraph = (
|
||||
input: unknown,
|
||||
): JavaScriptApplicationGraph => {
|
||||
const parsed = javascriptApplicationGraphInputSchema.parse(input);
|
||||
const semantic: JavaScriptApplicationGraphInput = {
|
||||
...parsed,
|
||||
root_node_ids: uniqueSorted(parsed.root_node_ids),
|
||||
nodes: [...parsed.nodes].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.node_id, right.node_id),
|
||||
),
|
||||
edges: [...parsed.edges].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.edge_id, right.edge_id),
|
||||
),
|
||||
coverage: {
|
||||
...parsed.coverage,
|
||||
limits: normalizeLimits(parsed.coverage.limits),
|
||||
},
|
||||
limitations: uniqueSorted(parsed.limitations),
|
||||
};
|
||||
const semantic = normalizeGraphInput(
|
||||
javascriptApplicationGraphInputSchema.parse(input),
|
||||
);
|
||||
const content = javascriptApplicationGraphContentSchema.parse(semantic);
|
||||
return {
|
||||
...content,
|
||||
@@ -498,6 +504,24 @@ export const createJavaScriptApplicationGraph = (
|
||||
};
|
||||
};
|
||||
|
||||
const normalizeGraphInput = (
|
||||
parsed: JavaScriptApplicationGraphInput,
|
||||
): JavaScriptApplicationGraphInput => ({
|
||||
...parsed,
|
||||
root_node_ids: uniqueSorted(parsed.root_node_ids),
|
||||
nodes: [...parsed.nodes].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.node_id, right.node_id),
|
||||
),
|
||||
edges: [...parsed.edges].sort((left, right) =>
|
||||
compareUnicodeCodePoints(left.edge_id, right.edge_id),
|
||||
),
|
||||
coverage: {
|
||||
...parsed.coverage,
|
||||
limits: normalizeLimits(parsed.coverage.limits),
|
||||
},
|
||||
limitations: uniqueSorted(parsed.limitations),
|
||||
});
|
||||
|
||||
const validatedImmutableApplicationGraphs = new WeakSet<object>();
|
||||
|
||||
/** Clone and validate synchronously, then return steps to seal the owned graph. */
|
||||
@@ -506,6 +530,65 @@ export const createImmutableJavaScriptApplicationGraphSteps = (
|
||||
): Generator<void, JavaScriptApplicationGraph> =>
|
||||
sealValidatedApplicationGraphSteps(createJavaScriptApplicationGraph(input));
|
||||
|
||||
const applicationGraphShape = javascriptApplicationGraphInputSchema.shape;
|
||||
const applicationGraphContainerSchema =
|
||||
javascriptApplicationGraphInputSchema.extend({
|
||||
nodes: arrayContainerSchema(applicationGraphShape.nodes),
|
||||
edges: arrayContainerSchema(applicationGraphShape.edges),
|
||||
});
|
||||
|
||||
/**
|
||||
* Seal a graph whose input the caller transfers: the caller neither retains nor
|
||||
* mutates any part of it afterwards. Only the graph's own fields are validated
|
||||
* synchronously; nodes and edges are validated, checked, hashed and frozen in
|
||||
* steps, because doing so at once held the event loop for large applications.
|
||||
*/
|
||||
export const sealTransferredJavaScriptApplicationGraphSteps = (
|
||||
input: unknown,
|
||||
): Generator<void, JavaScriptApplicationGraph> =>
|
||||
parseAndSealApplicationGraphSteps(
|
||||
applicationGraphContainerSchema.parse(input),
|
||||
);
|
||||
|
||||
function* parseAndSealApplicationGraphSteps(
|
||||
container: z.output<typeof applicationGraphContainerSchema>,
|
||||
): Generator<void, JavaScriptApplicationGraph> {
|
||||
const issues: z.core.$ZodIssue[] = [];
|
||||
const parsed: JavaScriptApplicationGraphInput = {
|
||||
...container,
|
||||
nodes: yield* parseElementSteps(
|
||||
applicationGraphShape.nodes.element,
|
||||
container.nodes,
|
||||
["nodes"],
|
||||
issues,
|
||||
),
|
||||
edges: yield* parseElementSteps(
|
||||
applicationGraphShape.edges.element,
|
||||
container.edges,
|
||||
["edges"],
|
||||
issues,
|
||||
),
|
||||
};
|
||||
if (issues.length > 0) throw new z.ZodError(issues);
|
||||
const content = normalizeGraphInput(parsed);
|
||||
let invalid = false;
|
||||
yield* checkGraphContentSteps(content, {
|
||||
addIssue: () => {
|
||||
invalid = true;
|
||||
},
|
||||
});
|
||||
// An invalid owned graph is a construction defect; report it with the exact
|
||||
// issues the content schema produces.
|
||||
if (invalid) {
|
||||
javascriptApplicationGraphContentSchema.parse(content);
|
||||
throw new TypeError("Application graph checks disagree with its schema");
|
||||
}
|
||||
return yield* sealValidatedApplicationGraphSteps({
|
||||
...content,
|
||||
graph_id: `jag_${yield* canonicalJsonDigestSteps(content)}`,
|
||||
});
|
||||
}
|
||||
|
||||
function* sealValidatedApplicationGraphSteps(
|
||||
graph: JavaScriptApplicationGraph,
|
||||
): Generator<void, JavaScriptApplicationGraph> {
|
||||
|
||||
@@ -597,11 +597,9 @@ describe("property mutation collection on minified bundles", () => {
|
||||
{ length: 2000 },
|
||||
(_, index) => `source.p${index} = ${index};`,
|
||||
).join(" ");
|
||||
const start = performance.now();
|
||||
const value = resultValue(
|
||||
`const source = { token: "TOKEN" }; ${writes} return [source.token, source.p1999];`,
|
||||
);
|
||||
expect(performance.now() - start).toBeLessThan(2000);
|
||||
expect(value).toMatchObject({
|
||||
status: "array",
|
||||
items: [
|
||||
@@ -610,6 +608,21 @@ describe("property mutation collection on minified bundles", () => {
|
||||
],
|
||||
});
|
||||
}, 30000);
|
||||
|
||||
it("indexes many returned object methods instead of rescanning the object", () => {
|
||||
const methods = Array.from(
|
||||
{ length: 2000 },
|
||||
(_, index) => `m${index}() { return shared; }`,
|
||||
).join(",");
|
||||
const writes = Array.from(
|
||||
{ length: 2000 },
|
||||
(_, index) => `box.m${index}().p${index} = ${index};`,
|
||||
).join(" ");
|
||||
const value = resultValue(
|
||||
`const shared = { token: "TOKEN" }; const box = { ${methods} }; ${writes} return shared.token;`,
|
||||
);
|
||||
expect(value?.status).toBe("unknown");
|
||||
}, 30000);
|
||||
});
|
||||
|
||||
describe("results of methods on an escaped receiver", () => {
|
||||
|
||||
@@ -33,12 +33,12 @@ import {
|
||||
} from "./javascriptSemanticState.js";
|
||||
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
|
||||
import { semanticRequireOrigin } from "./javascriptSemanticRequireOrigin.js";
|
||||
import { collectSemanticMemberMutations } from "./javascriptSemanticMemberMutations.js";
|
||||
import { collectSemanticMemberMutationsSteps } from "./javascriptSemanticMemberMutations.js";
|
||||
import {
|
||||
collectSemanticReturns,
|
||||
resolveSemanticModuleCallables,
|
||||
} from "./javascriptSemanticReturns.js";
|
||||
import { collectJavaScriptDerivedSemantics } from "./javascriptSemanticDerivedAnalysis.js";
|
||||
import { collectJavaScriptDerivedSemanticsSteps } from "./javascriptSemanticDerivedAnalysis.js";
|
||||
import { range } from "./javascriptStaticAnalysisHelpers.js";
|
||||
import { propertyName } from "./javascriptAstValues.js";
|
||||
import { semanticCoverage } from "./javascriptSemanticCoverage.js";
|
||||
@@ -107,18 +107,39 @@ export const analyzeParsedJavaScriptReferences = (
|
||||
export const analyzeParsedJavaScriptSemantics = (
|
||||
file: ParsedJavaScriptSource,
|
||||
): JavaScriptSemanticIr => {
|
||||
const steps = analyzeParsedJavaScriptSemanticsSteps(file);
|
||||
for (;;) {
|
||||
const step = steps.next();
|
||||
if (step.done === true) return step.value;
|
||||
}
|
||||
};
|
||||
|
||||
/**
|
||||
* Recover semantics from a parsed artifact with a yield between analysis
|
||||
* phases, so a caller can serve control messages within one large file.
|
||||
* Each phase completes before the next starts; results equal the synchronous
|
||||
* form.
|
||||
*/
|
||||
export function* analyzeParsedJavaScriptSemanticsSteps(
|
||||
file: ParsedJavaScriptSource,
|
||||
): Generator<void, JavaScriptSemanticIr> {
|
||||
const state = createState(file.program);
|
||||
collectDefinitions(file.program, state);
|
||||
collectSemanticMemberMutations(file.program, state);
|
||||
yield;
|
||||
yield* collectSemanticMemberMutationsSteps(file.program, state);
|
||||
traverseJavaScriptAst(file.program, {
|
||||
enter: (node) => collectSemanticModuleLink(node, state),
|
||||
});
|
||||
yield;
|
||||
const references = collectSemanticReferences(file.program, state);
|
||||
yield;
|
||||
const parserPartial = file.errors.length > 0;
|
||||
const bindings = immutableSemanticBindings(state);
|
||||
yield;
|
||||
const callables = collectSemanticReturns(file.program, state, parserPartial);
|
||||
yield;
|
||||
const moduleLinks = resolveSemanticModuleCallables(state, callables);
|
||||
const derived = collectJavaScriptDerivedSemantics(
|
||||
const derived = yield* collectJavaScriptDerivedSemanticsSteps(
|
||||
file.program,
|
||||
state,
|
||||
callables,
|
||||
@@ -154,7 +175,7 @@ export const analyzeParsedJavaScriptSemantics = (
|
||||
"Cross-function mutation and dynamic property resolution remain unknown.",
|
||||
],
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
/** Receiver identity facts for the overloaded `.open` syntax only. */
|
||||
export type JavaScriptOpenReceiverFact =
|
||||
|
||||
@@ -0,0 +1,61 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
analyzeParsedJavaScriptSemantics,
|
||||
analyzeParsedJavaScriptSemanticsSteps,
|
||||
} from "./javascriptSemanticAnalysis.js";
|
||||
import { parseJavaScriptSource } from "./javascriptSourceParser.js";
|
||||
import {
|
||||
traverseJavaScriptAst,
|
||||
traverseJavaScriptAstSteps,
|
||||
} from "./javascriptSemanticTraversal.js";
|
||||
|
||||
const source = `
|
||||
import { readFile } from "node:fs";
|
||||
const shared = { token: "TOKEN" };
|
||||
export function load(path) {
|
||||
return new Promise((resolve) => setTimeout(() => resolve(readFile(path)), 1));
|
||||
}
|
||||
export const box = { get() { return shared; } };
|
||||
box.get().value = process.env.MODE ?? "default";
|
||||
`;
|
||||
|
||||
it("yields between semantic phases and returns the synchronous result (#1462)", () => {
|
||||
const parsed = parseJavaScriptSource(source, "main.js");
|
||||
if (parsed === null) throw new Error("Expected parsed source");
|
||||
const steps = analyzeParsedJavaScriptSemanticsSteps(parsed);
|
||||
let yields = 0;
|
||||
let step = steps.next();
|
||||
while (step.done !== true) {
|
||||
yields += 1;
|
||||
step = steps.next();
|
||||
}
|
||||
// Every top-level phase and derived collector is a separate step.
|
||||
expect(yields).toBeGreaterThanOrEqual(13);
|
||||
const reparsed = parseJavaScriptSource(source, "main.js");
|
||||
if (reparsed === null) throw new Error("Expected parsed source");
|
||||
expect(step.value).toEqual(analyzeParsedJavaScriptSemantics(reparsed));
|
||||
});
|
||||
|
||||
it("traverses a large tree in steps with the synchronous visit order (#1462)", () => {
|
||||
const parsed = parseJavaScriptSource(
|
||||
Array.from(
|
||||
{ length: 400 },
|
||||
(_, index) => `const v${index} = [${index}];`,
|
||||
).join("\n"),
|
||||
"large.js",
|
||||
);
|
||||
if (parsed === null) throw new Error("Expected parsed source");
|
||||
const visits = (record: string[]) => ({
|
||||
enter: (node: { readonly type: string }) => record.push(`+${node.type}`),
|
||||
exit: (node: { readonly type: string }) => record.push(`-${node.type}`),
|
||||
});
|
||||
const synchronous: string[] = [];
|
||||
traverseJavaScriptAst(parsed.program, visits(synchronous));
|
||||
const stepped: string[] = [];
|
||||
const steps = traverseJavaScriptAstSteps(parsed.program, visits(stepped));
|
||||
let yields = 0;
|
||||
while (steps.next().done !== true) yields += 1;
|
||||
expect(yields).toBeGreaterThan(0);
|
||||
expect(stepped).toEqual(synchronous);
|
||||
});
|
||||
@@ -3,7 +3,7 @@ import type * as t from "@babel/types";
|
||||
import { collectJavaScriptSemanticAsyncEffects } from "./javascriptSemanticAsyncEffects.js";
|
||||
import { collectJavaScriptSemanticCalls } from "./javascriptSemanticCalls.js";
|
||||
import { collectJavaScriptSemanticChildProcesses } from "./javascriptSemanticChildProcesses.js";
|
||||
import { collectJavaScriptSemanticFingerprints } from "./javascriptSemanticFingerprints.js";
|
||||
import { collectJavaScriptSemanticFingerprintsSteps } from "./javascriptSemanticFingerprints.js";
|
||||
import { collectJavaScriptSemanticDataEffects } from "./javascriptSemanticDataEffects.js";
|
||||
import type {
|
||||
JavaScriptSemanticCallable,
|
||||
@@ -36,56 +36,68 @@ type DerivedSemanticAnalysis = Pick<
|
||||
>;
|
||||
|
||||
/** Compose bounded semantic passes after lexical definitions are available. */
|
||||
export const collectJavaScriptDerivedSemantics = (
|
||||
/**
|
||||
* Collect derived semantics with a yield between collectors. Each collector
|
||||
* completes before the next starts, so results equal the synchronous form.
|
||||
*/
|
||||
export function* collectJavaScriptDerivedSemanticsSteps(
|
||||
program: t.Program,
|
||||
state: JavaScriptSemanticAnalysisState,
|
||||
callables: readonly JavaScriptSemanticCallable[],
|
||||
parserPartial: boolean,
|
||||
): DerivedSemanticAnalysis => {
|
||||
): Generator<void, DerivedSemanticAnalysis> {
|
||||
const calls = collectJavaScriptSemanticCalls(program, state, callables);
|
||||
yield;
|
||||
const promiseOperations = collectJavaScriptSemanticPromises(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
yield;
|
||||
const asyncEffects = collectJavaScriptSemanticAsyncEffects(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
yield;
|
||||
const childProcesses = collectJavaScriptSemanticChildProcesses(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
yield;
|
||||
const dataEffects = collectJavaScriptSemanticDataEffects(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
yield;
|
||||
const resourceOperations = collectJavaScriptSemanticResources(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
yield;
|
||||
const objectOperations = collectJavaScriptSemanticObjects(
|
||||
program,
|
||||
state,
|
||||
callables,
|
||||
);
|
||||
const functionFingerprints = collectJavaScriptSemanticFingerprints({
|
||||
state,
|
||||
callables,
|
||||
calls,
|
||||
promises: promiseOperations,
|
||||
events: asyncEffects.eventOperations,
|
||||
timers: asyncEffects.timerOperations,
|
||||
childProcessSpawns: childProcesses.childProcessSpawns,
|
||||
childProcessInteractions: childProcesses.childProcessInteractions,
|
||||
requestOperations: dataEffects.requestOperations,
|
||||
resourceOperations,
|
||||
parserPartial,
|
||||
});
|
||||
yield;
|
||||
const functionFingerprints =
|
||||
yield* collectJavaScriptSemanticFingerprintsSteps({
|
||||
state,
|
||||
callables,
|
||||
calls,
|
||||
promises: promiseOperations,
|
||||
events: asyncEffects.eventOperations,
|
||||
timers: asyncEffects.timerOperations,
|
||||
childProcessSpawns: childProcesses.childProcessSpawns,
|
||||
childProcessInteractions: childProcesses.childProcessInteractions,
|
||||
requestOperations: dataEffects.requestOperations,
|
||||
resourceOperations,
|
||||
parserPartial,
|
||||
});
|
||||
return {
|
||||
...calls,
|
||||
promiseOperations,
|
||||
@@ -96,4 +108,4 @@ export const collectJavaScriptDerivedSemantics = (
|
||||
objectOperations,
|
||||
functionFingerprints,
|
||||
};
|
||||
};
|
||||
}
|
||||
|
||||
@@ -17,7 +17,7 @@ import type {
|
||||
} from "./javascriptSemanticIr.js";
|
||||
import { semanticCallableIdForNode } from "./javascriptSemanticProjection.js";
|
||||
import type { JavaScriptSemanticAnalysisState } from "./javascriptSemanticState.js";
|
||||
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
|
||||
import { traverseJavaScriptAstSteps } from "./javascriptSemanticTraversal.js";
|
||||
|
||||
interface SemanticFingerprintCollectionInput {
|
||||
readonly state: JavaScriptSemanticAnalysisState;
|
||||
@@ -33,10 +33,10 @@ interface SemanticFingerprintCollectionInput {
|
||||
readonly parserPartial: boolean;
|
||||
}
|
||||
|
||||
/** Build bounded rename- and formatting-resistant components per callable. */
|
||||
export const collectJavaScriptSemanticFingerprints = (
|
||||
/** Build bounded rename- and formatting-resistant components per callable, yielding between callables. */
|
||||
export function* collectJavaScriptSemanticFingerprintsSteps(
|
||||
input: SemanticFingerprintCollectionInput,
|
||||
): JavaScriptSemanticFunctionFingerprint[] => {
|
||||
): Generator<void, JavaScriptSemanticFunctionFingerprint[]> {
|
||||
const {
|
||||
state,
|
||||
callables,
|
||||
@@ -67,11 +67,13 @@ export const collectJavaScriptSemanticFingerprints = (
|
||||
);
|
||||
const networkEffectsByOwner = groupByOwner(requestOperations, ownerId);
|
||||
const resourceEffectsByOwner = groupByOwner(resourceOperations, ownerId);
|
||||
return callables.flatMap((callable) => {
|
||||
if (callable.kind === "class") return [];
|
||||
const fingerprints: JavaScriptSemanticFunctionFingerprint[] = [];
|
||||
for (const callable of callables) {
|
||||
if (callable.kind === "class") continue;
|
||||
const node = state.callableNodesById.get(callable.callableId);
|
||||
if (node === undefined) return [];
|
||||
const syntax = fingerprintSyntax(node, callable.callableId);
|
||||
if (node === undefined) continue;
|
||||
yield;
|
||||
const syntax = yield* fingerprintSyntaxSteps(node, callable.callableId);
|
||||
const promiseEffects = promiseEffectsByOwner.get(callable.callableId) ?? [];
|
||||
const eventEffects = eventEffectsByOwner.get(callable.callableId) ?? [];
|
||||
const timerEffects = timerEffectsByOwner.get(callable.callableId) ?? [];
|
||||
@@ -80,50 +82,49 @@ export const collectJavaScriptSemanticFingerprints = (
|
||||
const networkEffects = networkEffectsByOwner.get(callable.callableId) ?? [];
|
||||
const resourceEffects =
|
||||
resourceEffectsByOwner.get(callable.callableId) ?? [];
|
||||
return [
|
||||
{
|
||||
callableId: callable.callableId,
|
||||
status:
|
||||
parserPartial || callable.returnCoverage.status !== "complete"
|
||||
? "partial"
|
||||
: "complete",
|
||||
components: {
|
||||
parameterArity: callableParameterArity(node),
|
||||
normalizedAstSha256: digest(syntax.normalizedTokens),
|
||||
controlFlowSha256: digest(syntax.controlFlowTokens),
|
||||
relationShapeSha256: digest(
|
||||
relationShape(
|
||||
callable,
|
||||
callSitesByCaller.get(callable.callableId) ?? [],
|
||||
captureCountByCallable.get(callable.callableId) ?? 0,
|
||||
promiseEffects,
|
||||
),
|
||||
fingerprints.push({
|
||||
callableId: callable.callableId,
|
||||
status:
|
||||
parserPartial || callable.returnCoverage.status !== "complete"
|
||||
? "partial"
|
||||
: "complete",
|
||||
components: {
|
||||
parameterArity: callableParameterArity(node),
|
||||
normalizedAstSha256: digest(syntax.normalizedTokens),
|
||||
controlFlowSha256: digest(syntax.controlFlowTokens),
|
||||
relationShapeSha256: digest(
|
||||
relationShape(
|
||||
callable,
|
||||
callSitesByCaller.get(callable.callableId) ?? [],
|
||||
captureCountByCallable.get(callable.callableId) ?? 0,
|
||||
promiseEffects,
|
||||
),
|
||||
literalSetSha256: digest(
|
||||
[...new Set(syntax.literals)].sort(compareUnicodeCodePoints),
|
||||
),
|
||||
effects: [
|
||||
...(isAsyncCallable(node) ? (["async"] as const) : []),
|
||||
...(childProcessEffects.length > 0
|
||||
? (["child-process"] as const)
|
||||
: []),
|
||||
...(eventEffects.length > 0 ? (["event"] as const) : []),
|
||||
...(networkEffects.length > 0 ? (["network"] as const) : []),
|
||||
...(promiseEffects.length > 0 ? (["promise"] as const) : []),
|
||||
...(resourceEffects.length > 0 ? (["resource"] as const) : []),
|
||||
...(timerEffects.length > 0 ? (["timer"] as const) : []),
|
||||
],
|
||||
},
|
||||
limitations: [
|
||||
"The fingerprint is a static candidate and does not prove behavioral equivalence.",
|
||||
...(parserPartial
|
||||
? ["Incomplete semantic recovery makes this fingerprint partial."]
|
||||
),
|
||||
literalSetSha256: digest(
|
||||
[...new Set(syntax.literals)].sort(compareUnicodeCodePoints),
|
||||
),
|
||||
effects: [
|
||||
...(isAsyncCallable(node) ? (["async"] as const) : []),
|
||||
...(childProcessEffects.length > 0
|
||||
? (["child-process"] as const)
|
||||
: []),
|
||||
...(eventEffects.length > 0 ? (["event"] as const) : []),
|
||||
...(networkEffects.length > 0 ? (["network"] as const) : []),
|
||||
...(promiseEffects.length > 0 ? (["promise"] as const) : []),
|
||||
...(resourceEffects.length > 0 ? (["resource"] as const) : []),
|
||||
...(timerEffects.length > 0 ? (["timer"] as const) : []),
|
||||
],
|
||||
},
|
||||
];
|
||||
});
|
||||
};
|
||||
limitations: [
|
||||
"The fingerprint is a static candidate and does not prove behavioral equivalence.",
|
||||
...(parserPartial
|
||||
? ["Incomplete semantic recovery makes this fingerprint partial."]
|
||||
: []),
|
||||
],
|
||||
});
|
||||
}
|
||||
return fingerprints;
|
||||
}
|
||||
|
||||
const ownerId = <T extends { readonly ownerCallableId: string | null }>(
|
||||
value: T,
|
||||
@@ -161,15 +162,15 @@ interface FingerprintSyntax {
|
||||
readonly literals: readonly string[];
|
||||
}
|
||||
|
||||
const fingerprintSyntax = (
|
||||
function* fingerprintSyntaxSteps(
|
||||
root: t.Node,
|
||||
targetCallableId: string,
|
||||
): FingerprintSyntax => {
|
||||
): Generator<void, FingerprintSyntax> {
|
||||
const normalizedTokens: string[] = [];
|
||||
const controlFlowTokens: string[] = [];
|
||||
const literals: string[] = [];
|
||||
const callableStack: string[] = [];
|
||||
traverseJavaScriptAst(root, {
|
||||
yield* traverseJavaScriptAstSteps(root, {
|
||||
enter: (node, parent) => {
|
||||
const callableId = semanticCallableIdForNode(node);
|
||||
if (callableId !== null) callableStack.push(callableId);
|
||||
@@ -187,7 +188,7 @@ const fingerprintSyntax = (
|
||||
},
|
||||
});
|
||||
return { normalizedTokens, controlFlowTokens, literals };
|
||||
};
|
||||
}
|
||||
|
||||
const normalizedNodeToken = (node: t.Node, parent: t.Node | null): string => {
|
||||
if (t.isIdentifier(node))
|
||||
|
||||
@@ -6,6 +6,10 @@ import { uniqueSorted } from "../canonicalOrdering.js";
|
||||
import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
|
||||
import { canonicalJsonDigestSteps } from "../canonicalJsonDigestSteps.js";
|
||||
import { freezeOwnedJsonSnapshotSteps } from "../immutableJson.js";
|
||||
import {
|
||||
arrayContainerSchema,
|
||||
parseElementSteps,
|
||||
} from "../zodCollectionSteps.js";
|
||||
import type {
|
||||
ApplicationGraphEvidence,
|
||||
ApplicationGraphEvidenceContext,
|
||||
@@ -765,6 +769,15 @@ export const createJavaScriptSemanticGraph = (
|
||||
|
||||
const validatedImmutableSemanticGraphs = new WeakSet<object>();
|
||||
|
||||
const semanticGraphShape = javaScriptSemanticGraphInputSchema.shape;
|
||||
const semanticGraphContainerSchema = javaScriptSemanticGraphInputSchema.extend({
|
||||
evidence_contexts: arrayContainerSchema(semanticGraphShape.evidence_contexts),
|
||||
nodes: arrayContainerSchema(semanticGraphShape.nodes),
|
||||
relations: arrayContainerSchema(semanticGraphShape.relations),
|
||||
fingerprints: arrayContainerSchema(semanticGraphShape.fingerprints),
|
||||
unknowns: arrayContainerSchema(semanticGraphShape.unknowns),
|
||||
});
|
||||
|
||||
/** Clone input synchronously; commit, check and seal the owned graph in steps. */
|
||||
export const createImmutableJavaScriptSemanticGraphSteps = (
|
||||
input: unknown,
|
||||
@@ -773,6 +786,58 @@ export const createImmutableJavaScriptSemanticGraphSteps = (
|
||||
normalizeGraphInput(javaScriptSemanticGraphInputSchema.parse(input)),
|
||||
);
|
||||
|
||||
/**
|
||||
* Seal a graph whose input the caller transfers: the caller neither retains nor
|
||||
* mutates any part of it afterwards. Only the graph's own fields are validated
|
||||
* synchronously; collection elements are validated and cloned in steps, because
|
||||
* a whole-graph parse of a large application held the event loop for seconds.
|
||||
*/
|
||||
export const sealTransferredJavaScriptSemanticGraphSteps = (
|
||||
input: unknown,
|
||||
): Generator<void, JavaScriptSemanticGraph> =>
|
||||
parseAndSealSemanticGraphSteps(semanticGraphContainerSchema.parse(input));
|
||||
|
||||
function* parseAndSealSemanticGraphSteps(
|
||||
container: z.output<typeof semanticGraphContainerSchema>,
|
||||
): Generator<void, JavaScriptSemanticGraph> {
|
||||
const issues: z.core.$ZodIssue[] = [];
|
||||
const parsed: JavaScriptSemanticGraphInput = {
|
||||
...container,
|
||||
evidence_contexts: yield* parseElementSteps(
|
||||
semanticGraphShape.evidence_contexts.element,
|
||||
container.evidence_contexts,
|
||||
["evidence_contexts"],
|
||||
issues,
|
||||
),
|
||||
nodes: yield* parseElementSteps(
|
||||
semanticGraphShape.nodes.element,
|
||||
container.nodes,
|
||||
["nodes"],
|
||||
issues,
|
||||
),
|
||||
relations: yield* parseElementSteps(
|
||||
semanticGraphShape.relations.element,
|
||||
container.relations,
|
||||
["relations"],
|
||||
issues,
|
||||
),
|
||||
fingerprints: yield* parseElementSteps(
|
||||
semanticGraphShape.fingerprints.element,
|
||||
container.fingerprints,
|
||||
["fingerprints"],
|
||||
issues,
|
||||
),
|
||||
unknowns: yield* parseElementSteps(
|
||||
semanticGraphShape.unknowns.element,
|
||||
container.unknowns,
|
||||
["unknowns"],
|
||||
issues,
|
||||
),
|
||||
};
|
||||
if (issues.length > 0) throw new z.ZodError(issues);
|
||||
return yield* validateAndSealSemanticGraphSteps(normalizeGraphInput(parsed));
|
||||
}
|
||||
|
||||
function* validateAndSealSemanticGraphSteps(
|
||||
semantic: JavaScriptSemanticGraphInput,
|
||||
): Generator<void, JavaScriptSemanticGraph> {
|
||||
|
||||
@@ -25,7 +25,7 @@ import {
|
||||
type JavaScriptSemanticPropertyPath,
|
||||
} from "./javascriptSemanticPropertyPaths.js";
|
||||
import { compareUnicodeCodePoints } from "../unicodeCodePointOrder.js";
|
||||
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
|
||||
import { traverseJavaScriptAstSteps } from "./javascriptSemanticTraversal.js";
|
||||
import {
|
||||
semanticStaticPropertyKey,
|
||||
unwrapJavaScriptExpression,
|
||||
@@ -34,13 +34,13 @@ import {
|
||||
type PropertyPath = JavaScriptSemanticPropertyPath;
|
||||
type ValueEffect = "write" | "escape";
|
||||
|
||||
/** Preserve uncertainty from property writes and references exposed to calls. */
|
||||
export const collectSemanticMemberMutations = (
|
||||
/** Preserve uncertainty from property writes and references exposed to calls, yielding during traversal and fixpoint iteration. */
|
||||
export function* collectSemanticMemberMutationsSteps(
|
||||
program: t.Program,
|
||||
state: JavaScriptSemanticAnalysisState,
|
||||
): void => {
|
||||
): Generator<void, void> {
|
||||
const parents = state.parentsByNode;
|
||||
traverseJavaScriptAst(program, {
|
||||
yield* traverseJavaScriptAstSteps(program, {
|
||||
enter: (node, parent) => {
|
||||
if (parent !== null) parents.set(node, parent);
|
||||
},
|
||||
@@ -343,7 +343,8 @@ export const collectSemanticMemberMutations = (
|
||||
if (paths.has(pathKey)) continue;
|
||||
paths.add(pathKey);
|
||||
expanded.set(node, paths);
|
||||
pending.push(...expandedValues(node, value.path, "escape"));
|
||||
for (const reference of expandedValues(node, value.path, "escape"))
|
||||
pending.push(reference);
|
||||
}
|
||||
}
|
||||
const byPath = escapedLeaves.get(root) ?? new Map();
|
||||
@@ -381,7 +382,7 @@ export const collectSemanticMemberMutations = (
|
||||
);
|
||||
}
|
||||
};
|
||||
traverseJavaScriptAst(program, {
|
||||
yield* traverseJavaScriptAstSteps(program, {
|
||||
enter: (node, parent) => {
|
||||
for (const source of semanticIterationSources(node, parent))
|
||||
deferIterable({
|
||||
@@ -434,7 +435,8 @@ export const collectSemanticMemberMutations = (
|
||||
const effectsBefore = recordedEffects.size;
|
||||
const iterablesBefore = iterableReferences.length;
|
||||
const iterationBefore: boolean = arrayIterationUnknown;
|
||||
for (const reference of pendingReferences.splice(0)) {
|
||||
for (const [index, reference] of pendingReferences.splice(0).entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const { initializer } = reference;
|
||||
if (referenceSourcesInactive(initializer, state))
|
||||
pendingReferences.push(reference);
|
||||
@@ -479,7 +481,8 @@ export const collectSemanticMemberMutations = (
|
||||
reference.originAt,
|
||||
);
|
||||
}
|
||||
for (const reference of [...iterableReferences]) {
|
||||
for (const [index, reference] of [...iterableReferences].entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
if (referenceSourcesInactive(reference, state)) continue;
|
||||
if (reference.iterationOnly) {
|
||||
const expanded = expandedIterationReferences(reference, state);
|
||||
@@ -517,7 +520,7 @@ export const collectSemanticMemberMutations = (
|
||||
// Gathering effects can evaluate a primitive projection before its object
|
||||
// escapes. Final values must use the completed mutation state.
|
||||
clearSemanticPrimitiveBindingValues(state);
|
||||
};
|
||||
}
|
||||
|
||||
interface ReferencedValue {
|
||||
readonly node: t.Node;
|
||||
|
||||
@@ -30,6 +30,22 @@ interface Candidate {
|
||||
readonly bindings: ReadonlySet<string>;
|
||||
}
|
||||
|
||||
interface ObjectTargetIndex {
|
||||
readonly propertyByName: ReadonlyMap<
|
||||
string,
|
||||
t.ObjectMethod | t.ObjectProperty
|
||||
>;
|
||||
readonly trailingUnknownsByProperty: ReadonlyMap<
|
||||
t.ObjectMethod | t.ObjectProperty,
|
||||
ObjectTargetUnknown
|
||||
>;
|
||||
}
|
||||
|
||||
interface ObjectTargetUnknown {
|
||||
readonly node: t.ObjectMethod | t.ObjectProperty | t.SpreadElement;
|
||||
readonly previous: ObjectTargetUnknown | undefined;
|
||||
}
|
||||
|
||||
/** Resolve local result references conservatively, without claiming call execution. */
|
||||
export const createSemanticReturnedReferences = (
|
||||
state: JavaScriptSemanticAnalysisState,
|
||||
@@ -39,6 +55,7 @@ export const createSemanticReturnedReferences = (
|
||||
);
|
||||
const bindingCache = new Map<string, LocalCallableResolution>();
|
||||
const results = new WeakMap<t.Node, readonly SemanticReturnedReference[]>();
|
||||
const objectTargets = new WeakMap<t.ObjectExpression, ObjectTargetIndex>();
|
||||
return (callee) => {
|
||||
const existing = results.get(callee);
|
||||
if (existing !== undefined) return existing;
|
||||
@@ -115,7 +132,7 @@ export const createSemanticReturnedReferences = (
|
||||
} else if (t.isFunction(node) && item.path.length === 0)
|
||||
functions.add(node);
|
||||
else if (t.isObjectExpression(node))
|
||||
selectObjectTargets(node, item, pending);
|
||||
selectObjectTargets(node, item, pending, objectTargets);
|
||||
else if (t.isArrayExpression(node)) {
|
||||
const [key, ...path] = item.path;
|
||||
const index =
|
||||
@@ -187,8 +204,38 @@ const selectObjectTargets = (
|
||||
node: t.ObjectExpression,
|
||||
item: Candidate,
|
||||
pending: Candidate[],
|
||||
indexes: WeakMap<t.ObjectExpression, ObjectTargetIndex>,
|
||||
): void => {
|
||||
const [key, ...path] = item.path;
|
||||
if (key !== null && key !== undefined) {
|
||||
const index = objectTargetIndex(node, indexes);
|
||||
const property = index.propertyByName.get(String(key));
|
||||
if (property !== undefined) {
|
||||
const unknowns: ObjectTargetUnknown[] = [];
|
||||
for (
|
||||
let unknown = index.trailingUnknownsByProperty.get(property);
|
||||
unknown !== undefined;
|
||||
unknown = unknown.previous
|
||||
)
|
||||
unknowns.push(unknown);
|
||||
for (const { node: unknown } of unknowns.reverse())
|
||||
pending.push({
|
||||
...item,
|
||||
node: t.isSpreadElement(unknown)
|
||||
? unknown.argument
|
||||
: t.isObjectProperty(unknown)
|
||||
? unknown.value
|
||||
: unknown,
|
||||
...(t.isSpreadElement(unknown) ? {} : { path }),
|
||||
});
|
||||
pending.push({
|
||||
...item,
|
||||
node: t.isObjectProperty(property) ? property.value : property,
|
||||
path,
|
||||
});
|
||||
return;
|
||||
}
|
||||
}
|
||||
let replaced = false;
|
||||
for (const property of [...node.properties].reverse()) {
|
||||
if (replaced) break;
|
||||
@@ -211,3 +258,35 @@ const selectObjectTargets = (
|
||||
replaced = true;
|
||||
}
|
||||
};
|
||||
|
||||
const objectTargetIndex = (
|
||||
node: t.ObjectExpression,
|
||||
indexes: WeakMap<t.ObjectExpression, ObjectTargetIndex>,
|
||||
): ObjectTargetIndex => {
|
||||
const existing = indexes.get(node);
|
||||
if (existing !== undefined) return existing;
|
||||
const propertyByName = new Map<string, t.ObjectMethod | t.ObjectProperty>();
|
||||
const trailingUnknownsByProperty = new Map<
|
||||
t.ObjectMethod | t.ObjectProperty,
|
||||
ObjectTargetUnknown
|
||||
>();
|
||||
let trailingUnknown: ObjectTargetUnknown | undefined;
|
||||
for (const property of [...node.properties].reverse()) {
|
||||
if (t.isSpreadElement(property)) {
|
||||
trailingUnknown = { node: property, previous: trailingUnknown };
|
||||
continue;
|
||||
}
|
||||
const name = semanticStaticPropertyKey(property.key, property.computed);
|
||||
if (name === null) {
|
||||
trailingUnknown = { node: property, previous: trailingUnknown };
|
||||
continue;
|
||||
}
|
||||
if (propertyByName.has(name)) continue;
|
||||
propertyByName.set(name, property);
|
||||
if (trailingUnknown !== undefined)
|
||||
trailingUnknownsByProperty.set(property, trailingUnknown);
|
||||
}
|
||||
const created = { propertyByName, trailingUnknownsByProperty };
|
||||
indexes.set(node, created);
|
||||
return created;
|
||||
};
|
||||
|
||||
@@ -12,15 +12,28 @@ import * as t from "@babel/types";
|
||||
*/
|
||||
export const traverseJavaScriptAst = (
|
||||
root: t.Node,
|
||||
visitor: {
|
||||
readonly enter: (
|
||||
node: t.Node,
|
||||
parent: t.Node | null,
|
||||
readAncestors: () => readonly t.Node[],
|
||||
) => void;
|
||||
readonly exit?: (node: t.Node, parent: t.Node | null) => void;
|
||||
},
|
||||
): void => {
|
||||
visitor: JavaScriptAstVisitor,
|
||||
): void => completeSemanticSteps(traverseJavaScriptAstSteps(root, visitor));
|
||||
|
||||
/** Callbacks for one deterministic AST traversal. */
|
||||
export interface JavaScriptAstVisitor {
|
||||
readonly enter: (
|
||||
node: t.Node,
|
||||
parent: t.Node | null,
|
||||
readAncestors: () => readonly t.Node[],
|
||||
) => void;
|
||||
readonly exit?: (node: t.Node, parent: t.Node | null) => void;
|
||||
}
|
||||
|
||||
/**
|
||||
* {@link traverseJavaScriptAst} with a yield every 1,024 visited nodes, so a
|
||||
* caller can serve control messages during one large traversal. Visit order
|
||||
* and callbacks are identical.
|
||||
*/
|
||||
export function* traverseJavaScriptAstSteps(
|
||||
root: t.Node,
|
||||
visitor: JavaScriptAstVisitor,
|
||||
): Generator<void, void> {
|
||||
const ancestors: t.Node[] = [];
|
||||
const enter = (node: t.Node, parent: t.Node | null): TraversalFrame => {
|
||||
visitor.enter(node, parent, () => [...ancestors]);
|
||||
@@ -28,12 +41,15 @@ export const traverseJavaScriptAst = (
|
||||
return { node, parent, children: childNodes(node), nextIndex: 0 };
|
||||
};
|
||||
const pending = [enter(root, null)];
|
||||
let visited = 1;
|
||||
while (pending.length > 0) {
|
||||
const current = pending.at(-1);
|
||||
if (current === undefined) break;
|
||||
const child = current.children[current.nextIndex];
|
||||
if (child !== undefined) {
|
||||
current.nextIndex += 1;
|
||||
if (visited % 1024 === 0) yield;
|
||||
visited += 1;
|
||||
pending.push(enter(child, current.node));
|
||||
} else {
|
||||
visitor.exit?.(current.node, current.parent);
|
||||
@@ -41,6 +57,16 @@ export const traverseJavaScriptAst = (
|
||||
pending.pop();
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
/** Run cooperative analysis steps to completion without yielding control. */
|
||||
export const completeSemanticSteps = <Value>(
|
||||
steps: Iterator<void, Value>,
|
||||
): Value => {
|
||||
for (;;) {
|
||||
const step = steps.next();
|
||||
if (step.done === true) return step.value;
|
||||
}
|
||||
};
|
||||
|
||||
interface TraversalFrame {
|
||||
|
||||
@@ -1,6 +1,9 @@
|
||||
import * as t from "@babel/types";
|
||||
|
||||
import { traverseJavaScriptAst } from "./javascriptSemanticTraversal.js";
|
||||
import {
|
||||
completeSemanticSteps,
|
||||
traverseJavaScriptAstSteps,
|
||||
} from "./javascriptSemanticTraversal.js";
|
||||
|
||||
import { inspectElectronStaticNode } from "./electronStaticAnalysis.js";
|
||||
import {
|
||||
@@ -57,9 +60,19 @@ export const analyzeParsedJavaScriptStaticSource = (
|
||||
source: string,
|
||||
file: ParsedJavaScriptSource,
|
||||
openReceiverFacts?: ReadonlyMap<number, JavaScriptOpenReceiverFact>,
|
||||
): JavaScriptStaticAnalysis => {
|
||||
): JavaScriptStaticAnalysis =>
|
||||
completeSemanticSteps(
|
||||
analyzeParsedJavaScriptStaticSourceSteps(source, file, openReceiverFacts),
|
||||
);
|
||||
|
||||
/** Static analysis that yields during its source traversal; results are unchanged. */
|
||||
export function* analyzeParsedJavaScriptStaticSourceSteps(
|
||||
source: string,
|
||||
file: ParsedJavaScriptSource,
|
||||
openReceiverFacts?: ReadonlyMap<number, JavaScriptOpenReceiverFact>,
|
||||
): Generator<void, JavaScriptStaticAnalysis> {
|
||||
const accumulator = createJavaScriptAnalysisAccumulator(source.length);
|
||||
traverseStaticSource(file, {
|
||||
yield* traverseStaticSourceSteps(file, {
|
||||
source,
|
||||
accumulator,
|
||||
...(openReceiverFacts === undefined ? {} : { openReceiverFacts }),
|
||||
@@ -67,20 +80,20 @@ export const analyzeParsedJavaScriptStaticSource = (
|
||||
});
|
||||
addSourceMapDirectives(source, file.comments ?? [], accumulator);
|
||||
return finalizeStaticAnalysis(source, file, accumulator);
|
||||
};
|
||||
}
|
||||
|
||||
const traverseStaticSource = (
|
||||
function* traverseStaticSourceSteps(
|
||||
file: ParsedJavaScriptSource,
|
||||
findings: JavaScriptFindingContext,
|
||||
): void => {
|
||||
traverseJavaScriptAst(file, {
|
||||
): Generator<void, void> {
|
||||
yield* traverseJavaScriptAstSteps(file, {
|
||||
enter: (node) => {
|
||||
findings.accumulator.visitedNodes += 1;
|
||||
inspectNode(node, findings);
|
||||
return undefined;
|
||||
},
|
||||
});
|
||||
};
|
||||
}
|
||||
|
||||
const finalizeStaticAnalysis = (
|
||||
source: string,
|
||||
|
||||
@@ -0,0 +1,33 @@
|
||||
import { z } from "zod";
|
||||
|
||||
/**
|
||||
* An array schema's own constraints, such as a minimum length, without its
|
||||
* element schema. Pair it with {@link parseElementSteps} to validate a large
|
||||
* collection in cooperative steps.
|
||||
*/
|
||||
export const arrayContainerSchema = (
|
||||
array: z.ZodArray<z.ZodType>,
|
||||
): z.ZodType<unknown[]> => array.clone({ ...array.def, element: z.unknown() });
|
||||
|
||||
/** Elements validated between yields, in the issues and paths a whole-array parse reports. */
|
||||
export function* parseElementSteps<Element extends z.ZodType>(
|
||||
element: Element,
|
||||
values: readonly unknown[],
|
||||
path: readonly PropertyKey[],
|
||||
issues: z.core.$ZodIssue[],
|
||||
): Generator<void, z.output<Element>[]> {
|
||||
const parsed: z.output<Element>[] = [];
|
||||
for (const [index, value] of values.entries()) {
|
||||
if (index % 64 === 0) yield;
|
||||
const result = element.safeParse(value);
|
||||
if (result.success) parsed.push(result.data);
|
||||
else
|
||||
issues.push(
|
||||
...result.error.issues.map((issue) => ({
|
||||
...issue,
|
||||
path: [...path, index, ...issue.path],
|
||||
})),
|
||||
);
|
||||
}
|
||||
return parsed;
|
||||
}
|
||||
@@ -75,6 +75,7 @@ interface TerminalExitOptions {
|
||||
readonly interactions: InteractionEvent[];
|
||||
readonly dispatchedEventIndexes: ReadonlySet<number>;
|
||||
readonly recordEvent: RecordProcessCaptureEvent;
|
||||
readonly onLiveProgress?: () => void;
|
||||
}
|
||||
|
||||
interface CaptureResultOptions {
|
||||
@@ -601,8 +602,10 @@ export const observeSettlement = async (
|
||||
recordEvent: RecordProcessCaptureEvent = () => undefined,
|
||||
platform: NodeJS.Platform = process.platform,
|
||||
signal?: AbortSignal,
|
||||
onLiveProgress?: () => void,
|
||||
): Promise<ObservedProcessSettlement> => {
|
||||
assertNotCancelled(signal);
|
||||
onLiveProgress?.();
|
||||
if (platform === "win32") {
|
||||
recordEvent("lifecycle", 1);
|
||||
return { state: "unverifiable", elapsed_ms: 0 };
|
||||
@@ -611,6 +614,7 @@ export const observeSettlement = async (
|
||||
let consecutiveEmpty = 0;
|
||||
let deadlineReached = false;
|
||||
while (!deadlineReached) {
|
||||
onLiveProgress?.();
|
||||
assertNotCancelled(signal);
|
||||
const observations = await Promise.all(
|
||||
[...new Set(processGroupIds)].map((processGroupId) =>
|
||||
@@ -651,6 +655,7 @@ export const awaitTerminalExit = async ({
|
||||
interactions,
|
||||
dispatchedEventIndexes,
|
||||
recordEvent,
|
||||
onLiveProgress,
|
||||
}: TerminalExitOptions): Promise<{
|
||||
exitCode: number;
|
||||
signal?: number;
|
||||
@@ -661,6 +666,7 @@ export const awaitTerminalExit = async ({
|
||||
// Keep the initiating lifecycle reason so comparisons distinguish a target
|
||||
// exit from harness-owned timeout, idle-timeout, and cancellation cleanup.
|
||||
let reason: "exited" | "timeout" | "idle_timeout" | "cancelled" = "exited";
|
||||
onLiveProgress?.();
|
||||
terminal.onExit((exit) => {
|
||||
recordEvent("lifecycle", 0);
|
||||
for (const [eventIndex, event] of scenario.events.entries()) {
|
||||
@@ -688,6 +694,7 @@ export const awaitTerminalExit = async ({
|
||||
resolveExit({ ...exit, reason });
|
||||
});
|
||||
const timeout = scheduleProcessInterval(() => {
|
||||
onLiveProgress?.();
|
||||
if (signal?.aborted === true) {
|
||||
reason = "cancelled";
|
||||
terminal.kill("SIGKILL");
|
||||
|
||||
@@ -0,0 +1,113 @@
|
||||
import { expect, it } from "vitest";
|
||||
|
||||
import {
|
||||
createProcessCaptureProgressTracker,
|
||||
type ProcessCaptureProgress,
|
||||
} from "./ProcessCaptureProgress.js";
|
||||
|
||||
const blockedProgress = () => {
|
||||
let release: () => void = () => undefined;
|
||||
const blocked = new Promise<void>((resolve) => {
|
||||
release = resolve;
|
||||
});
|
||||
const delivered: Parameters<ProcessCaptureProgress["report"]>[0][] = [];
|
||||
const progress: ProcessCaptureProgress = {
|
||||
async report(update) {
|
||||
delivered.push(update);
|
||||
if (delivered.length === 1) await blocked;
|
||||
},
|
||||
};
|
||||
return { progress, delivered, release: () => release() };
|
||||
};
|
||||
|
||||
it("coalesces intermediate observations while the progress receiver is blocked", async () => {
|
||||
const receiver = blockedProgress();
|
||||
const tracker = createProcessCaptureProgressTracker(receiver.progress);
|
||||
void tracker.report({
|
||||
phase: "running",
|
||||
counts: { frames: 1, samples: 0, interactions: 0 },
|
||||
});
|
||||
await Promise.resolve();
|
||||
let latest: Promise<void> | undefined;
|
||||
for (let frames = 2; frames <= 1_000; frames += 1) {
|
||||
latest = tracker.report({
|
||||
phase: "running",
|
||||
counts: { frames, samples: 0, interactions: 0 },
|
||||
});
|
||||
}
|
||||
expect(receiver.delivered).toHaveLength(1);
|
||||
receiver.release();
|
||||
await latest;
|
||||
expect(receiver.delivered.map((update) => update.completed)).toEqual([
|
||||
1, 1_000,
|
||||
]);
|
||||
expect(receiver.delivered[1]?.message).toContain("frames=1000");
|
||||
});
|
||||
|
||||
it("discards stale live observations before delivering final cleanup", async () => {
|
||||
const receiver = blockedProgress();
|
||||
const tracker = createProcessCaptureProgressTracker(receiver.progress);
|
||||
void tracker.report({
|
||||
phase: "running",
|
||||
counts: { frames: 1, samples: 0, interactions: 0 },
|
||||
});
|
||||
await Promise.resolve();
|
||||
void tracker.report({
|
||||
phase: "running",
|
||||
counts: { frames: 2, samples: 0, interactions: 0 },
|
||||
});
|
||||
void tracker.report({
|
||||
phase: "settling",
|
||||
counts: { frames: 2, samples: 1, interactions: 0 },
|
||||
});
|
||||
tracker.closeLive();
|
||||
await tracker.report({
|
||||
phase: "running",
|
||||
counts: { frames: 10, samples: 10, interactions: 10 },
|
||||
});
|
||||
const terminal = tracker.report({
|
||||
phase: "cleanup",
|
||||
counts: { frames: 2, samples: 2, interactions: 0 },
|
||||
disposition: "exited",
|
||||
terminal: true,
|
||||
});
|
||||
receiver.release();
|
||||
await terminal;
|
||||
expect(receiver.delivered.map((update) => update.phase)).toEqual([
|
||||
"running",
|
||||
"cleanup",
|
||||
]);
|
||||
expect(receiver.delivered.at(-1)).toMatchObject({
|
||||
completed: 4,
|
||||
total: null,
|
||||
terminal: true,
|
||||
});
|
||||
});
|
||||
|
||||
it("still delivers terminal status after an observer rejects an update", async () => {
|
||||
const delivered: Parameters<ProcessCaptureProgress["report"]>[0][] = [];
|
||||
const tracker = createProcessCaptureProgressTracker({
|
||||
async report(update) {
|
||||
delivered.push(update);
|
||||
if (delivered.length === 1) throw new Error("Observer disconnected");
|
||||
},
|
||||
});
|
||||
await tracker.report({
|
||||
phase: "prepare",
|
||||
counts: { frames: 0, samples: 0, interactions: 0 },
|
||||
});
|
||||
tracker.closeLive();
|
||||
await expect(
|
||||
tracker.report({
|
||||
phase: "cleanup",
|
||||
counts: { frames: 1, samples: 1, interactions: 0 },
|
||||
disposition: "failed",
|
||||
terminal: true,
|
||||
}),
|
||||
).resolves.toBeUndefined();
|
||||
expect(delivered.at(-1)).toMatchObject({
|
||||
phase: "cleanup",
|
||||
completed: 2,
|
||||
terminal: true,
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,121 @@
|
||||
import type { ProcessCaptureCleanupReport } from "../../domain/process/processCapture.js";
|
||||
|
||||
/**
|
||||
* Progress port accepted by process capture.
|
||||
* Structurally matches the shared application `ProgressReporter`.
|
||||
*/
|
||||
export interface ProcessCaptureProgress {
|
||||
report(update: {
|
||||
readonly phase: string;
|
||||
readonly completed: number;
|
||||
readonly total: null;
|
||||
readonly message: string;
|
||||
readonly terminal?: boolean;
|
||||
}): Promise<void>;
|
||||
}
|
||||
|
||||
/** Observed collection counts. These are not a percentage of an unknown total. */
|
||||
export interface ProcessCaptureProgressCounts {
|
||||
readonly frames: number;
|
||||
readonly samples: number;
|
||||
readonly interactions: number;
|
||||
}
|
||||
|
||||
export type ProcessCaptureProgressPhase =
|
||||
| "prepare"
|
||||
| "running"
|
||||
| "settling"
|
||||
| "cleanup";
|
||||
|
||||
export type ProcessCaptureProgressDisposition =
|
||||
| "exited"
|
||||
| "timeout"
|
||||
| "idle_timeout"
|
||||
| "cancelled"
|
||||
| "failed";
|
||||
|
||||
export interface ProcessCaptureProgressReport {
|
||||
readonly phase: ProcessCaptureProgressPhase;
|
||||
readonly counts: ProcessCaptureProgressCounts;
|
||||
readonly terminal?: boolean;
|
||||
readonly disposition?: ProcessCaptureProgressDisposition;
|
||||
readonly cleanup?: ProcessCaptureCleanupReport;
|
||||
}
|
||||
|
||||
const formatProgressMessage = (
|
||||
elapsedMs: number,
|
||||
counts: ProcessCaptureProgressCounts,
|
||||
disposition: ProcessCaptureProgressDisposition | undefined,
|
||||
cleanup: ProcessCaptureCleanupReport | undefined,
|
||||
): string => {
|
||||
const status = `elapsed_ms=${String(elapsedMs)} frames=${String(counts.frames)} samples=${String(counts.samples)} interactions=${String(counts.interactions)}`;
|
||||
const dispositionText =
|
||||
disposition === undefined ? "" : ` disposition=${disposition}`;
|
||||
const cleanupText =
|
||||
cleanup === undefined
|
||||
? ""
|
||||
: ` owned_process_group=${cleanup.owned_process_group.state} terminal_renderer=${cleanup.terminal_renderer.state} temporary_root=${cleanup.temporary_root.state}`;
|
||||
return `${status}${dispositionText}${cleanupText}`;
|
||||
};
|
||||
|
||||
/** Serialize observed capture status through one rate-limited reporter. */
|
||||
export const createProcessCaptureProgressTracker = (
|
||||
progress: ProcessCaptureProgress | undefined,
|
||||
now: () => number = Date.now,
|
||||
) => {
|
||||
const started = now();
|
||||
let completed = 0;
|
||||
let live = true;
|
||||
let next: Parameters<ProcessCaptureProgress["report"]>[0] | undefined;
|
||||
let pending: Promise<void> | undefined;
|
||||
const flush = async (): Promise<void> => {
|
||||
try {
|
||||
while (next !== undefined) {
|
||||
const update = next;
|
||||
next = undefined;
|
||||
try {
|
||||
await progress?.report(update);
|
||||
} catch {
|
||||
// Progress delivery is observational; capture and cleanup still finish.
|
||||
continue;
|
||||
}
|
||||
}
|
||||
} finally {
|
||||
pending = undefined;
|
||||
}
|
||||
};
|
||||
return {
|
||||
closeLive(): void {
|
||||
live = false;
|
||||
if (next?.terminal !== true) next = undefined;
|
||||
},
|
||||
report(update: ProcessCaptureProgressReport): Promise<void> {
|
||||
if (progress === undefined) return Promise.resolve();
|
||||
if (update.terminal !== true && !live) return Promise.resolve();
|
||||
const units =
|
||||
update.counts.frames +
|
||||
update.counts.samples +
|
||||
update.counts.interactions;
|
||||
if (units > completed) completed = units;
|
||||
// A slow observer needs the latest observation, not a queue of old states.
|
||||
next = {
|
||||
phase: update.phase,
|
||||
completed,
|
||||
total: null as null,
|
||||
message: formatProgressMessage(
|
||||
Math.max(0, now() - started),
|
||||
update.counts,
|
||||
update.disposition,
|
||||
update.cleanup,
|
||||
),
|
||||
...(update.terminal === true ? { terminal: true as const } : {}),
|
||||
};
|
||||
pending ??= Promise.resolve().then(flush);
|
||||
return pending;
|
||||
},
|
||||
};
|
||||
};
|
||||
|
||||
export type ProcessCaptureProgressTracker = ReturnType<
|
||||
typeof createProcessCaptureProgressTracker
|
||||
>;
|
||||
@@ -55,6 +55,13 @@ import {
|
||||
import { makeProcessCaptureEnvironment } from "./ProcessCaptureEnvironment.js";
|
||||
import { classifyFilesystemEffects } from "./ProcessFilesystemEffects.js";
|
||||
import { processCaptureOwnershipUnavailableReason } from "./ProcessCaptureCapability.js";
|
||||
import {
|
||||
createProcessCaptureProgressTracker,
|
||||
type ProcessCaptureProgress,
|
||||
type ProcessCaptureProgressCounts,
|
||||
type ProcessCaptureProgressDisposition,
|
||||
type ProcessCaptureProgressTracker,
|
||||
} from "./ProcessCaptureProgress.js";
|
||||
import type { ProcessOwnershipBaseline } from "../ProcessOwnership.js";
|
||||
|
||||
interface StartedCaptureRuntime {
|
||||
@@ -262,7 +269,10 @@ const finishProcessRun = async (options: {
|
||||
readonly executionFailure: unknown;
|
||||
readonly observations?: ProcessCaptureObservationBuffer;
|
||||
readonly rootPid?: number;
|
||||
readonly progress: ProcessCaptureProgressTracker;
|
||||
readonly progressCounts: () => ProcessCaptureProgressCounts;
|
||||
}): Promise<ProcessCapture> => {
|
||||
options.progress.closeLive();
|
||||
await options.stopSampler();
|
||||
const sampledProcessGroupIds =
|
||||
options.runtime === undefined
|
||||
@@ -281,6 +291,20 @@ const finishProcessRun = async (options: {
|
||||
temporaryRoot: options.temporaryRoot,
|
||||
...(options.cleanupHost === undefined ? {} : { host: options.cleanupHost }),
|
||||
});
|
||||
const observedExit =
|
||||
options.observations?.exit.state === "available"
|
||||
? options.observations.exit.value.reason
|
||||
: options.capture?.exit.reason;
|
||||
await options.progress.report({
|
||||
phase: "cleanup",
|
||||
counts: options.progressCounts(),
|
||||
terminal: true,
|
||||
disposition: captureProgressDisposition(
|
||||
observedExit,
|
||||
options.executionFailure,
|
||||
),
|
||||
cleanup,
|
||||
});
|
||||
const cleanupFailure = cleanupReportFailure(cleanup);
|
||||
let { capture, executionFailure } = options;
|
||||
let verifiedCapture: ProcessCapture | undefined;
|
||||
@@ -336,6 +360,7 @@ const completeCapture = async (options: {
|
||||
readonly eventJournal: readonly ProcessCaptureEventJournalEntry[];
|
||||
readonly observationBuffer: ProcessCaptureObservationBuffer;
|
||||
readonly recordEvent: RecordProcessCaptureEvent;
|
||||
readonly onLiveProgress?: () => void;
|
||||
}): Promise<PendingProcessCapture> => {
|
||||
const unavailableReason = (stage: string, cause: unknown): string =>
|
||||
`${stage} failed: ${cause instanceof Error ? cause.message : "unknown failure"}`;
|
||||
@@ -351,6 +376,7 @@ const completeCapture = async (options: {
|
||||
options.recordEvent,
|
||||
options.hostPlatform,
|
||||
options.signal,
|
||||
options.onLiveProgress,
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
options.observationBuffer.settlement = {
|
||||
@@ -460,6 +486,25 @@ const completeCapture = async (options: {
|
||||
});
|
||||
};
|
||||
|
||||
const captureProgressDisposition = (
|
||||
exitReason: string | undefined,
|
||||
executionFailure: unknown,
|
||||
): ProcessCaptureProgressDisposition => {
|
||||
if (
|
||||
exitReason === "exited" ||
|
||||
exitReason === "timeout" ||
|
||||
exitReason === "idle_timeout" ||
|
||||
exitReason === "cancelled"
|
||||
)
|
||||
return exitReason;
|
||||
if (
|
||||
executionFailure instanceof ProcessCaptureError &&
|
||||
executionFailure.reason === "cancelled"
|
||||
)
|
||||
return "cancelled";
|
||||
return "failed";
|
||||
};
|
||||
|
||||
/** Execute one caller-selected scenario and return bounded observations. */
|
||||
const runProcessScenario = async (
|
||||
scenario: ProcessScenario,
|
||||
@@ -468,12 +513,44 @@ const runProcessScenario = async (
|
||||
hostPlatform: NodeJS.Platform = process.platform,
|
||||
captureSnapshot: typeof snapshotRoots = snapshotRoots,
|
||||
cleanupHost?: ProcessCaptureCleanupHost,
|
||||
progress?: ProcessCaptureProgress,
|
||||
): Promise<ProcessCapture> => {
|
||||
const { temporaryRoot, runId, ownershipBaseline, before } =
|
||||
await prepareProcessCapture(scenario, signal, captureSnapshot);
|
||||
const progressTracker = createProcessCaptureProgressTracker(progress);
|
||||
const frames: TerminalFrame[] = [];
|
||||
const samples: ProcessSample[] = [];
|
||||
const interactions: InteractionEvent[] = [];
|
||||
const progressCounts = (): ProcessCaptureProgressCounts => ({
|
||||
frames: frames.length,
|
||||
samples: samples.length,
|
||||
interactions: interactions.length,
|
||||
});
|
||||
const reportRunning = () => {
|
||||
void progressTracker.report({ phase: "running", counts: progressCounts() });
|
||||
};
|
||||
const reportSettling = () => {
|
||||
void progressTracker.report({
|
||||
phase: "settling",
|
||||
counts: progressCounts(),
|
||||
});
|
||||
};
|
||||
let prepared: Awaited<ReturnType<typeof prepareProcessCapture>>;
|
||||
try {
|
||||
await progressTracker.report({
|
||||
phase: "prepare",
|
||||
counts: progressCounts(),
|
||||
});
|
||||
prepared = await prepareProcessCapture(scenario, signal, captureSnapshot);
|
||||
} catch (cause: unknown) {
|
||||
progressTracker.closeLive();
|
||||
await progressTracker.report({
|
||||
phase: "cleanup",
|
||||
counts: progressCounts(),
|
||||
terminal: true,
|
||||
disposition: signal?.aborted === true ? "cancelled" : "failed",
|
||||
});
|
||||
throw cause;
|
||||
}
|
||||
const { temporaryRoot, runId, ownershipBaseline, before } = prepared;
|
||||
const journal = createProcessCaptureJournal();
|
||||
const { entries: eventJournal, recordEvent } = journal;
|
||||
recordEvent("filesystem_checkpoints", 0);
|
||||
@@ -523,6 +600,7 @@ const runProcessScenario = async (
|
||||
interactions,
|
||||
dispatchedEventIndexes,
|
||||
recordEvent,
|
||||
...(progress === undefined ? {} : { onLiveProgress: reportRunning }),
|
||||
});
|
||||
observations.exit = {
|
||||
state: "available",
|
||||
@@ -549,6 +627,7 @@ const runProcessScenario = async (
|
||||
recordEvent,
|
||||
captureSnapshot,
|
||||
...(signal === undefined ? {} : { signal }),
|
||||
...(progress === undefined ? {} : { onLiveProgress: reportSettling }),
|
||||
});
|
||||
} catch (cause: unknown) {
|
||||
executionFailure = normalizeCaptureFailure(cause, signal);
|
||||
@@ -590,6 +669,8 @@ const runProcessScenario = async (
|
||||
executionFailure,
|
||||
observations,
|
||||
...(actualRootPid === undefined ? {} : { rootPid: actualRootPid }),
|
||||
progress: progressTracker,
|
||||
progressCounts,
|
||||
});
|
||||
};
|
||||
|
||||
@@ -599,8 +680,9 @@ export const captureProcessScenario = async (
|
||||
signal?: AbortSignal,
|
||||
platform: NodeJS.Platform = process.platform,
|
||||
environment: Readonly<Record<string, string | undefined>> = process.env,
|
||||
captureSnapshot: typeof snapshotRoots = snapshotRoots,
|
||||
captureSnapshot?: typeof snapshotRoots,
|
||||
cleanupHost?: ProcessCaptureCleanupHost,
|
||||
progress?: ProcessCaptureProgress,
|
||||
): Promise<Result<ProcessCapture, ProcessCaptureError | AnalysisError>> => {
|
||||
const ownershipReason = processCaptureOwnershipUnavailableReason(platform);
|
||||
if (ownershipReason !== undefined)
|
||||
@@ -624,8 +706,9 @@ export const captureProcessScenario = async (
|
||||
signal,
|
||||
environment,
|
||||
platform,
|
||||
captureSnapshot,
|
||||
captureSnapshot ?? snapshotRoots,
|
||||
cleanupHost,
|
||||
progress,
|
||||
),
|
||||
);
|
||||
} catch (cause: unknown) {
|
||||
|
||||
@@ -90,24 +90,20 @@ const registerProcessTools = ({
|
||||
toolRegistrationOptions(captureContract),
|
||||
async (input, context) => {
|
||||
const progress = mcpProgressReporter(context);
|
||||
await progress.report({
|
||||
phase: captureContract.name,
|
||||
completed: 0,
|
||||
total: 1,
|
||||
message: "started",
|
||||
});
|
||||
const captured = await logToolExecution(
|
||||
logger,
|
||||
captureContract.name,
|
||||
() => captureProcessScenario(input, context.mcpReq.signal),
|
||||
() =>
|
||||
captureProcessScenario(
|
||||
input,
|
||||
context.mcpReq.signal,
|
||||
process.platform,
|
||||
process.env,
|
||||
undefined,
|
||||
undefined,
|
||||
progress,
|
||||
),
|
||||
);
|
||||
await progress.report({
|
||||
phase: captureContract.name,
|
||||
completed: 1,
|
||||
total: 1,
|
||||
message: captured.ok ? "completed" : "failed",
|
||||
terminal: true,
|
||||
});
|
||||
if (!captured.ok)
|
||||
return server.delivery.toCallToolResult(captured, captureContract);
|
||||
const evidence = createProcessCaptureEvidence(input, captured.value);
|
||||
|
||||
@@ -115,3 +115,39 @@ cliTest(
|
||||
({ cli }) => verifyJavaScriptReturnShapes(cli, source, assertReturns),
|
||||
120_000,
|
||||
);
|
||||
|
||||
cliTest(
|
||||
"analyzes wide receiver returns without losing escaped reference facts",
|
||||
({ cli }) => {
|
||||
const width = 160_000;
|
||||
const object = Array.from(
|
||||
{ length: width },
|
||||
(_, index) => `p${index}:0`,
|
||||
).join(",");
|
||||
const array = "0,".repeat(width);
|
||||
const wideSource = [
|
||||
["wideObject", `{${object},last:shared}`],
|
||||
["wideArray", `[${array}shared]`],
|
||||
]
|
||||
.map(
|
||||
([name, value]) =>
|
||||
`export function ${name}(){const shared={x:1};const box={wide(){return ${value}},noop(){}};box.noop();return {x:shared.x,keep:7};}`,
|
||||
)
|
||||
.join("\n");
|
||||
return verifyJavaScriptReturnShapes(cli, wideSource, (fields) => {
|
||||
for (const name of ["wideObject", "wideArray"]) {
|
||||
expect(fields(name)).toContainEqual(
|
||||
expect.objectContaining({ path: "/x", state: "unknown" }),
|
||||
);
|
||||
expect(fields(name)).toContainEqual(
|
||||
expect.objectContaining({
|
||||
path: "/keep",
|
||||
state: "literal",
|
||||
value: 7,
|
||||
}),
|
||||
);
|
||||
}
|
||||
});
|
||||
},
|
||||
120_000,
|
||||
);
|
||||
|
||||
@@ -22,9 +22,9 @@ cliTest(
|
||||
arguments: arguments_,
|
||||
cwd: home,
|
||||
environment: {
|
||||
HOME: home,
|
||||
USERPROFILE: home,
|
||||
HERMES_HOME: " ${HOME}/profile ",
|
||||
REA_CLIENT_PROFILE_HOME: home,
|
||||
HERMES_HOME: " ${REA_CLIENT_PROFILE_HOME}/profile ",
|
||||
},
|
||||
timeoutMs: 20_000,
|
||||
});
|
||||
@@ -96,3 +96,195 @@ cliTest(
|
||||
await expect(access(skill)).rejects.toMatchObject({ code: "ENOENT" });
|
||||
},
|
||||
);
|
||||
|
||||
for (const selection of ["default", "custom", "suffix", "explicit"] as const) {
|
||||
cliTest(
|
||||
`Hermes ${selection} sticky-profile selection preserves the root configuration`,
|
||||
async ({ cli }) => {
|
||||
const home = await createTestTempDirectory("rea-hermes-sticky-");
|
||||
const suffix = selection === "suffix" ? "-dev" : "";
|
||||
const native =
|
||||
process.platform === "win32"
|
||||
? join(home, "AppData", "Local", `hermes${suffix}`)
|
||||
: join(home, `.hermes${suffix}`);
|
||||
const root = selection === "custom" ? join(home, "custom root") : native;
|
||||
const profile = join(
|
||||
root,
|
||||
"profiles",
|
||||
selection === "explicit" ? "other" : "coder",
|
||||
);
|
||||
await mkdir(profile, { recursive: true });
|
||||
const original =
|
||||
"# profile settings\nmodel: custom\nmcp_servers:\n other:\n command: other-server\n";
|
||||
const config = join(profile, "config.yaml");
|
||||
const rootConfig = join(root, "config.yaml");
|
||||
await writeFile(config, original);
|
||||
await writeFile(rootConfig, "model: root-model\n");
|
||||
await writeFile(join(root, "active_profile"), "\uFEFFCoDeR\r\n");
|
||||
const run = (args: readonly string[]) =>
|
||||
cli.run({
|
||||
arguments: args,
|
||||
cwd: home,
|
||||
environment: {
|
||||
USERPROFILE: home,
|
||||
LOCALAPPDATA: join(home, "AppData", "Local"),
|
||||
HERMES_DATA_DIR_SUFFIX: suffix,
|
||||
HERMES_HOME:
|
||||
selection === "explicit"
|
||||
? profile
|
||||
: selection === "custom"
|
||||
? root
|
||||
: undefined,
|
||||
},
|
||||
timeoutMs: 20_000,
|
||||
});
|
||||
const plan = await run([
|
||||
"setup",
|
||||
"--client",
|
||||
"hermes",
|
||||
"--dry-run",
|
||||
"--json",
|
||||
]);
|
||||
expect(plan.exitCode).toBe(0);
|
||||
expect(plan.json).toMatchObject({
|
||||
status: "planned",
|
||||
plannedActions: expect.arrayContaining([
|
||||
expect.objectContaining({ target: config }),
|
||||
expect.objectContaining({
|
||||
target: join(profile, "skills", "reverse-engineer-anything"),
|
||||
}),
|
||||
]),
|
||||
});
|
||||
expect(
|
||||
(await run(["setup", "--client", "hermes", "--yes", "--json"]))
|
||||
.exitCode,
|
||||
).toBe(0);
|
||||
expect(parse(await readFile(config, "utf8"))).toMatchObject({
|
||||
mcp_servers: {
|
||||
rea: { enabled: true },
|
||||
other: { command: "other-server" },
|
||||
},
|
||||
});
|
||||
expect(await readFile(`${config}.rea.backup`, "utf8")).toBe(original);
|
||||
const skill = join(
|
||||
profile,
|
||||
"skills",
|
||||
"reverse-engineer-anything",
|
||||
"SKILL.md",
|
||||
);
|
||||
expect(await readFile(skill, "utf8")).toContain(
|
||||
"name: reverse-engineer-anything",
|
||||
);
|
||||
if (selection === "custom") {
|
||||
const doctor = await run([
|
||||
"doctor",
|
||||
"--client",
|
||||
"hermes",
|
||||
"--skill",
|
||||
"--json",
|
||||
]);
|
||||
expect(doctor.exitCode).toBe(0);
|
||||
expect(doctor.json).toMatchObject({
|
||||
healthy: true,
|
||||
identity: {
|
||||
skill: { state: "aligned" },
|
||||
registrations: expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
client: "hermes",
|
||||
config_path: config,
|
||||
state: "aligned",
|
||||
}),
|
||||
]),
|
||||
},
|
||||
});
|
||||
expect(
|
||||
(await run(["setup", "--client", "hermes", "--yes", "--json"])).json,
|
||||
).toMatchObject({ appliedActions: [] });
|
||||
expect((await run(["uninstall", "--json"])).exitCode).toBe(0);
|
||||
expect(parse(await readFile(config, "utf8"))).toEqual(parse(original));
|
||||
await expect(access(skill)).rejects.toMatchObject({ code: "ENOENT" });
|
||||
}
|
||||
expect(await readFile(rootConfig, "utf8")).toBe("model: root-model\n");
|
||||
await expect(access(`${rootConfig}.rea.backup`)).rejects.toMatchObject({
|
||||
code: "ENOENT",
|
||||
});
|
||||
await expect(
|
||||
access(join(root, "skills", "reverse-engineer-anything")),
|
||||
).rejects.toMatchObject({ code: "ENOENT" });
|
||||
},
|
||||
);
|
||||
}
|
||||
for (const name of ["missing", "deleted", "ghost", "../escape", "root"]) {
|
||||
cliTest(
|
||||
`Hermes rejects unusable sticky profile ${name} without writing a fallback home`,
|
||||
async ({ cli }) => {
|
||||
const home = await createTestTempDirectory("rea-hermes-invalid-profile-");
|
||||
const root = join(home, "hermes root");
|
||||
await mkdir(root);
|
||||
await writeFile(join(root, "active_profile"), name);
|
||||
if (name === "deleted" || name === "ghost") {
|
||||
await mkdir(join(root, "profiles", name), { recursive: true });
|
||||
if (name === "deleted") {
|
||||
await writeFile(
|
||||
join(root, "profiles", name, "config.yaml"),
|
||||
"model: custom\n",
|
||||
);
|
||||
await mkdir(join(root, "profiles", ".deleted"));
|
||||
await writeFile(
|
||||
join(root, "profiles", ".deleted", name),
|
||||
"deleted\n",
|
||||
);
|
||||
}
|
||||
}
|
||||
const run = (args: readonly string[]) =>
|
||||
cli.run({
|
||||
arguments: args,
|
||||
cwd: home,
|
||||
environment: { USERPROFILE: home, HERMES_HOME: root },
|
||||
timeoutMs: 20_000,
|
||||
});
|
||||
const rejected = await run([
|
||||
"setup",
|
||||
"--client",
|
||||
"hermes",
|
||||
"--yes",
|
||||
"--json",
|
||||
]);
|
||||
expect(rejected.exitCode).not.toBe(0);
|
||||
expect(rejected.json).toMatchObject({
|
||||
status: "needs_human",
|
||||
plannedActions: [],
|
||||
appliedActions: [],
|
||||
remediation: expect.stringContaining("Hermes profile"),
|
||||
});
|
||||
await expect(access(join(root, "config.yaml"))).rejects.toMatchObject({
|
||||
code: "ENOENT",
|
||||
});
|
||||
await expect(access(join(root, "skills"))).rejects.toMatchObject({
|
||||
code: "ENOENT",
|
||||
});
|
||||
if (name !== "missing") return;
|
||||
const doctor = await run(["doctor", "--client", "hermes", "--json"]);
|
||||
expect(doctor.exitCode).not.toBe(0);
|
||||
expect(doctor.json).toMatchObject({
|
||||
identity: {
|
||||
registrations: expect.arrayContaining([
|
||||
expect.objectContaining({
|
||||
client: "hermes",
|
||||
state: "invalid",
|
||||
remediation: expect.stringContaining("Hermes profile"),
|
||||
}),
|
||||
]),
|
||||
},
|
||||
});
|
||||
const unrelated = await run([
|
||||
"setup",
|
||||
"--client",
|
||||
"codex",
|
||||
"--yes",
|
||||
"--json",
|
||||
]);
|
||||
expect(unrelated.exitCode).toBe(0);
|
||||
},
|
||||
);
|
||||
}
|
||||
|
||||
@@ -32,157 +32,156 @@ afterEach(async () => {
|
||||
await Promise.all(browsers.splice(0).map(async (browser) => browser.close()));
|
||||
});
|
||||
|
||||
describe("browser CLI parity", () => {
|
||||
it(
|
||||
"returns the same Evidence discovery and inspection contracts",
|
||||
async () => {
|
||||
const browser = await startFakeCdpBrowser({
|
||||
sessionTimeline: "same_origin",
|
||||
webMcpTools: true,
|
||||
sensitiveShapes: true,
|
||||
commandEvents: partialScriptEvents,
|
||||
});
|
||||
browsers.push(browser);
|
||||
const listed = await runCli(
|
||||
["list-browser-targets", browser.endpoint, "--json"],
|
||||
process.env,
|
||||
);
|
||||
expect(listed).toMatchObject({
|
||||
operation: "list_browser_targets",
|
||||
provider: { id: "rea-cdp-browser" },
|
||||
normalized_result: {
|
||||
targets: expect.arrayContaining([
|
||||
expect.objectContaining({ target_id: "allowed-page" }),
|
||||
expect.objectContaining({ target_id: "disallowed-page" }),
|
||||
]),
|
||||
it(
|
||||
"browser CLI parity returns the same Evidence discovery and inspection contracts",
|
||||
async () => {
|
||||
const browser = await startFakeCdpBrowser({
|
||||
sessionTimeline: "same_origin",
|
||||
webMcpTools: true,
|
||||
sensitiveShapes: true,
|
||||
commandEvents: partialScriptEvents,
|
||||
eventsBeforeReply: ["Network.enable"],
|
||||
});
|
||||
browsers.push(browser);
|
||||
const listed = await runCli(
|
||||
["list-browser-targets", browser.endpoint, "--json"],
|
||||
process.env,
|
||||
);
|
||||
expect(listed).toMatchObject({
|
||||
operation: "list_browser_targets",
|
||||
provider: { id: "rea-cdp-browser" },
|
||||
normalized_result: {
|
||||
targets: expect.arrayContaining([
|
||||
expect.objectContaining({ target_id: "allowed-page" }),
|
||||
expect.objectContaining({ target_id: "disallowed-page" }),
|
||||
]),
|
||||
},
|
||||
});
|
||||
const inspected = await runCli(
|
||||
[
|
||||
"inspect-web-page",
|
||||
browser.endpoint,
|
||||
"allowed-page",
|
||||
"--observation-ms",
|
||||
"0",
|
||||
"--include-console-text",
|
||||
"--include-json-body-shapes",
|
||||
"--include-websocket-shapes",
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(inspected).toMatchObject({
|
||||
operation: "inspect_web_page",
|
||||
provider: { id: "rea-cdp-browser" },
|
||||
normalized_result: {
|
||||
target: { target_id: "allowed-page" },
|
||||
scripts: {
|
||||
items: [{ cdp_hash: null, length: null, is_module: null }],
|
||||
},
|
||||
});
|
||||
const inspected = await runCli(
|
||||
[
|
||||
"inspect-web-page",
|
||||
browser.endpoint,
|
||||
"allowed-page",
|
||||
"--observation-ms",
|
||||
"0",
|
||||
"--include-console-text",
|
||||
"--include-json-body-shapes",
|
||||
"--include-websocket-shapes",
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(inspected).toMatchObject({
|
||||
operation: "inspect_web_page",
|
||||
provider: { id: "rea-cdp-browser" },
|
||||
normalized_result: {
|
||||
target: { target_id: "allowed-page" },
|
||||
scripts: {
|
||||
items: [{ cdp_hash: null, length: null, is_module: null }],
|
||||
},
|
||||
network: {
|
||||
prior_activity_available: false,
|
||||
requests: [
|
||||
expect.objectContaining({
|
||||
body_shapes: expect.objectContaining({ status: "included" }),
|
||||
}),
|
||||
],
|
||||
},
|
||||
},
|
||||
});
|
||||
const inspection = normalizedResult(inspected);
|
||||
const compared = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify({ inspection }),
|
||||
JSON.stringify({ inspection }),
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(compared).toMatchObject({
|
||||
operation: "compare_web_captures",
|
||||
normalized_result: {
|
||||
overall_status: "unknown",
|
||||
dimensions: {
|
||||
network: { status: "unknown", total_changes: 0 },
|
||||
},
|
||||
},
|
||||
});
|
||||
const scenarioCapture = completeScenarioCapture();
|
||||
const scenarioCompared = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
'{"rules":[]}',
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(scenarioCompared).toMatchObject({
|
||||
operation: "compare_web_captures",
|
||||
normalized_result: {
|
||||
comparison_kind: "browser_scenario",
|
||||
overall_status: "unchanged",
|
||||
alignment: { status: "aligned", aligned_steps: 2 },
|
||||
},
|
||||
});
|
||||
const intentionalPolicy = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
JSON.stringify({
|
||||
rules: [
|
||||
{
|
||||
rule_id: "domain",
|
||||
artifacts: ["url"],
|
||||
match: "app.example.test",
|
||||
replacement: "normalized.test",
|
||||
},
|
||||
],
|
||||
}),
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(intentionalPolicy).toMatchObject({
|
||||
normalized_result: {
|
||||
normalization: { rules: [{ rule_id: "domain" }] },
|
||||
},
|
||||
});
|
||||
|
||||
const malformedPolicy = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
"{invalid-policy",
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(malformedPolicy).toMatchObject({
|
||||
error: "Browser observation failed",
|
||||
code: "invalid_request",
|
||||
details: {
|
||||
operation: "compare_web_captures",
|
||||
issues: [
|
||||
{
|
||||
path: ["normalization"],
|
||||
reason: "invalid_format",
|
||||
expected: "JSON",
|
||||
},
|
||||
network: {
|
||||
prior_activity_available: false,
|
||||
requests: [
|
||||
expect.objectContaining({
|
||||
body_shapes: expect.objectContaining({ status: "included" }),
|
||||
}),
|
||||
],
|
||||
},
|
||||
});
|
||||
},
|
||||
INTEGRATION_TEST_TIMEOUT_MS,
|
||||
);
|
||||
});
|
||||
},
|
||||
});
|
||||
const inspection = normalizedResult(inspected);
|
||||
const compared = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify({ inspection }),
|
||||
JSON.stringify({ inspection }),
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(compared).toMatchObject({
|
||||
operation: "compare_web_captures",
|
||||
normalized_result: {
|
||||
overall_status: "unknown",
|
||||
dimensions: {
|
||||
network: { status: "unknown", total_changes: 0 },
|
||||
},
|
||||
},
|
||||
});
|
||||
const scenarioCapture = completeScenarioCapture();
|
||||
const scenarioCompared = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
'{"rules":[]}',
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(scenarioCompared).toMatchObject({
|
||||
operation: "compare_web_captures",
|
||||
normalized_result: {
|
||||
comparison_kind: "browser_scenario",
|
||||
overall_status: "unchanged",
|
||||
alignment: { status: "aligned", aligned_steps: 2 },
|
||||
},
|
||||
});
|
||||
const intentionalPolicy = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
JSON.stringify({
|
||||
rules: [
|
||||
{
|
||||
rule_id: "domain",
|
||||
artifacts: ["url"],
|
||||
match: "app.example.test",
|
||||
replacement: "normalized.test",
|
||||
},
|
||||
],
|
||||
}),
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(intentionalPolicy).toMatchObject({
|
||||
normalized_result: {
|
||||
normalization: { rules: [{ rule_id: "domain" }] },
|
||||
},
|
||||
});
|
||||
|
||||
const malformedPolicy = await runCli(
|
||||
[
|
||||
"compare-web-captures",
|
||||
JSON.stringify(scenarioCapture),
|
||||
JSON.stringify(scenarioCapture),
|
||||
"--normalization-json",
|
||||
"{invalid-policy",
|
||||
"--json",
|
||||
],
|
||||
process.env,
|
||||
);
|
||||
expect(malformedPolicy).toMatchObject({
|
||||
error: "Browser observation failed",
|
||||
code: "invalid_request",
|
||||
details: {
|
||||
operation: "compare_web_captures",
|
||||
issues: [
|
||||
{
|
||||
path: ["normalization"],
|
||||
reason: "invalid_format",
|
||||
expected: "JSON",
|
||||
},
|
||||
],
|
||||
},
|
||||
});
|
||||
},
|
||||
INTEGRATION_TEST_TIMEOUT_MS,
|
||||
);
|
||||
|
||||
describe("browser CLI capture parity", () => {
|
||||
it(
|
||||
|
||||
@@ -1,5 +1,5 @@
|
||||
import { createHash } from "node:crypto";
|
||||
import { mkdir, writeFile } from "node:fs/promises";
|
||||
import { chmod, mkdir, readdir, truncate, writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { build } from "plist";
|
||||
@@ -67,6 +67,82 @@ it.each([
|
||||
},
|
||||
);
|
||||
|
||||
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
|
||||
"rejects a selected unreadable directory before descending into it",
|
||||
async () => {
|
||||
const root = await bundle();
|
||||
const selected = join(root, "Contents", "Resources");
|
||||
await chmod(selected, 0);
|
||||
try {
|
||||
await expect(readdir(selected)).rejects.toMatchObject({ code: "EACCES" });
|
||||
await expect(
|
||||
inspect(root, { path: "Contents/Resources" }),
|
||||
).rejects.toMatchObject({
|
||||
issues: [
|
||||
{
|
||||
path: ["path"],
|
||||
reason: "invalid_value",
|
||||
message: expect.stringContaining("selects a directory"),
|
||||
},
|
||||
],
|
||||
});
|
||||
} finally {
|
||||
await chmod(selected, 0o700);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
|
||||
"inspects an active standalone archive without opening unrelated directories",
|
||||
async () => {
|
||||
const root = await createTestTempDirectory("rea-keyed-standalone-scope-");
|
||||
const path = join(root, "Model.plist");
|
||||
const bytes = Buffer.from(archive);
|
||||
const sha256 = createHash("sha256").update(bytes).digest("hex");
|
||||
await writeFile(path, bytes);
|
||||
const blocked = join(root, "unrelated");
|
||||
await mkdir(blocked);
|
||||
await chmod(blocked, 0);
|
||||
try {
|
||||
await expect(readdir(blocked)).rejects.toMatchObject({ code: "EACCES" });
|
||||
const result = await new ArtifactProvider(process.env, "darwin")
|
||||
.createClient({ path, sha256, kind: "artifact", format: "plist" })
|
||||
.execute("inspect_keyed_archive", {});
|
||||
if (!result.ok) throw result.error;
|
||||
expect(result.value.result).toMatchObject({
|
||||
archive_path: "Model.plist",
|
||||
archive_sha256: sha256,
|
||||
});
|
||||
} finally {
|
||||
await chmod(blocked, 0o700);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it.skipIf(process.platform === "win32" || process.getuid?.() === 0)(
|
||||
"reports the selected oversized archive limit despite an unreadable sibling",
|
||||
async () => {
|
||||
const root = await createTestTempDirectory("rea-keyed-size-scope-");
|
||||
const path = join(root, "Large.plist");
|
||||
await writeFile(path, archive);
|
||||
await truncate(path, 64 * 1024 * 1024 + 1);
|
||||
const blocked = join(root, "unrelated");
|
||||
await mkdir(blocked);
|
||||
await chmod(blocked, 0);
|
||||
try {
|
||||
await expect(readdir(blocked)).rejects.toMatchObject({ code: "EACCES" });
|
||||
await expect(
|
||||
inspect(root, { path: "Large.plist" }),
|
||||
).rejects.toMatchObject({
|
||||
reason: "limit",
|
||||
message: "Keyed archive exceeds 64 MiB",
|
||||
});
|
||||
} finally {
|
||||
await chmod(blocked, 0o700);
|
||||
}
|
||||
},
|
||||
);
|
||||
|
||||
it("reports an absent named root with the archive's available roots", async () => {
|
||||
const root = await bundle();
|
||||
await expect(
|
||||
@@ -184,6 +260,38 @@ it("selects a decomposed bundle path by its normalized spelling and reports the
|
||||
);
|
||||
});
|
||||
|
||||
it("selects normalized intermediate directories while preserving their raw spelling", async () => {
|
||||
const root = await createTestTempDirectory("rea-keyed-unicode-ancestors-");
|
||||
const directory = "Cafe\u0301/Neste\u0301";
|
||||
const rawPath = `${directory}/Model.plist`;
|
||||
await mkdir(join(root, directory), { recursive: true });
|
||||
await writeFile(join(root, rawPath), archive);
|
||||
const result = await inspect(root, { path: rawPath.normalize("NFC") });
|
||||
expect(result.archive_path).toBe(rawPath);
|
||||
});
|
||||
|
||||
it.skipIf(process.platform === "darwin" || process.platform === "win32")(
|
||||
"rejects equivalent archive paths beneath distinct Unicode-equivalent directories",
|
||||
async () => {
|
||||
const root = await createTestTempDirectory("rea-keyed-unicode-branches-");
|
||||
for (const directory of ["Caf\u00e9", "Cafe\u0301"]) {
|
||||
await mkdir(join(root, directory));
|
||||
await writeFile(join(root, directory, "Model.plist"), archive);
|
||||
}
|
||||
await expect(
|
||||
inspect(root, { path: "Caf\u00e9/Model.plist" }),
|
||||
).rejects.toMatchObject({
|
||||
issues: [
|
||||
{
|
||||
path: ["path"],
|
||||
reason: "invalid_value",
|
||||
message: expect.stringContaining("Unicode-equivalent"),
|
||||
},
|
||||
],
|
||||
});
|
||||
},
|
||||
);
|
||||
|
||||
it("keeps an archive readable when a non-finite real is an explicit unknown", async () => {
|
||||
const root = await bundle();
|
||||
const bytes = Buffer.from(
|
||||
|
||||
@@ -0,0 +1,558 @@
|
||||
import { spawn } from "node:child_process";
|
||||
import { writeFile } from "node:fs/promises";
|
||||
import { join } from "node:path";
|
||||
|
||||
import { Client, InMemoryTransport } from "@modelcontextprotocol/client";
|
||||
import { expect, onTestFinished } from "vitest";
|
||||
import { z } from "zod";
|
||||
|
||||
import { analysisCliErrorEnvelopeSchema } from "../../../src/contracts/errorSchemas.js";
|
||||
import { toolContract } from "../../../src/contracts/toolContracts.js";
|
||||
import { parseEvidence } from "../../../src/domain/evidence.js";
|
||||
import { parseProcessCapture } from "../../../src/domain/process/processCaptureParsing.js";
|
||||
import { silentLogger } from "../../../src/logger.js";
|
||||
import { createServer } from "../../../src/server/createServer.js";
|
||||
import { createTestBinarySession } from "../../fixtures/binarySession.js";
|
||||
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
|
||||
import { itWithCaptureCapability } from "./processCaptureCapability.js";
|
||||
|
||||
const PROGRESS_INTERVAL_MS = 100;
|
||||
|
||||
const progressLineSchema = z.object({
|
||||
rea_progress: z.object({
|
||||
phase: z.string(),
|
||||
completed: z.number().nonnegative(),
|
||||
total: z.null(),
|
||||
message: z.string(),
|
||||
sequence: z.number().int().positive(),
|
||||
terminal: z.boolean().optional(),
|
||||
}),
|
||||
});
|
||||
|
||||
const progressMessageSchema = z.object({
|
||||
elapsed_ms: z.number().int().nonnegative(),
|
||||
frames: z.number().int().nonnegative(),
|
||||
samples: z.number().int().nonnegative(),
|
||||
interactions: z.number().int().nonnegative(),
|
||||
disposition: z
|
||||
.enum(["exited", "timeout", "idle_timeout", "cancelled", "failed"])
|
||||
.optional(),
|
||||
owned_process_group: z
|
||||
.enum(["cleaned", "failed", "unverified", "not_required"])
|
||||
.optional(),
|
||||
terminal_renderer: z
|
||||
.enum(["cleaned", "failed", "unverified", "not_required"])
|
||||
.optional(),
|
||||
temporary_root: z
|
||||
.enum(["cleaned", "failed", "unverified", "not_required"])
|
||||
.optional(),
|
||||
});
|
||||
|
||||
type ProgressLine = z.infer<typeof progressLineSchema>["rea_progress"];
|
||||
type ParsedProgress = ProgressLine & {
|
||||
readonly details: z.infer<typeof progressMessageSchema>;
|
||||
};
|
||||
|
||||
const parseProgressMessage = (message: string) => {
|
||||
const matched =
|
||||
/^elapsed_ms=(?<elapsed_ms>\d+) frames=(?<frames>\d+) samples=(?<samples>\d+) interactions=(?<interactions>\d+)(?: disposition=(?<disposition>exited|timeout|idle_timeout|cancelled|failed))?(?: owned_process_group=(?<owned_process_group>cleaned|failed|unverified|not_required) terminal_renderer=(?<terminal_renderer>cleaned|failed|unverified|not_required) temporary_root=(?<temporary_root>cleaned|failed|unverified|not_required))?$/u.exec(
|
||||
message,
|
||||
);
|
||||
if (matched?.groups === undefined)
|
||||
throw new Error(`Progress message is not capture status: ${message}`);
|
||||
return progressMessageSchema.parse({
|
||||
elapsed_ms: Number(matched.groups.elapsed_ms),
|
||||
frames: Number(matched.groups.frames),
|
||||
samples: Number(matched.groups.samples),
|
||||
interactions: Number(matched.groups.interactions),
|
||||
...(matched.groups.disposition === undefined
|
||||
? {}
|
||||
: { disposition: matched.groups.disposition }),
|
||||
...(matched.groups.owned_process_group === undefined
|
||||
? {}
|
||||
: {
|
||||
owned_process_group: matched.groups.owned_process_group,
|
||||
terminal_renderer: matched.groups.terminal_renderer,
|
||||
temporary_root: matched.groups.temporary_root,
|
||||
}),
|
||||
});
|
||||
};
|
||||
|
||||
interface CliCapture {
|
||||
readonly stdout: string;
|
||||
readonly stderr: string;
|
||||
readonly exitCode: number | null;
|
||||
readonly lines: readonly {
|
||||
readonly update: ParsedProgress;
|
||||
}[];
|
||||
}
|
||||
|
||||
const writeScenario = async (
|
||||
prefix: string,
|
||||
scenario: Readonly<Record<string, unknown>>,
|
||||
): Promise<string> => {
|
||||
const root = await createTestTempDirectory(prefix);
|
||||
const path = join(root, "scenario.json");
|
||||
await writeFile(path, JSON.stringify(scenario));
|
||||
return path;
|
||||
};
|
||||
|
||||
const runCaptureCli = async (
|
||||
scenarioPath: string,
|
||||
options: { readonly stopOnRunning?: boolean } = {},
|
||||
): Promise<CliCapture> => {
|
||||
const child = spawn(
|
||||
process.execPath,
|
||||
["scripts/rea.mjs", "capture-process", scenarioPath, "--json"],
|
||||
{ stdio: ["ignore", "pipe", "pipe"] },
|
||||
);
|
||||
let stdout = "";
|
||||
let stderr = "";
|
||||
let pending = "";
|
||||
const lines: string[] = [];
|
||||
let sawRunning: (() => void) | undefined;
|
||||
const running = options.stopOnRunning
|
||||
? new Promise<void>((resolve) => {
|
||||
sawRunning = resolve;
|
||||
})
|
||||
: undefined;
|
||||
child.stdout.on("data", (chunk: Buffer) => {
|
||||
stdout += chunk.toString();
|
||||
});
|
||||
child.stderr.on("data", (chunk: Buffer) => {
|
||||
pending += chunk.toString();
|
||||
const parts = pending.split("\n");
|
||||
pending = parts.pop() ?? "";
|
||||
for (const line of parts) {
|
||||
if (line.length === 0) continue;
|
||||
lines.push(line);
|
||||
if (line.includes('"phase":"running"')) sawRunning?.();
|
||||
}
|
||||
});
|
||||
const closed = new Promise<{ code: number | null }>((resolve, reject) => {
|
||||
child.once("error", reject);
|
||||
child.once("close", (code) => resolve({ code }));
|
||||
});
|
||||
if (running !== undefined) {
|
||||
let timer: ReturnType<typeof setTimeout> | undefined;
|
||||
const appeared = await Promise.race([
|
||||
running.then(() => true),
|
||||
new Promise<boolean>((resolve) => {
|
||||
timer = setTimeout(() => resolve(false), 8_000);
|
||||
}),
|
||||
]).finally(() => {
|
||||
clearTimeout(timer);
|
||||
});
|
||||
if (!appeared) {
|
||||
child.kill("SIGKILL");
|
||||
await closed;
|
||||
throw new Error(
|
||||
`capture produced no running progress on stderr:\n${lines.join("\n")}`,
|
||||
);
|
||||
}
|
||||
child.kill("SIGINT");
|
||||
}
|
||||
const result = await closed;
|
||||
if (pending.length > 0) lines.push(pending);
|
||||
stderr = lines.join("\n");
|
||||
return {
|
||||
stdout,
|
||||
stderr,
|
||||
exitCode: result.code,
|
||||
lines: lines.map((line) => {
|
||||
const update = progressLineSchema.parse(JSON.parse(line)).rea_progress;
|
||||
return {
|
||||
update: { ...update, details: parseProgressMessage(update.message) },
|
||||
};
|
||||
}),
|
||||
};
|
||||
};
|
||||
|
||||
const assertMonotonic = (updates: readonly ParsedProgress[]): void => {
|
||||
for (const [index, update] of updates.entries()) {
|
||||
expect(update.total).toBeNull();
|
||||
expect(update.message).not.toMatch(/%|\bpercent/iu);
|
||||
const previous = updates[index - 1];
|
||||
if (previous === undefined) continue;
|
||||
expect(update.completed).toBeGreaterThanOrEqual(previous.completed);
|
||||
expect(update.sequence).toBe(previous.sequence + 1);
|
||||
}
|
||||
};
|
||||
|
||||
const assertRateBound = (
|
||||
intermediateCount: number,
|
||||
elapsedMs: number,
|
||||
): void => {
|
||||
// Pipe/transport buffering can deliver correctly spaced sends together.
|
||||
// Exact send spacing belongs to the reporter's controlled-clock test.
|
||||
expect(intermediateCount).toBeGreaterThan(1);
|
||||
expect(intermediateCount).toBeLessThanOrEqual(
|
||||
Math.floor(elapsedMs / PROGRESS_INTERVAL_MS) + 1,
|
||||
);
|
||||
};
|
||||
|
||||
const childScript = (source: string) => ["-e", source];
|
||||
|
||||
const connectProgressClient = async (
|
||||
recordNotifications = false,
|
||||
): Promise<{
|
||||
readonly client: Client;
|
||||
readonly notifications: string[];
|
||||
}> => {
|
||||
const session = createTestBinarySession(() => {
|
||||
throw new Error("Process capture must not launch a binary provider");
|
||||
});
|
||||
const server = createServer(
|
||||
{ kind: "session", session },
|
||||
{ logger: silentLogger },
|
||||
);
|
||||
const client = new Client({
|
||||
name: "process-capture-progress",
|
||||
version: "1",
|
||||
});
|
||||
const notifications: string[] = [];
|
||||
if (recordNotifications) {
|
||||
client.setNotificationHandler("notifications/progress", (notification) => {
|
||||
notifications.push(JSON.stringify(notification));
|
||||
});
|
||||
}
|
||||
const [clientTransport, serverTransport] =
|
||||
InMemoryTransport.createLinkedPair();
|
||||
await server.connect(serverTransport);
|
||||
await client.connect(clientTransport);
|
||||
onTestFinished(async () => {
|
||||
await Promise.allSettled([client.close(), server.close(), session.close()]);
|
||||
});
|
||||
return { client, notifications };
|
||||
};
|
||||
|
||||
itWithCaptureCapability(
|
||||
"keeps capture Evidence on stdout and live status on stderr for a sparse child",
|
||||
async () => {
|
||||
const scenario = await writeScenario("rea-process-progress-sparse-", {
|
||||
executable: process.execPath,
|
||||
arguments: childScript(
|
||||
"process.stdout.write('SPARSE_CHILD_STARTED\\n'); setTimeout(() => process.stdout.write('SPARSE_CHILD_DONE\\n'), 1600);",
|
||||
),
|
||||
timeout_ms: 10_000,
|
||||
idle_timeout_ms: 10_000,
|
||||
});
|
||||
const capture = await runCaptureCli(scenario);
|
||||
expect(capture.exitCode, capture.stderr).toBe(0);
|
||||
expect(capture.stdout).not.toContain("rea_progress");
|
||||
const evidence = parseEvidence(JSON.parse(capture.stdout));
|
||||
const recorded = parseProcessCapture(evidence.normalized_result);
|
||||
expect(evidence).toMatchObject({
|
||||
operation: "capture_process_scenario",
|
||||
predicate_type: "rea.process-capture",
|
||||
});
|
||||
expect(recorded.frames.map(({ data }) => data).join("")).toContain(
|
||||
"SPARSE_CHILD_STARTED",
|
||||
);
|
||||
expect(capture.stderr).not.toContain("SPARSE_CHILD_STARTED");
|
||||
expect(capture.stderr).not.toContain("SPARSE_CHILD_DONE");
|
||||
const updates = capture.lines.map(({ update }) => update);
|
||||
assertMonotonic(updates);
|
||||
const running = updates.filter(({ phase }) => phase === "running");
|
||||
expect(running.length).toBeGreaterThanOrEqual(3);
|
||||
const elapsed = running.map(({ details }) => details.elapsed_ms);
|
||||
expect(Math.max(...elapsed) - Math.min(...elapsed)).toBeGreaterThanOrEqual(
|
||||
1_000,
|
||||
);
|
||||
expect(running.every(({ details }) => details.frames <= 2)).toBe(true);
|
||||
expect(updates.at(-1)).toMatchObject({
|
||||
phase: "cleanup",
|
||||
terminal: true,
|
||||
details: {
|
||||
disposition: "exited",
|
||||
owned_process_group: "cleaned",
|
||||
terminal_renderer: "cleaned",
|
||||
temporary_root: "cleaned",
|
||||
},
|
||||
});
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
|
||||
itWithCaptureCapability(
|
||||
"bounds stderr progress while a busy child emits many output chunks",
|
||||
async () => {
|
||||
const scenario = await writeScenario("rea-process-progress-busy-", {
|
||||
executable: process.execPath,
|
||||
arguments: childScript(
|
||||
"let count = 0; const timer = setInterval(() => { process.stdout.write('BUSY_CHILD_LINE\\n'); count += 1; if (count >= 50) clearInterval(timer); }, 12);",
|
||||
),
|
||||
timeout_ms: 10_000,
|
||||
idle_timeout_ms: 10_000,
|
||||
});
|
||||
const capture = await runCaptureCli(scenario);
|
||||
expect(capture.exitCode, capture.stderr).toBe(0);
|
||||
const evidence = parseEvidence(JSON.parse(capture.stdout));
|
||||
const recorded = parseProcessCapture(evidence.normalized_result);
|
||||
const occurrences =
|
||||
recorded.frames
|
||||
.map(({ data }) => data)
|
||||
.join("")
|
||||
.split("BUSY_CHILD_LINE").length - 1;
|
||||
expect(occurrences).toBeGreaterThanOrEqual(40);
|
||||
expect(capture.stderr).not.toContain("BUSY_CHILD_LINE");
|
||||
const updates = capture.lines.map(({ update }) => update);
|
||||
assertMonotonic(updates);
|
||||
expect(updates.length).toBeLessThan(occurrences / 2);
|
||||
const nonTerminal = capture.lines.filter(
|
||||
({ update }) => update.terminal !== true,
|
||||
);
|
||||
assertRateBound(
|
||||
nonTerminal.length,
|
||||
updates.at(-1)?.details.elapsed_ms ?? 0,
|
||||
);
|
||||
expect(
|
||||
Math.max(...updates.map(({ details }) => details.frames)),
|
||||
).toBeGreaterThanOrEqual(10);
|
||||
expect(updates.at(-1)?.details.owned_process_group).toBe("cleaned");
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
|
||||
itWithCaptureCapability(
|
||||
"reports timeout cleanup on stderr without changing Evidence shape",
|
||||
async () => {
|
||||
const scenario = await writeScenario("rea-process-progress-timeout-", {
|
||||
executable: process.execPath,
|
||||
arguments: childScript("setInterval(() => undefined, 1000);"),
|
||||
timeout_ms: 700,
|
||||
idle_timeout_ms: 10_000,
|
||||
});
|
||||
const capture = await runCaptureCli(scenario);
|
||||
expect(capture.exitCode, capture.stderr).toBe(0);
|
||||
const evidence = parseEvidence(JSON.parse(capture.stdout));
|
||||
const recorded = parseProcessCapture(evidence.normalized_result);
|
||||
expect(recorded.exit.reason).toBe("timeout");
|
||||
expect(capture.stdout).not.toContain("rea_progress");
|
||||
const updates = capture.lines.map(({ update }) => update);
|
||||
assertMonotonic(updates);
|
||||
expect(updates.at(-1)).toMatchObject({
|
||||
phase: "cleanup",
|
||||
terminal: true,
|
||||
details: {
|
||||
disposition: "timeout",
|
||||
owned_process_group: "cleaned",
|
||||
},
|
||||
});
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
|
||||
itWithCaptureCapability(
|
||||
"reports cleanup status on stderr when capture is cancelled",
|
||||
async () => {
|
||||
const scenario = await writeScenario("rea-process-progress-cancel-", {
|
||||
executable: process.execPath,
|
||||
arguments: childScript("setInterval(() => undefined, 1000);"),
|
||||
timeout_ms: 15_000,
|
||||
idle_timeout_ms: 15_000,
|
||||
});
|
||||
const capture = await runCaptureCli(scenario, { stopOnRunning: true });
|
||||
expect(capture.exitCode).toBe(130);
|
||||
expect(
|
||||
analysisCliErrorEnvelopeSchema.parse(JSON.parse(capture.stdout)),
|
||||
).toMatchObject({
|
||||
code: "cancelled",
|
||||
details: { operation: "process_capture", cleanup: "complete" },
|
||||
});
|
||||
expect(capture.stdout).not.toContain("rea_progress");
|
||||
const updates = capture.lines.map(({ update }) => update);
|
||||
assertMonotonic(updates);
|
||||
expect(updates.at(-1)).toMatchObject({
|
||||
phase: "cleanup",
|
||||
terminal: true,
|
||||
details: {
|
||||
disposition: "cancelled",
|
||||
owned_process_group: "cleaned",
|
||||
},
|
||||
});
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
|
||||
itWithCaptureCapability(
|
||||
"forwards live capture progress only when the MCP client supplies a token",
|
||||
async () => {
|
||||
const silentClient = await connectProgressClient(true);
|
||||
const { client: tokenClient } = await connectProgressClient();
|
||||
const { notifications } = silentClient;
|
||||
const silent = await silentClient.client.callTool({
|
||||
name: "capture_process_scenario",
|
||||
arguments: {
|
||||
executable: process.execPath,
|
||||
arguments: childScript("process.stdout.write('SILENT_CHILD_OK\\n');"),
|
||||
timeout_ms: 10_000,
|
||||
idle_timeout_ms: 10_000,
|
||||
},
|
||||
});
|
||||
expect(silent.isError, JSON.stringify(silent)).not.toBe(true);
|
||||
expect(notifications).toEqual([]);
|
||||
const evidence = toolContract(
|
||||
"capture_process_scenario",
|
||||
).outputSchema.parse(silent.structuredContent);
|
||||
expect(
|
||||
evidence.normalized_result.frames.map((frame) => frame.data).join(""),
|
||||
).toContain("SILENT_CHILD_OK");
|
||||
|
||||
const progress: Array<{
|
||||
readonly progress: number;
|
||||
readonly total: number | undefined;
|
||||
readonly message: string | undefined;
|
||||
}> = [];
|
||||
const captured = await tokenClient.callTool(
|
||||
{
|
||||
name: "capture_process_scenario",
|
||||
arguments: {
|
||||
executable: process.execPath,
|
||||
arguments: childScript(
|
||||
"process.stdout.write('TOKEN_CHILD_STARTED\\n'); setTimeout(() => process.stdout.write('TOKEN_CHILD_DONE\\n'), 1200);",
|
||||
),
|
||||
timeout_ms: 10_000,
|
||||
idle_timeout_ms: 10_000,
|
||||
},
|
||||
},
|
||||
{
|
||||
onprogress: (update) => {
|
||||
progress.push({
|
||||
progress: update.progress,
|
||||
total: update.total,
|
||||
message: update.message,
|
||||
});
|
||||
},
|
||||
},
|
||||
);
|
||||
expect(captured.isError, JSON.stringify(captured)).not.toBe(true);
|
||||
expect(progress.length).toBeGreaterThanOrEqual(3);
|
||||
expect(progress.every(({ total }) => total === undefined)).toBe(true);
|
||||
for (const [index, update] of progress.entries()) {
|
||||
const previous = progress[index - 1];
|
||||
if (previous !== undefined)
|
||||
expect(update.progress).toBeGreaterThanOrEqual(previous.progress);
|
||||
expect(update.message ?? "").not.toContain("TOKEN_CHILD_STARTED");
|
||||
expect(update.message ?? "").not.toContain("TOKEN_CHILD_DONE");
|
||||
}
|
||||
const messages = progress.map(({ message }) => message ?? "");
|
||||
expect(messages.some((message) => message.startsWith("running:"))).toBe(
|
||||
true,
|
||||
);
|
||||
expect(messages.at(-1)).toContain("cleanup:");
|
||||
expect(messages.at(-1)).toContain("owned_process_group=cleaned");
|
||||
expect(messages.at(-1)).toContain("disposition=exited");
|
||||
const nonTerminal = progress.slice(0, -1);
|
||||
assertRateBound(
|
||||
nonTerminal.length,
|
||||
parseProgressMessage((messages.at(-1) ?? "").slice("cleanup: ".length))
|
||||
.elapsed_ms,
|
||||
);
|
||||
const tokenEvidence = toolContract(
|
||||
"capture_process_scenario",
|
||||
).outputSchema.parse(captured.structuredContent);
|
||||
expect(
|
||||
tokenEvidence.normalized_result.frames
|
||||
.map((frame) => frame.data)
|
||||
.join(""),
|
||||
).toContain("TOKEN_CHILD_STARTED");
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
|
||||
itWithCaptureCapability(
|
||||
"reports timeout and cancellation cleanup through MCP progress",
|
||||
async () => {
|
||||
const { client } = await connectProgressClient();
|
||||
const timeoutProgress: Array<{
|
||||
readonly message: string | undefined;
|
||||
readonly total: number | undefined;
|
||||
}> = [];
|
||||
const timedOut = await client.callTool(
|
||||
{
|
||||
name: "capture_process_scenario",
|
||||
arguments: {
|
||||
executable: process.execPath,
|
||||
arguments: childScript("setInterval(() => undefined, 1000);"),
|
||||
timeout_ms: 600,
|
||||
idle_timeout_ms: 10_000,
|
||||
},
|
||||
},
|
||||
{
|
||||
onprogress: (update) => {
|
||||
timeoutProgress.push({
|
||||
message: update.message,
|
||||
total: update.total,
|
||||
});
|
||||
},
|
||||
},
|
||||
);
|
||||
expect(timedOut.isError, JSON.stringify(timedOut)).not.toBe(true);
|
||||
const timedOutEvidence = toolContract(
|
||||
"capture_process_scenario",
|
||||
).outputSchema.parse(timedOut.structuredContent);
|
||||
expect(timedOutEvidence.normalized_result.exit.reason).toBe("timeout");
|
||||
expect(timeoutProgress.every(({ total }) => total === undefined)).toBe(
|
||||
true,
|
||||
);
|
||||
expect(timeoutProgress.at(-1)?.message).toContain("disposition=timeout");
|
||||
expect(timeoutProgress.at(-1)?.message).toContain(
|
||||
"owned_process_group=cleaned",
|
||||
);
|
||||
|
||||
const cancelling = await connectProgressClient(true);
|
||||
// Prepare the SDK's full output-schema cache before timing capture control.
|
||||
await cancelling.client.callTool({ name: "binary_session", arguments: {} });
|
||||
const controller = new AbortController();
|
||||
const stall = setTimeout(() => controller.abort(), 5_000);
|
||||
onTestFinished(() => clearTimeout(stall));
|
||||
const call = cancelling.client.callTool(
|
||||
{
|
||||
name: "capture_process_scenario",
|
||||
arguments: {
|
||||
executable: process.execPath,
|
||||
arguments: childScript("setInterval(() => undefined, 1000);"),
|
||||
timeout_ms: 15_000,
|
||||
idle_timeout_ms: 15_000,
|
||||
},
|
||||
_meta: { progressToken: "capture-cancel" },
|
||||
},
|
||||
{ signal: controller.signal },
|
||||
);
|
||||
const completion = call.then(
|
||||
(reply) => ({ kind: "reply" as const, reply }),
|
||||
(cause: unknown) => ({ kind: "error" as const, cause }),
|
||||
);
|
||||
try {
|
||||
await expect
|
||||
.poll(
|
||||
() =>
|
||||
cancelling.notifications.some((note) => note.includes("running:")),
|
||||
{ timeout: 4_000 },
|
||||
)
|
||||
.toBe(true);
|
||||
controller.abort();
|
||||
const outcome = await completion;
|
||||
if (outcome.kind !== "error")
|
||||
throw new Error("Cancelled capture must reject its client wait");
|
||||
expect(outcome.cause).toMatchObject({
|
||||
message: expect.stringMatching(/abort/iu),
|
||||
});
|
||||
} finally {
|
||||
clearTimeout(stall);
|
||||
controller.abort();
|
||||
await completion;
|
||||
}
|
||||
await expect
|
||||
.poll(() => cancelling.notifications.join("\n"))
|
||||
.toContain("disposition=cancelled");
|
||||
expect(cancelling.notifications.join("\n")).toContain(
|
||||
"owned_process_group=cleaned",
|
||||
);
|
||||
expect(cancelling.notifications.join("\n")).not.toMatch(
|
||||
/setInterval|CHILD/u,
|
||||
);
|
||||
},
|
||||
30_000,
|
||||
);
|
||||
Vendored
+16
-10
@@ -196,22 +196,28 @@ const replyToCommand = (
|
||||
);
|
||||
return;
|
||||
}
|
||||
socket.send(
|
||||
JSON.stringify({
|
||||
id: command.id,
|
||||
result,
|
||||
}),
|
||||
);
|
||||
if (options.malformedEventOnMethod === command.method)
|
||||
socket.send("{not-json");
|
||||
if (options.malformedEventShapeOnMethod === command.method)
|
||||
socket.send(JSON.stringify({ method: 42 }));
|
||||
const reply = () => {
|
||||
socket.send(
|
||||
JSON.stringify({
|
||||
id: command.id,
|
||||
result,
|
||||
}),
|
||||
);
|
||||
if (options.malformedEventOnMethod === command.method)
|
||||
socket.send("{not-json");
|
||||
if (options.malformedEventShapeOnMethod === command.method)
|
||||
socket.send(JSON.stringify({ method: 42 }));
|
||||
};
|
||||
const eventsFirst =
|
||||
options.eventsBeforeReply?.includes(command.method) === true;
|
||||
if (!eventsFirst) reply();
|
||||
const customEvents = options.commandEvents?.(
|
||||
command,
|
||||
`http://127.0.0.1:${String(port)}`,
|
||||
);
|
||||
if (customEvents === undefined) emitEvents(socket, command, port, options);
|
||||
else for (const event of customEvents) socket.send(JSON.stringify(event));
|
||||
if (eventsFirst) reply();
|
||||
if (options.closeAfterMethod === command.method)
|
||||
setImmediate(() => socket.close());
|
||||
};
|
||||
|
||||
+2
@@ -28,6 +28,8 @@ export interface FakeCdpBrowser {
|
||||
}
|
||||
|
||||
export interface FakeOptions {
|
||||
/** Send these commands' producer events before acknowledging completion, as a wire barrier. */
|
||||
readonly eventsBeforeReply?: readonly string[];
|
||||
/** Return a native-shaped command rejection through the actual wire parser. */
|
||||
readonly commandError?: (
|
||||
command: FakeCdpCommand,
|
||||
|
||||
+13
-3
@@ -12,6 +12,12 @@ for asset notes and the source of case-study claims.
|
||||
should explain a new fact or action.
|
||||
- Reuse the shared styles, prompts, figures and code-step components. Keep a
|
||||
case study focused on one question, with further examples in native details.
|
||||
- Edit shared header, footer and sharing markup in `templates/`; run
|
||||
`python3 scripts/website.py sync` and commit the rendered regions with their
|
||||
templates. Keep page bodies outside the marked regions. Author each title and
|
||||
description once; derive sharing fields and canonicals from them. Use
|
||||
`new-page` for a reading-page scaffold, then add its index link. Keep a draft's
|
||||
visible label and `noindex` until the content is ready.
|
||||
- Show what REA returns and how the agent uses it. Preserve source attribution,
|
||||
target identity and verification scope.
|
||||
- Blog articles teach methods, decisions and workflows through concrete cases.
|
||||
@@ -27,9 +33,13 @@ for asset notes and the source of case-study claims.
|
||||
from HTML automatically. Mark example applications `noindex` in the head and
|
||||
keep them crawlable. Maintain the SVG sharing source, not the generated PNG.
|
||||
- Check both local root and `/rea/` paths, mobile layouts, expanded details,
|
||||
copying and downloads. Run `scripts/prepare-website.py` followed by
|
||||
`scripts/verify-website.py` and `scripts/test-website.py`, using the website
|
||||
Python environment described in the README.
|
||||
copying and downloads. Run `python3 scripts/website.py check`, using the Python
|
||||
environment described in the README. It rejects drift rather than silently
|
||||
rewriting shared HTML. Use `website.py links` for an optional network audit;
|
||||
distinguish missing targets from access denials and unverified fragments.
|
||||
- Check setup and support statements against the current installation/provider
|
||||
guides and released package. Preserve historical case-study checkpoints and
|
||||
versions unless a new investigation supplies replacement evidence.
|
||||
- Keep `website-pages.yml` as the sole, manual production publisher for
|
||||
Cloudflare and Pages. Default to `both`: both hosts receive the same verified
|
||||
artifact and pass the published-commit check. Use `pages` only when explicitly
|
||||
|
||||
+91
-17
@@ -7,8 +7,9 @@
|
||||
An English static website with explanatory figures, worked guides and Aegis, DX-Ball, Notion, TH04 and CTF investigations.
|
||||
The public files are in `website/public/`. The site uses HTML, CSS and small
|
||||
scripts for copying code, following code comparisons and playing the dinosaur
|
||||
speed reconstruction. Python prepares the example ZIP, sitemap and sharing
|
||||
image; there is no frontend bundler or npm dependency.
|
||||
speed reconstruction. Small Python commands maintain shared HTML, prepare
|
||||
downloads and check the site. There is no frontend framework, bundler or npm
|
||||
dependency. The checked-in HTML works as ordinary static files.
|
||||
|
||||
[style-guide.md](style-guide.md) explains the writing, page structure, figures,
|
||||
visual system and review process. Read it before adding or revising a page.
|
||||
@@ -21,8 +22,7 @@ From the repository root:
|
||||
python3 -m venv website/.venv
|
||||
source website/.venv/bin/activate
|
||||
python3 -m pip install -r website/requirements.txt
|
||||
python3 scripts/prepare-website.py
|
||||
python3 -m http.server 4173 --bind 127.0.0.1 --directory website/public
|
||||
python3 scripts/website.py serve
|
||||
```
|
||||
|
||||
Open <http://127.0.0.1:4173/>. Refresh the browser after editing a file.
|
||||
@@ -32,9 +32,81 @@ install them with `sudo apt-get install libcairo2 fonts-dejavu-core`. For other
|
||||
systems, see [CairoSVG's installation instructions](https://cairosvg.org/documentation/#installation).
|
||||
CI installs both packages explicitly before rendering the card.
|
||||
|
||||
After adding, moving or removing a page, or changing its indexing policy, rerun
|
||||
`python3 scripts/prepare-website.py`. It regenerates the sitemap from the current
|
||||
HTML files. No URL list needs to be maintained.
|
||||
To test the GitHub Pages prefix, use
|
||||
`python3 scripts/website.py serve --port 4174 --base-path /rea/` and open
|
||||
<http://127.0.0.1:4174/rea/>.
|
||||
|
||||
## Contribute a page or correction
|
||||
|
||||
Edit the page's HTML in `public/`. Keep the question, evidence and result easy to
|
||||
follow. The writing and design guidance in [style-guide.md](style-guide.md)
|
||||
applies to every page.
|
||||
|
||||
| Change | Edit | Then run |
|
||||
| ------------------------------ | ---------------------------------------------------------------- | ----------------------------------------------- |
|
||||
| Page text, examples or figures | The page's HTML outside the marked shared regions | `python3 scripts/website.py check` |
|
||||
| Search title or description | The page's `<title>` and first description meta tag | `python3 scripts/website.py sync`, then `check` |
|
||||
| Main navigation | `NAVIGATION` in `scripts/website.py` | `sync`, then `check` |
|
||||
| Header, social links or footer | `templates/header.html.tmpl` or `templates/footer.html.tmpl` | `sync`, then `check` |
|
||||
| Shared link previews | `templates/sharing.html.tmpl` or `public/assets/social-card.svg` | `sync`, then `check` |
|
||||
|
||||
Create a reading page with:
|
||||
|
||||
```sh
|
||||
python3 scripts/website.py new-page blog/my-article \
|
||||
--title "My article title" \
|
||||
--description "One sentence explaining the article."
|
||||
```
|
||||
|
||||
The command creates `public/blog/my-article/index.html` with the correct relative
|
||||
paths, navigation and sharing metadata. It starts as a visible draft with
|
||||
`noindex`. Write the article, add its link to the Blog index, then remove the
|
||||
Draft label and robots meta tag when it is ready. The same command accepts
|
||||
routes under `guides/` and `showcase/`. New pages still need their own content;
|
||||
the scaffold supplies the common structure.
|
||||
|
||||
The regions marked `website:sharing`, `website:header` and `website:footer` are
|
||||
generated from the templates. Edit the template rather than a generated copy.
|
||||
The `.html.tmpl` partials own their generated whitespace; HTML formatter-ignore
|
||||
comments keep the repository formatter from changing those regions. Their
|
||||
content is checked by `sync --check`, while ordinary page content stays subject
|
||||
to the repository formatter.
|
||||
`sync` updates only those regions; page bodies, figures and scripts remain
|
||||
authored HTML. Commit the updated pages alongside the template. Titles and
|
||||
descriptions are written once per page; their sharing fields are derived from
|
||||
them. Routes come from file paths, including the sitemap, so there is no second
|
||||
page list to register.
|
||||
|
||||
Before opening a PR:
|
||||
|
||||
```sh
|
||||
python3 scripts/website.py check
|
||||
```
|
||||
|
||||
This checks shared HTML without rewriting it, prepares generated assets, and
|
||||
checks page links, copied-text targets, repository documentation links, SEO
|
||||
metadata and the publishing configuration. It also runs the maintenance
|
||||
regressions. A stale shared region fails with the command needed to fix it.
|
||||
PR checks and the manual publisher run this same command. The checks work
|
||||
offline after the Python dependencies are installed.
|
||||
|
||||
For an optional external-link audit, with GitHub CLI available:
|
||||
|
||||
```sh
|
||||
python3 scripts/website.py links --report /tmp/rea-website-links.json
|
||||
```
|
||||
|
||||
GitHub source links are checked through `gh`, including pinned commits and
|
||||
branch names containing slashes. Other external links use HTTP. Missing targets
|
||||
fail the command; access denials, timeouts and GitHub UI routes are reported as
|
||||
unknown and need manual verification. External fragment IDs are not checked.
|
||||
This network audit runs separately so third-party uptime does not block every PR.
|
||||
Keep its report outside public assets.
|
||||
|
||||
Links are only part of a content review. When updating setup or support claims,
|
||||
compare them with [installation.md](../docs/installation.md), the relevant
|
||||
provider guide and the released package. A case study's pinned version and date
|
||||
describe its recorded investigation; update them only when repeating that work.
|
||||
|
||||
## Pages
|
||||
|
||||
@@ -43,7 +115,7 @@ HTML files. No URL list needs to be maintained.
|
||||
- `public/first-investigation/index.html`: a guided Notes export investigation, from setup to a checked CSV prediction.
|
||||
- `public/showcase/index.html`: the case-study index.
|
||||
- `public/blog/index.html`: articles about reconstruction methods, ports, mods and reverse engineering.
|
||||
- `public/blog/touhou-reconstruction/index.html`: a personal essay about agent-driven reconstruction, knowledge that compounds across TH08 and TH095, and the workflow's applicability to PC-98 TH04.
|
||||
- `public/blog/touhou-reconstruction/index.html`: a personal essay about agent autonomy, oracle quality, knowledge carried between TH08 and TH095, PC-98 TH04, and the path from exact reconstruction to readable source and modern ports.
|
||||
- `public/showcase/aegis/index.html`: Aegis's Android login-code calculation, with an adjustable clock and reference checks.
|
||||
- `public/showcase/dx-ball/index.html`: sound-pan investigation and project status.
|
||||
- `public/showcase/notion/index.html`: Notion's Electron clipboard bridge and rich clipboard format.
|
||||
@@ -67,11 +139,11 @@ navigation and asset references remain relative so both hosts and local previews
|
||||
keep working.
|
||||
|
||||
Maintain a descriptive `<title>` and a short meta description in each page's
|
||||
`<head>`. The title names the page's subject; visible headings keep the wording
|
||||
that best explains it to a reader. Open Graph and Twitter titles/descriptions
|
||||
match those fields. `og:url` matches the canonical, and sharing images use
|
||||
absolute rea.tools URLs. Search results and link previews should follow the same
|
||||
clear, concise writing standard as the page.
|
||||
`<head>`, then run `sync`. The title names the page's subject; visible headings
|
||||
keep the wording that best explains it to a reader. The script derives Open
|
||||
Graph and Twitter fields and the canonical from those inputs and the file's
|
||||
route. Search results and link previews should follow the same clear, concise
|
||||
writing standard as the page.
|
||||
|
||||
`scripts/prepare-website.py` scans `public/**/*.html` and generates
|
||||
`public/sitemap.xml` with absolute rea.tools URLs. An `index.html` maps to its
|
||||
@@ -101,8 +173,7 @@ canonicals, lost fixture exclusions, stale sitemap entries and missing previews.
|
||||
Run it after preparing assets:
|
||||
|
||||
```sh
|
||||
python3 scripts/verify-website.py
|
||||
python3 scripts/test-website.py
|
||||
python3 scripts/website.py check
|
||||
```
|
||||
|
||||
### After publishing an SEO change
|
||||
@@ -136,6 +207,10 @@ quoted README passage and milestone counting rules are in
|
||||
The completed text has normal search metadata and is included in the generated
|
||||
sitemap.
|
||||
|
||||
Its opening flywheel connects agent autonomy, reference-based oracles and
|
||||
repository memory. The essay develops those ideas through the project examples.
|
||||
Figure labels are selectable HTML; inline SVG supplies the feedback arrows.
|
||||
|
||||
Keep the copy direct and specific. Explain the task and the result before listing
|
||||
tool names. Setup commands and runtime requirements should match the released
|
||||
package. Keep the core learning path inside the site. Source, issue and evidence
|
||||
@@ -400,8 +475,7 @@ dependencies. The same asset preparation and verification run before each manual
|
||||
deployment. With the preview environment active, run them locally:
|
||||
|
||||
```sh
|
||||
python3 scripts/prepare-website.py
|
||||
python3 scripts/verify-website.py
|
||||
python3 scripts/website.py check
|
||||
```
|
||||
|
||||
`.github/workflows/pages.yml` is a separate, manual-only VitePress build. It
|
||||
|
||||
@@ -173,3 +173,115 @@ observations, also confirmed by the author in this revision request. It is
|
||||
not attributed to a new automated website test or a fresh runtime replay.
|
||||
The 64-bit port is described as in development. The earlier four-product build
|
||||
and function-count milestones retain their historical scopes.
|
||||
|
||||
## Autonomy, oracles and the compounding flywheel
|
||||
|
||||
The author's requested revision emphasizes two principles: agents have broad
|
||||
autonomy to investigate, and their hypotheses are tested by oracles with concrete
|
||||
references and explicit acceptance conditions. These ideas are developed in the
|
||||
Factory's agent-autonomy and semantic-reconstruction documents listed above.
|
||||
An oracle result supports the property and inputs actually checked; the essay
|
||||
retains human responsibility for project milestones and release decisions.
|
||||
|
||||
The flywheel is an explanatory model of this relationship. Its passing branch
|
||||
retains a checked result and its evidence; a mismatch returns to investigation.
|
||||
Code, checks and recorded lessons improve the next starting point, with TH08,
|
||||
TH095 and TH04 illustrating knowledge carried between projects. It does not
|
||||
depict a measured performance ratio or give REA sole credit for reconstruction.
|
||||
|
||||
The first inline reference to GensokyoClub's public README links to the author's
|
||||
selected [Internet Archive capture](https://web.archive.org/web/20260909051514/https://github.com/GensokyoClub/th08#important-notice).
|
||||
The pinned source caption and 23-word excerpt retain their original provenance.
|
||||
The author approved this revision for publication on 10 October 2026.
|
||||
|
||||
## TH08's floating-literal oracle failure
|
||||
|
||||
The author recalled a floating-point comparison bug. The source history and
|
||||
public GitHub record identify it as a reference-data verification gap, rather
|
||||
than a rounding-tolerance problem. The original Japanese TH08 1.00d executable
|
||||
uses double `128.0` in the power arm of `ItemManager::OnUpdate`'s item-attraction
|
||||
condition. The reconstructed source used `0.0`.
|
||||
|
||||
- [Issue #10](https://github.com/N0zoM1z0/th08/issues/10), opened on 2 September
|
||||
2026, records the downstream Switch-port report, the target instructions and
|
||||
the constant bytes. Normal power is non-negative, so the erroneous power arm
|
||||
was effectively unconditional after crossing the collection line. Focus and
|
||||
shot-type exceptions were separate, correct arms of the condition.
|
||||
- [PR #11](https://github.com/N0zoM1z0/th08/pull/11), merged on 2 September,
|
||||
contains commit
|
||||
[`7148a76b`](https://github.com/N0zoM1z0/th08/commit/7148a76ba224742677895c7160807a68897957d5).
|
||||
It changes the threshold from `0.0` to `128.0`, fixes the manifest literal
|
||||
identity, and adds source-symbol/declared-data/target-data checks for
|
||||
explicitly recorded floating literals.
|
||||
- [PR #13](https://github.com/N0zoM1z0/th08/pull/13), merged the same day,
|
||||
contains commit
|
||||
[`a393f400`](https://github.com/N0zoM1z0/th08/commit/a393f400786e4cc6cbb1000af0dad3276da12c78).
|
||||
It audits 1,548 configured floating-literal references, corrects twelve more
|
||||
stale references across five accepted functions, and makes verification
|
||||
automatic for every 32-bit or 64-bit `__real@...` relocation. Its tests include
|
||||
deliberately invalid literal declarations and representations.
|
||||
|
||||
The older comparison replayed the target address into the instruction's
|
||||
relocation field, then compared instruction bytes without checking the
|
||||
floating-literal data at that address. Source `0.0` could therefore appear
|
||||
exact against target `128.0`. The essay explains this mechanism in ordinary
|
||||
language and keeps implementation details in the linked record. The count is
|
||||
of references, not distinct values or new functions.
|
||||
|
||||
The website work reexamined the historical diffs and retrieved the issue and
|
||||
PR metadata with `gh`; it did not rerun the game's historical compiler or
|
||||
runtime. The author supplies the first-person lesson about working as one
|
||||
human with agents and about responsibility for oracle quality.
|
||||
|
||||
## Readability and the learned phase order
|
||||
|
||||
The semantic discussion is based on the author's requested explanation,
|
||||
[TH08's semantic playbook](https://github.com/N0zoM1z0/th08/blob/d2a00f4acb4a13916e07a00bd13f714961714628/docs/SEMANTIC_PLAYBOOK.md),
|
||||
and the Factory's
|
||||
[semantic-reconstruction workflow](https://github.com/N0zoM1z0/touhou-reconstruction-factory/blob/717e1b8560783ed17a39fdf159d30aa16bb307a7/docs/semantic-reconstruction.md).
|
||||
The workflow's latest public change was checked using `gh` on 10 October.
|
||||
|
||||
The recommended order is an exact baseline, a working historical-platform
|
||||
product, semantic reconstruction with both validation paths, then portable
|
||||
products. The original target/compiler comparisons and the historical
|
||||
build/runtime checks answer different questions. Both are preserved during
|
||||
semantic work. Names, ownership and protocol interpretations also need
|
||||
producer/consumer evidence; a passing check does not establish their English
|
||||
meaning. Modern ports compare behavior with the established historical build
|
||||
without requiring the new architecture's machine code to match the old one.
|
||||
|
||||
This is a method learned from the projects. TH08's earlier portable releases
|
||||
preceded some later historical-platform audits. The essay states that history
|
||||
explicitly rather than presenting the current order as the original chronology.
|
||||
The game-RE background and the assembly/raw-offset aside are author-provided
|
||||
perspective. Transfer to other fields is a proposal to carry the principles
|
||||
while choosing references appropriate to the new domain.
|
||||
|
||||
## Industrial analogy: instruments develop with machines
|
||||
|
||||
The [Science Museum Group's steam-engine indicator record](https://collection.sciencemuseumgroup.org.uk/objects/co51439/watts-steam-engine-indicator),
|
||||
read on 10 October 2026, describes Boulton and Watt's introduction of the
|
||||
instrument in 1796 to assist with valve adjustment. It also explains how adding
|
||||
a pencil and moving paper made cylinder pressure through the stroke recordable.
|
||||
The essay paraphrases this description and links it directly. It does not use
|
||||
the record's images, quote its text, or date the displayed object or pressure
|
||||
diagram to 1796.
|
||||
|
||||
The connection to reconstruction tools is the author's analogy: rapid
|
||||
execution needs measurement, and the instruments themselves require improvement.
|
||||
The claim that this is an early industrial stage is the essay's interpretation
|
||||
of the project experience. The historical example supports the measurement
|
||||
comparison rather than a measured prediction about AI productivity.
|
||||
|
||||
## Prose revision
|
||||
|
||||
The later prose pass reduces repeated enumerations and develops each lesson
|
||||
through its project example. It preserves the milestone figures, quotation,
|
||||
source links and four-stage method. The two author-selected emphasized sentences
|
||||
retain their wording.
|
||||
|
||||
The opening takeaway now uses five bullets: agent autonomy, repository/Git
|
||||
memory, evidence and explicit unknowns, testing the oracle, and the early stage
|
||||
of the industrial shift. Each has a direct lead and a short explanation. The
|
||||
historical-build/semantic/port sequence remains in the body rather than becoming
|
||||
another takeaway item.
|
||||
|
||||
+19
-3
@@ -96,9 +96,25 @@ formula, default settings, slider outputs and reference cases consistent.
|
||||
|
||||
## Touhou reconstruction essay
|
||||
|
||||
The essay opens with a takeaway and develops its argument in prose. It has no
|
||||
opening flow figure. Project dates and the attributed README excerpt support
|
||||
the narrative; detailed milestone references are available in a native
|
||||
The essay opens with a takeaway and a flywheel explaining how experience
|
||||
compounds. The figure uses selectable HTML labels and inline SVG connectors:
|
||||
an autonomous agent proposes an experiment, an oracle tests it against a
|
||||
reference, and code, evidence, checks and lessons remain in the repository.
|
||||
A dashed mismatch branch returns to the agent for revision. The repository
|
||||
supplies a better starting point for the next investigation; TH08 → TH095 →
|
||||
TH04 illustrates knowledge carried between projects. Human direction names
|
||||
the goal and acceptance criteria above the cycle.
|
||||
|
||||
The caption connects reuse with improving the checks themselves. The TH08
|
||||
floating-literal case in the essay explains why a passing result can need
|
||||
reexamination when an oracle's blind spot is discovered. Preserve that link
|
||||
between the figure's ideal loop and the infrastructure lessons in the prose.
|
||||
|
||||
The shared stylesheet positions the labels and gives narrow screens separate
|
||||
connector geometry. Keep the arrows clear of the text and retain the same
|
||||
meaning at every width. This is an explanatory model, with no measured speed
|
||||
or productivity multiplier. Project dates and the attributed README excerpt
|
||||
support the narrative; detailed milestone references are available in a native
|
||||
disclosure. Their provenance is documented in
|
||||
[evidence/touhou-reconstruction-method.md](evidence/touhou-reconstruction-method.md).
|
||||
|
||||
|
||||
@@ -692,6 +692,178 @@ pre code {
|
||||
.blog-takeaway p:last-child {
|
||||
margin-bottom: 0;
|
||||
}
|
||||
.blog-takeaway ul {
|
||||
margin: 0;
|
||||
padding-left: 1.15rem;
|
||||
}
|
||||
.blog-takeaway li + li {
|
||||
margin-top: 0.75rem;
|
||||
}
|
||||
.reconstruction-flywheel {
|
||||
max-width: 880px;
|
||||
margin: 0 auto 4rem;
|
||||
padding-block: 1.5rem 1.75rem;
|
||||
border-block: 1px solid var(--line);
|
||||
}
|
||||
.flywheel-heading {
|
||||
text-align: center;
|
||||
}
|
||||
.flywheel-heading .eyebrow {
|
||||
margin-bottom: 0.6rem;
|
||||
color: var(--accent);
|
||||
}
|
||||
.flywheel-heading > p:last-child {
|
||||
color: var(--muted);
|
||||
font-size: 0.875rem;
|
||||
}
|
||||
.flywheel-diagram {
|
||||
position: relative;
|
||||
max-width: 760px;
|
||||
height: 440px;
|
||||
margin-inline: auto;
|
||||
}
|
||||
.flywheel-arrows {
|
||||
position: absolute;
|
||||
inset: 0;
|
||||
width: 100%;
|
||||
height: 100%;
|
||||
}
|
||||
.flywheel-path-mobile {
|
||||
display: none;
|
||||
}
|
||||
.flywheel-node {
|
||||
position: absolute;
|
||||
width: 30%;
|
||||
text-align: center;
|
||||
transform: translate(-50%, -50%);
|
||||
}
|
||||
.flywheel-node p {
|
||||
margin: 0.6rem 0 0;
|
||||
color: var(--muted);
|
||||
font-size: 0.875rem;
|
||||
line-height: 1.5;
|
||||
}
|
||||
.flywheel-node .flywheel-kicker {
|
||||
margin: 0 0 0.4rem;
|
||||
color: var(--accent);
|
||||
font-size: 0.6875rem;
|
||||
font-weight: 600;
|
||||
letter-spacing: 0.09em;
|
||||
text-transform: uppercase;
|
||||
}
|
||||
.flywheel-node h3 {
|
||||
margin: 0;
|
||||
font-size: 1.5rem;
|
||||
line-height: 1.2;
|
||||
}
|
||||
.flywheel-agent {
|
||||
top: 15%;
|
||||
left: 50%;
|
||||
width: 38%;
|
||||
}
|
||||
.flywheel-oracle {
|
||||
top: 58%;
|
||||
left: 79%;
|
||||
}
|
||||
.flywheel-memory {
|
||||
top: 58%;
|
||||
left: 21%;
|
||||
}
|
||||
.flywheel-retry,
|
||||
.flywheel-center,
|
||||
.flywheel-reuse,
|
||||
.flywheel-pass {
|
||||
position: absolute;
|
||||
margin: 0;
|
||||
padding: 0.25rem;
|
||||
background: var(--page);
|
||||
color: var(--muted);
|
||||
font-size: 0.75rem;
|
||||
line-height: 1.5;
|
||||
text-align: center;
|
||||
transform: translate(-50%, -50%);
|
||||
}
|
||||
.flywheel-retry {
|
||||
top: 36%;
|
||||
left: 68%;
|
||||
width: 23%;
|
||||
}
|
||||
.flywheel-center {
|
||||
top: 57%;
|
||||
left: 50%;
|
||||
width: 20%;
|
||||
color: var(--accent);
|
||||
font-size: 0.9375rem;
|
||||
}
|
||||
.flywheel-reuse {
|
||||
top: 33%;
|
||||
left: 23%;
|
||||
color: var(--accent);
|
||||
}
|
||||
.flywheel-pass {
|
||||
top: 94%;
|
||||
left: 50%;
|
||||
width: 75%;
|
||||
color: var(--accent);
|
||||
font-size: 0.8125rem;
|
||||
}
|
||||
.flywheel-projects {
|
||||
display: flex;
|
||||
justify-content: center;
|
||||
align-items: center;
|
||||
gap: 1.4rem;
|
||||
margin-top: 0.3rem;
|
||||
}
|
||||
.flywheel-projects a {
|
||||
font-size: 0.9375rem;
|
||||
font-weight: 600;
|
||||
}
|
||||
.flywheel-projects span {
|
||||
color: var(--muted);
|
||||
}
|
||||
.reconstruction-flywheel figcaption {
|
||||
margin: 1rem auto 0;
|
||||
max-width: 600px;
|
||||
color: var(--muted);
|
||||
font-size: 0.875rem;
|
||||
text-align: center;
|
||||
}
|
||||
@media (max-width: 640px) {
|
||||
.reconstruction-flywheel {
|
||||
margin-bottom: 2.75rem;
|
||||
}
|
||||
.flywheel-diagram {
|
||||
height: 405px;
|
||||
}
|
||||
.flywheel-agent {
|
||||
width: 52%;
|
||||
}
|
||||
.flywheel-path-desktop {
|
||||
display: none;
|
||||
}
|
||||
.flywheel-path-mobile {
|
||||
display: initial;
|
||||
}
|
||||
.flywheel-node h3 {
|
||||
font-size: 1.125rem;
|
||||
}
|
||||
.flywheel-node p {
|
||||
font-size: 0.75rem;
|
||||
}
|
||||
.flywheel-node .flywheel-kicker {
|
||||
font-size: 0.6rem;
|
||||
letter-spacing: 0.05em;
|
||||
}
|
||||
.flywheel-center {
|
||||
font-size: 0.75rem;
|
||||
}
|
||||
.flywheel-retry {
|
||||
font-size: 0.625rem;
|
||||
}
|
||||
.flywheel-projects {
|
||||
gap: 1rem;
|
||||
}
|
||||
}
|
||||
.blog-article blockquote {
|
||||
margin: 1.6rem 0;
|
||||
padding-left: 1.25rem;
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/blog/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="REA Blog — Thoughts on Reverse Engineering"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA Blog — Thoughts on Reverse Engineering" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/blog/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="REA Blog — Thoughts on Reverse Engineering"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="REA Blog — Thoughts on Reverse Engineering" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Thoughts on reverse engineering, drawing on practical experience with REA and AI agents." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -63,8 +65,8 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/">Showcases</a>
|
||||
<a href="./" aria-current="page">Blog</a>
|
||||
<a class="nav-start" href="../get-started/">Get started</a>
|
||||
<a href="../blog/" aria-current="page">Blog</a>
|
||||
<a href="../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / Blog</p>
|
||||
@@ -154,13 +157,14 @@
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -170,5 +174,6 @@
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
File diff suppressed because it is too large
Load Diff
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/examples/dino-lab/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Chrome Dinosaur Game: Rebuild Its Speed Rule — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Chrome Dinosaur Game: Rebuild Its Speed Rule — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/examples/dino-lab/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Chrome Dinosaur Game: Rebuild Its Speed Rule — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Chrome Dinosaur Game: Rebuild Its Speed Rule — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Read the dinosaur game’s speed rule with REA, rebuild it, then change the speed and play." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -56,6 +56,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -64,9 +66,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/">Showcases</a>
|
||||
<a href="../../blog/">Blog</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../../guides/">Guides</a><a href="../../faq/">FAQ</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -130,6 +133,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -396,21 +400,23 @@
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top"
|
||||
><span aria-hidden="true">↑</span> Top</a
|
||||
>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/faq/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="REA FAQ: Setup, Updates and Troubleshooting"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA FAQ: Setup, Updates and Troubleshooting" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/faq/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="REA FAQ: Setup, Updates and Troubleshooting"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="REA FAQ: Setup, Updates and Troubleshooting" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Answers to common REA questions: installation, updates, analysis tools, coding agents, troubleshooting and sharing examples." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -64,9 +66,9 @@
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/">Showcases</a>
|
||||
<a href="../blog/">Blog</a>
|
||||
<a class="nav-start" href="../get-started/">Get started</a>
|
||||
<a href="../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="./" aria-current="page">FAQ</a>
|
||||
<a href="../faq/" aria-current="page">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / FAQ</p>
|
||||
@@ -495,21 +498,23 @@
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top"
|
||||
><span aria-hidden="true">↑</span> Top</a
|
||||
>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/first-investigation/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Your First Reverse Engineering Investigation — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Your First Reverse Engineering Investigation — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/first-investigation/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Your First Reverse Engineering Investigation — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Your First Reverse Engineering Investigation — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Try REA on a small Notes app. Set up your agent, ask where exported notes go, and check the CSV formatter with a sample title." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -63,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/">Showcases</a>
|
||||
<a href="../blog/">Blog</a
|
||||
><a class="nav-start" href="../get-started/">Get started</a
|
||||
><a href="../guides/">Guides</a><a href="../faq/">FAQ</a>
|
||||
<a href="../blog/">Blog</a>
|
||||
<a href="../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -129,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -433,21 +437,23 @@ JS</code></pre>
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top"
|
||||
><span aria-hidden="true">↑</span> Top</a
|
||||
>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/get-started/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Install REA and Set Up Your Coding Agent"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Install REA and Set Up Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/get-started/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Install REA and Set Up Your Coding Agent"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Install REA and Set Up Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Connect REA to your coding agent or inspect a local JavaScript or Electron app from the terminal. Setup, first questions and native provider guides." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -63,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/">Showcases</a>
|
||||
<a href="../blog/">Blog</a
|
||||
><a class="nav-start" href="./" aria-current="page">Get started</a
|
||||
><a href="../guides/">Guides</a><a href="../faq/">FAQ</a>
|
||||
<a href="../blog/">Blog</a>
|
||||
<a href="../get-started/" class="nav-start" aria-current="page">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -129,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / Get started</p>
|
||||
@@ -291,8 +295,9 @@
|
||||
<div>
|
||||
<p>
|
||||
Use an existing Ghidra 12.1.x installation and a 64-bit
|
||||
JDK 21 or newer on Linux x64 or macOS x64/arm64. Set the
|
||||
paths before running setup:
|
||||
JDK 21 or newer on Linux or macOS, on x64 or arm64. Your
|
||||
Ghidra installation needs a native decompiler for your
|
||||
host architecture. Set the paths before running setup:
|
||||
</p>
|
||||
<details class="evidence-details">
|
||||
<summary>Connect your Ghidra installation</summary>
|
||||
@@ -316,8 +321,38 @@ npx rea-agents@latest setup</code></pre>
|
||||
<p>
|
||||
Replace both paths with your existing installations.
|
||||
Setup checks them and records valid settings for your
|
||||
selected client. On macOS, use a Ghidra package with the
|
||||
native decompiler matching your host architecture.
|
||||
selected client. On Linux arm64, you may need to build
|
||||
Ghidra's native decompiler separately.
|
||||
</p>
|
||||
</details>
|
||||
<details class="evidence-details">
|
||||
<summary>Connect Ghidra on Windows</summary>
|
||||
<p>
|
||||
Windows x64 has experimental, read-only support for
|
||||
native x86 and x64 PE applications and DLLs on fixed
|
||||
local NTFS drives. Use an existing Ghidra 12.1.x
|
||||
installation and a 64-bit JDK 21 or newer:
|
||||
</p>
|
||||
<div class="code-block">
|
||||
<div class="code-header">
|
||||
<span>Ghidra connection · Windows PowerShell</span>
|
||||
<button
|
||||
class="copy-button"
|
||||
type="button"
|
||||
data-copy="ghidra-windows-connect"
|
||||
aria-label="Copy Ghidra connection for Windows PowerShell"
|
||||
>
|
||||
Copy
|
||||
</button>
|
||||
</div>
|
||||
<pre><code id="ghidra-windows-connect">$env:GHIDRA_INSTALL_DIR = "C:/tools/ghidra_12.1.4_PUBLIC"
|
||||
$env:JAVA_HOME = "C:/tools/jdk-21"
|
||||
npx -y rea-agents@latest doctor --provider ghidra --json
|
||||
npx rea-agents@latest setup</code></pre>
|
||||
</div>
|
||||
<p>
|
||||
Replace the two paths with your installations, then
|
||||
review setup's plan.
|
||||
</p>
|
||||
</details>
|
||||
</div>
|
||||
@@ -492,13 +527,14 @@ npx rea-agents@latest setup</code></pre>
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -508,5 +544,6 @@ npx rea-agents@latest setup</code></pre>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,40 +8,46 @@
|
||||
name="description"
|
||||
content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/guides/browser/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Browser and Network Analysis — REA" />
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/guides/browser/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Browser and Network Analysis — REA" />
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Observe a Notes export with REA: select a browser page, capture a click, inspect the request and follow the export script." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -49,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -57,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/">Showcases</a>
|
||||
<a href="../../blog/">Blog</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a><a href="../../faq/">FAQ</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/" aria-current="page">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -123,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -416,13 +426,14 @@ link.click();</code></pre>
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -432,5 +443,6 @@ link.click();</code></pre>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,40 +8,46 @@
|
||||
name="description"
|
||||
content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/guides/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Reverse Engineering Guides — REA" />
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/guides/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Reverse Engineering Guides — REA" />
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Learn REA through short worked examples: a native calculation, an Electron CSV export and a browser request." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -49,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -57,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../showcase/">Showcases</a>
|
||||
<a href="../blog/">Blog</a
|
||||
><a class="nav-start" href="../get-started/">Get started</a
|
||||
><a href="./" aria-current="page">Guides</a><a href="../faq/">FAQ</a>
|
||||
<a href="../blog/">Blog</a>
|
||||
<a href="../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../guides/" aria-current="page">Guides</a>
|
||||
<a href="../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -123,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / Guides</p>
|
||||
@@ -199,13 +209,14 @@
|
||||
</section>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -215,5 +226,6 @@
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/guides/javascript/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="JavaScript and Electron Analysis — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="JavaScript and Electron Analysis — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/guides/javascript/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="JavaScript and Electron Analysis — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="JavaScript and Electron Analysis — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Trace a Notes CSV export through a renderer API, preload and IPC handler with REA. Includes downloadable example files and a verified analysis result." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -63,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/">Showcases</a>
|
||||
<a href="../../blog/">Blog</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a><a href="../../faq/">FAQ</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/" aria-current="page">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -129,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -418,13 +422,14 @@
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -434,5 +439,6 @@
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,40 +8,46 @@
|
||||
name="description"
|
||||
content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/guides/native/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Native Binary Analysis — REA" />
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/guides/native/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Native Binary Analysis — REA" />
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Recover a native calculation with REA: inspect instructions, follow a caller, read constants and check reconstructed C." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -49,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -57,9 +65,10 @@
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../../showcase/">Showcases</a>
|
||||
<a href="../../blog/">Blog</a
|
||||
><a class="nav-start" href="../../get-started/">Get started</a
|
||||
><a href="../">Guides</a><a href="../../faq/">FAQ</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/" aria-current="page">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -123,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -348,13 +358,14 @@ return (DxBallInt)pan;</code></pre>
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -364,5 +375,6 @@ return (DxBallInt)pan;</code></pre>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
+36
-31
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="REA — Reverse Engineering for Your Coding Agent"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="REA — Reverse Engineering for Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="REA — Reverse Engineering for Your Coding Agent"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="REA — Reverse Engineering for Your Coding Agent" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Reverse engineer apps, binaries and browser behavior with your coding agent. Follow clear guides and try interactive examples with REA." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="assets/styles.css" />
|
||||
@@ -57,6 +57,8 @@
|
||||
</head>
|
||||
<body class="home-page" id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="./" aria-label="REA home"
|
||||
@@ -64,11 +66,11 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="showcase/">Showcases</a>
|
||||
<a href="blog/">Blog</a>
|
||||
<a class="nav-start" href="get-started/">Get started</a>
|
||||
<a href="guides/">Guides</a>
|
||||
<a href="faq/">FAQ</a>
|
||||
<a href="./showcase/">Showcases</a>
|
||||
<a href="./blog/">Blog</a>
|
||||
<a href="./get-started/" class="nav-start">Get started</a>
|
||||
<a href="./guides/">Guides</a>
|
||||
<a href="./faq/">FAQ</a>
|
||||
</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
@@ -132,6 +134,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<details class="home-page-nav" data-home-nav open>
|
||||
<summary class="container">
|
||||
<span>On this page</span>
|
||||
@@ -1095,13 +1098,14 @@ SPEED: 6</code></pre>
|
||||
</div>
|
||||
</section>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -1111,5 +1115,6 @@ SPEED: 6</code></pre>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/aegis/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Aegis APK Reverse Engineering: Login Codes — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Aegis APK Reverse Engineering: Login Codes — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/aegis/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Aegis APK Reverse Engineering: Login Codes — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Aegis APK Reverse Engineering: Login Codes — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Inspect the Aegis Android APK with REA, recover its six-digit login-code calculation and try a reconstruction with an adjustable clock." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -56,6 +56,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -63,9 +65,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a href="../../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -131,6 +133,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -731,21 +734,23 @@ npx rea-agents@latest inspect-android-package \
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top"
|
||||
><span aria-hidden="true">↑</span> Top</a
|
||||
>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/ctf/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="CTF Reverse Engineering: DownUnderCTF Flag Checker — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="CTF Reverse Engineering: DownUnderCTF Flag Checker — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/ctf/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="CTF Reverse Engineering: DownUnderCTF Flag Checker — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="CTF Reverse Engineering: DownUnderCTF Flag Checker — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Use REA to solve DownUnderCTF's masked squares flag checker. Find the checking functions, extract the masks and compare a recovered flag with the original program." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -62,9 +64,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a href="../../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -701,21 +704,23 @@ chmod +x ms_flag_checker
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top"
|
||||
><span aria-hidden="true">↑</span> Top</a
|
||||
>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/dx-ball/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="DX-Ball Reverse Engineering: Sound Panning — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="DX-Ball Reverse Engineering: Sound Panning — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/dx-ball/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="DX-Ball Reverse Engineering: Sound Panning — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="DX-Ball Reverse Engineering: Sound Panning — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Follow a DX-Ball reconstruction from binary analysis through REA to maintained C, original-x86 tests and matching compiled function bytes." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -62,9 +64,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a href="../../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -709,13 +712,14 @@
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -725,5 +729,6 @@
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Reverse Engineering Case Studies — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Reverse Engineering Case Studies — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Reverse Engineering Case Studies — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Reverse Engineering Case Studies — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Follow REA investigations through code, figures and demos: an Android authenticator, DX-Ball, Notion, TH04 and a DownUnderCTF flag checker." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../" aria-label="REA home"
|
||||
@@ -62,9 +64,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="./" aria-current="page">Showcases</a>
|
||||
<a href="../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../blog/">Blog</a>
|
||||
<a class="nav-start" href="../get-started/">Get started</a>
|
||||
<a href="../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../guides/">Guides</a>
|
||||
<a href="../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="../">Home</a> / Showcases</p>
|
||||
@@ -241,13 +244,14 @@
|
||||
<a class="text-link" href="../guides/">Read the guides</a>
|
||||
</section>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -257,5 +261,6 @@
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/notion/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="Notion Electron Reverse Engineering: Clipboard — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="Notion Electron Reverse Engineering: Clipboard — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/notion/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="Notion Electron Reverse Engineering: Clipboard — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="Notion Electron Reverse Engineering: Clipboard — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Follow Notion's clipboard API through Electron's preload, IPC wrappers and main process, with short code excerpts and a look at its rich clipboard format." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -62,9 +64,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a href="../../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -547,13 +550,14 @@ mimeTypes:
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -563,5 +567,6 @@ mimeTypes:
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -8,46 +8,46 @@
|
||||
name="description"
|
||||
content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player."
|
||||
/>
|
||||
<!-- website:sharing:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="https://rea.tools/showcase/th04/" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<meta
|
||||
property="og:title"
|
||||
content="TH04 Reverse Engineering: DOS Bullet Patterns — REA"
|
||||
/>
|
||||
<meta
|
||||
property="og:description"
|
||||
content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="TH04 Reverse Engineering: DOS Bullet Patterns — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="https://rea.tools/showcase/th04/" />
|
||||
<meta
|
||||
property="og:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<meta
|
||||
name="twitter:title"
|
||||
content="TH04 Reverse Engineering: DOS Bullet Patterns — REA"
|
||||
/>
|
||||
<meta
|
||||
name="twitter:description"
|
||||
content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player."
|
||||
/>
|
||||
<meta
|
||||
name="twitter:image"
|
||||
content="https://rea.tools/assets/social-card.png"
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="TH04 Reverse Engineering: DOS Bullet Patterns — REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="Inspect TH04's original 16-bit DOS code with REA. Follow the assembly and recovered C++ to see how a ring of bullets is spaced and aimed at the player." />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="https://rea.tools/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="../../assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="../../assets/styles.css" />
|
||||
@@ -55,6 +55,8 @@
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="../../" aria-label="REA home"
|
||||
@@ -62,9 +64,9 @@
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">
|
||||
<a href="../">Showcases</a>
|
||||
<a href="../../showcase/" aria-current="page">Showcases</a>
|
||||
<a href="../../blog/">Blog</a>
|
||||
<a class="nav-start" href="../../get-started/">Get started</a>
|
||||
<a href="../../get-started/" class="nav-start">Get started</a>
|
||||
<a href="../../guides/">Guides</a>
|
||||
<a href="../../faq/">FAQ</a>
|
||||
</nav>
|
||||
@@ -130,6 +132,7 @@
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb">
|
||||
@@ -724,13 +727,14 @@ no_aim:
|
||||
</article>
|
||||
</div>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE"
|
||||
>MIT license</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
@@ -740,5 +744,6 @@ no_aim:
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
|
||||
@@ -9,8 +9,10 @@ evidence the reader can inspect, and a useful next step. A clean, refined
|
||||
appearance comes from precise wording, readable figures, consistent typography
|
||||
and deliberate spacing.
|
||||
|
||||
Use this guide for new pages and revisions. Start from an existing page and
|
||||
reuse `public/assets/styles.css` and `public/assets/main.js`. Local preview and
|
||||
Use this guide for new pages and revisions. Create the common page structure
|
||||
with `python3 scripts/website.py new-page`, then reuse the relevant components
|
||||
from an existing page, `public/assets/styles.css` and `public/assets/main.js`.
|
||||
Keep shared regions in sync with `templates/`. Contribution, preview and
|
||||
publication commands are in [README.md](README.md).
|
||||
|
||||
## What a reader should understand
|
||||
|
||||
@@ -0,0 +1,16 @@
|
||||
<!-- prettier-ignore -->
|
||||
<footer class="site-footer">
|
||||
<div class="container footer-inner">
|
||||
<p>REA · Reverse Engineer Anything</p>
|
||||
<div class="footer-links">
|
||||
<a href="https://github.com/morluto/rea">Source</a
|
||||
><a href="https://github.com/morluto/rea/blob/main/LICENSE">MIT license</a
|
||||
><a href="https://discord.gg/GkcryMnJDM">Join the community</a
|
||||
><a href="https://x.com/reatools">Follow us on X</a>
|
||||
</div>
|
||||
</div>
|
||||
</footer>
|
||||
<p class="sr-only" id="copy-status" role="status" aria-live="polite"></p>
|
||||
<a class="back-to-top" href="#top" aria-label="Back to top">
|
||||
<span aria-hidden="true">↑</span> Top
|
||||
</a>
|
||||
@@ -0,0 +1,70 @@
|
||||
<!-- prettier-ignore -->
|
||||
<header class="site-header">
|
||||
<div class="container header-inner">
|
||||
<a class="brand" href="$base" aria-label="REA home"
|
||||
><span class="brand-name">REA</span
|
||||
><span class="brand-caption">Reverse Engineer Anything</span></a
|
||||
>
|
||||
<nav class="navigation" aria-label="Main navigation">$navigation</nav>
|
||||
<div class="header-social">
|
||||
<a
|
||||
class="nav-github"
|
||||
href="https://github.com/morluto/rea"
|
||||
aria-label="REA on GitHub"
|
||||
title="REA on GitHub"
|
||||
>
|
||||
<svg
|
||||
width="22"
|
||||
height="22"
|
||||
viewBox="0 0 16 16"
|
||||
aria-hidden="true"
|
||||
focusable="false"
|
||||
>
|
||||
<path
|
||||
fill="currentColor"
|
||||
d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82a7.65 7.65 0 0 1 2-.27c.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.01 8.01 0 0 0 16 8c0-4.42-3.58-8-8-8Z"
|
||||
/>
|
||||
</svg>
|
||||
<span class="nav-github-count" hidden aria-hidden="true"></span>
|
||||
</a>
|
||||
<a
|
||||
class="nav-discord"
|
||||
href="https://discord.gg/GkcryMnJDM"
|
||||
aria-label="Join REA on Discord"
|
||||
title="Join REA on Discord"
|
||||
>
|
||||
<svg
|
||||
width="22"
|
||||
height="22"
|
||||
viewBox="0 0 24 24"
|
||||
aria-hidden="true"
|
||||
focusable="false"
|
||||
>
|
||||
<path
|
||||
fill="currentColor"
|
||||
d="M20.317 4.3698a19.7913 19.7913 0 0 0-4.8851-1.5152.0741.0741 0 0 0-.0785.0371c-.211.3753-.4447.8648-.6083 1.2495-1.8447-.2762-3.68-.2762-5.4868 0-.1636-.3933-.4058-.8742-.6177-1.2495a.077.077 0 0 0-.0785-.037 19.7363 19.7363 0 0 0-4.8852 1.515.0699.0699 0 0 0-.0321.0277C.5334 9.0458-.319 13.5799.0992 18.0578a.0824.0824 0 0 0 .0312.0561c2.0528 1.5076 4.0413 2.4228 5.9929 3.0294a.0777.0777 0 0 0 .0842-.0276c.4616-.6304.8731-1.2952 1.226-1.9942a.076.076 0 0 0-.0416-.1057c-.6528-.2476-1.2743-.5495-1.8722-.8923a.077.077 0 0 1-.0076-.1277c.1258-.0943.2517-.1923.3718-.2914a.0743.0743 0 0 1 .0776-.0105c3.9278 1.7933 8.18 1.7933 12.0614 0a.0739.0739 0 0 1 .0785.0095c.1202.099.246.1981.3728.2924a.077.077 0 0 1-.0066.1276 12.2986 12.2986 0 0 1-1.873.8914.0766.0766 0 0 0-.0407.1067c.3604.698.7719 1.3628 1.225 1.9932a.076.076 0 0 0 .0842.0286c1.961-.6067 3.9495-1.5219 6.0023-3.0294a.077.077 0 0 0 .0313-.0552c.5004-5.177-.8382-9.6739-3.5485-13.6604a.061.061 0 0 0-.0312-.0286ZM8.02 15.3312c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9555-2.4189 2.157-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.9555 2.4189-2.1569 2.4189Zm7.9748 0c-1.1825 0-2.1569-1.0857-2.1569-2.419 0-1.3332.9554-2.4189 2.1569-2.4189 1.2108 0 2.1757 1.0952 2.1568 2.419 0 1.3332-.946 2.4189-2.1568 2.4189Z"
|
||||
/>
|
||||
</svg>
|
||||
</a>
|
||||
<a
|
||||
class="nav-x"
|
||||
href="https://x.com/reatools"
|
||||
aria-label="Follow REA on X"
|
||||
title="Follow REA on X"
|
||||
>
|
||||
<svg
|
||||
width="18"
|
||||
height="18"
|
||||
viewBox="0 0 24 24"
|
||||
aria-hidden="true"
|
||||
focusable="false"
|
||||
>
|
||||
<path
|
||||
fill="currentColor"
|
||||
d="M18.901 1.153h3.68l-8.04 9.19L24 22.846h-7.406l-5.8-7.584-6.638 7.584H.474l8.6-9.83L0 1.154h7.594l5.243 6.932ZM17.61 20.644h2.039L6.486 3.24H4.298Z"
|
||||
/>
|
||||
</svg>
|
||||
</a>
|
||||
</div>
|
||||
</div>
|
||||
</header>
|
||||
@@ -0,0 +1,38 @@
|
||||
<!doctype html>
|
||||
<html lang="en">
|
||||
<head>
|
||||
<meta charset="utf-8" />
|
||||
<meta name="viewport" content="width=device-width, initial-scale=1" />
|
||||
<title>$title</title>
|
||||
<meta name="description" content="$description" />
|
||||
<meta name="robots" content="noindex" />
|
||||
<!-- website:sharing:start -->
|
||||
<!-- website:sharing:end -->
|
||||
<meta name="theme-color" content="#ffffff" />
|
||||
<link rel="icon" href="${base}assets/favicon.svg" type="image/svg+xml" />
|
||||
<link rel="stylesheet" href="${base}assets/styles.css" />
|
||||
<script src="${base}assets/main.js" defer></script>
|
||||
</head>
|
||||
<body id="top">
|
||||
<a class="skip-link" href="#main">Skip to content</a>
|
||||
<!-- website:header:start -->
|
||||
<!-- website:header:end -->
|
||||
<main id="main" class="container">
|
||||
<div class="page-heading">
|
||||
<p class="breadcrumb"><a href="$base">Home</a> / Draft</p>
|
||||
<h1>$title</h1>
|
||||
<p class="lede">$description</p>
|
||||
</div>
|
||||
<article class="article">
|
||||
<section class="article-section" id="question">
|
||||
<h2>The question</h2>
|
||||
<p>
|
||||
Introduce one concrete question, then show the evidence and result.
|
||||
</p>
|
||||
</section>
|
||||
</article>
|
||||
</main>
|
||||
<!-- website:footer:start -->
|
||||
<!-- website:footer:end -->
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,38 @@
|
||||
<!-- prettier-ignore -->
|
||||
<link rel="canonical" href="$canonical" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:type" content="website" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:site_name" content="REA" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:title" content="$title" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:description" content="$description" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:url" content="$canonical" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image" content="$origin/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:type" content="image/png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:width" content="1200" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta property="og:image:height" content="630" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
property="og:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:card" content="summary_large_image" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:title" content="$title" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:description" content="$description" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta name="twitter:image" content="$origin/assets/social-card.png" />
|
||||
<!-- prettier-ignore -->
|
||||
<meta
|
||||
name="twitter:image:alt"
|
||||
content="REA — Find out how software works. Reverse engineering with your coding agent."
|
||||
/>
|
||||
@@ -11,7 +11,7 @@ not_found_handling = "none"
|
||||
|
||||
[build]
|
||||
cwd = ".."
|
||||
command = "python3 scripts/prepare-website.py && python3 scripts/verify-website.py"
|
||||
command = "python3 scripts/website.py check"
|
||||
watch_dir = "./public/examples/notes-electron"
|
||||
|
||||
# Public HTTPS depends on zone activation and certificate readiness.
|
||||
|
||||
Reference in New Issue
Block a user