Repository navigation
docs: add the Argus documentation site - #3
Conversation
|
Warning Review limit reached
Next review available in: 49 minutes Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available. How can I continue?After more reviews become available, a review can be triggered using the To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews. How do review limits work?CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability. For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window. Please refer docs for additional details. Review details⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Plus Run ID: ⛔ Files ignored due to path filters (2)
📒 Files selected for processing (36)
📝 WalkthroughWalkthroughThe pull request adds a complete Astro/Starlight documentation website for Argus, including site configuration, styling, local development guidance, and extensive documentation covering installation, CLI usage, Hermes engines and provisioning, test APIs, internals, limitations, and roadmap. ChangesArgus documentation website
Estimated code review effort: 4 (Complex) | ~45 minutes 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Astro + Starlight site under website/, outside the pnpm workspace so it installs and builds independently of the runner. 26 pages covering installation, the test-authoring surface, Hermes engine selection and provisioning, the React Native to Hermes version table, CLI usage, internals and the roadmap. Anchors the docs/ and openspec/ ignore rules to the repo root so the site's own content directory stays tracked.
hermes-bin-v250829098.0.16 is live with all four platforms, so the "nothing published yet" caveat is wrong. Splits the version table's prebuilt column into published vs publishable, since only the V1 ref React Native 0.86 and 0.87 share has a release so far.
website/ is its own package with its own toolchain, outside the pnpm workspace. Biome cannot parse its Tailwind v4 CSS at all, and reformatting Astro config and content to the runner's style would fight Astro's own conventions for no benefit.
There was a problem hiding this comment.
Actionable comments posted: 14
🧹 Nitpick comments (1)
website/.gitignore (1)
6-8: 🔒 Security & Privacy | 🔵 Trivial | ⚡ Quick winIgnore all local environment variants.
.env.local,.env.development, and other.env.*files remain eligible for accidental commits. Use a wildcard while explicitly allowing.env.example.Proposed fix
- .env - .env.production + .env + .env.* + !.env.example🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@website/.gitignore` around lines 6 - 8, Update the Environment entries in .gitignore to ignore all .env.* variants with a wildcard pattern, while explicitly unignoring .env.example so the template remains versioned.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@website/astro.config.mjs`:
- Around line 7-106: Run the repository-configured Biome formatter and commit
its output for website/astro.config.mjs lines 7-106 and
website/src/content.config.ts lines 5-7; both sites require formatting-only
changes, with no behavioral modifications.
In `@website/package.json`:
- Line 22: Update the onlyBuiltDependencies entry in package.json to the
multiline array format required by Biome, preserving the existing esbuild and
sharp values.
In `@website/README.md`:
- Around line 41-44: Update the deployment instructions around the Wrangler
command to make Wrangler availability self-contained: either document the
required global Wrangler installation or declare Wrangler in
website/package.json and invoke it through pnpm exec wrangler. Ensure the
documented command works without an undeclared local binary prerequisite.
In `@website/src/content/docs/cli/reporting.md`:
- Around line 21-29: Update the sample test summary in the reporting
documentation to show 2 passed, 1 failed, 1 todo, and 1 skipped test, including
the skipped count in the total. Keep the individual test results unchanged.
- Around line 83-89: Update the protocol failure example in the reporting
documentation to use the actual parseHermesOutput reason, changing the displayed
reason from [no-frame] to [missing-frame] while leaving the surrounding output
and explanation unchanged.
In `@website/src/content/docs/hermes/engines.md`:
- Around line 8-22: Update the Hermes history and default-engine wording in the
documentation to match the RN 0.82 V1 pin recorded in versions.md, rather than
stating that two engines begin with RN 0.83. Clarify that React Native 0.83
defaults to legacy Hermes while Argus intentionally defaults to Hermes V1, and
reserve the “mirroring React Native” claim for versions where that behavior
matches.
In `@website/src/content/docs/hermes/prebuilts.md`:
- Around line 115-118: Update the explanatory paragraph around the version table
to limit the 404 claim to versioned refs that can name a release, rather than
all pinned versions. Explicitly distinguish those release-capable rows from bare
SHAs and date-based refs that require source provisioning, while preserving the
existing fallback and roadmap references.
In `@website/src/content/docs/index.mdx`:
- Around line 84-88: Update the Status caution in the documentation to
explicitly state that `@argus/cli` is not yet published and npm installation is
unavailable. Add a supported local-install workflow here and in the installation
guidance, or remove installation CTAs until publication; ensure visitors are not
directed toward a failing package installation path.
In `@website/src/content/docs/internals/result-protocol.md`:
- Around line 82-83: Update the result-protocol documentation so a non-zero
Hermes exit is classified as an infrastructure-failure even when a frame is
present. Reserve protocol-failure for other protocol violations, and revise the
raw-stdout diagnostic wording to reflect this distinction.
In `@website/src/content/docs/internals/source-maps.md`:
- Around line 47-48: Update the documentation sentence describing
internal-source matching to distinguish the prefix-based Argus path check from
the substring-based detection of nested /node_modules/ paths. Avoid
characterizing the entire rule exclusively as a startsWith check.
- Around line 27-28: Update the documentation around remapFrame() to state that
Argus internal frames are preserved unchanged rather than dropped. Remove the
claim that resulting stacks contain only user code, while retaining the
explanation that remapping resolves user frames.
In `@website/src/content/docs/reference/roadmap.md`:
- Around line 79-81: Update the roadmap’s native import() configuration note to
state that direct TypeScript config loading requires Node 22.18 or newer, is
enabled by default in Node 24, and supports only erasable TypeScript syntax
while ignoring tsconfig.json. Add guidance to use the config formatter with
erasableSyntaxOnly, or retain/transpile configs through a loader for older
supported runtimes.
In `@website/src/content/docs/start/installation.mdx`:
- Around line 23-37: Make the documented `@argus/cli` installation path usable
before shipping the getting-started docs: publish `@argus/cli`, or replace the
package-manager commands in website/src/content/docs/start/installation.mdx
(lines 23-37) and website/src/content/docs/start/quickstart.mdx (lines 12-16)
with supported prerelease or local installation instructions. Keep both
documentation sites consistent.
In `@website/src/content/docs/tests/matchers.md`:
- Around line 14-18: Update the `toBe(expected)` documentation to describe the
single equality algorithm actually used by its implementation, resolving the
`Object.is` versus SameValueZero inconsistency. Add a regression test covering
`-0` versus `0`, and keep the matcher table and examples aligned with the
verified behavior.
---
Nitpick comments:
In `@website/.gitignore`:
- Around line 6-8: Update the Environment entries in .gitignore to ignore all
.env.* variants with a wildcard pattern, while explicitly unignoring
.env.example so the template remains versioned.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: 4aa2ed0c-143f-4d3f-ac68-316e3aa886b6
⛔ Files ignored due to path filters (2)
website/pnpm-lock.yamlis excluded by!**/pnpm-lock.yamlwebsite/public/favicon.svgis excluded by!**/*.svg
📒 Files selected for processing (35)
.gitignorewebsite/.gitignorewebsite/README.mdwebsite/astro.config.mjswebsite/package.jsonwebsite/src/content.config.tswebsite/src/content/docs/404.mdwebsite/src/content/docs/cli/reporting.mdwebsite/src/content/docs/cli/usage.mdwebsite/src/content/docs/hermes/engines.mdwebsite/src/content/docs/hermes/prebuilts.mdwebsite/src/content/docs/hermes/provisioning.mdwebsite/src/content/docs/hermes/syntax-envelope.mdwebsite/src/content/docs/hermes/versions.mdwebsite/src/content/docs/index.mdxwebsite/src/content/docs/internals/architecture.mdwebsite/src/content/docs/internals/packages.mdwebsite/src/content/docs/internals/result-protocol.mdwebsite/src/content/docs/internals/source-maps.mdwebsite/src/content/docs/reference/contributing.mdwebsite/src/content/docs/reference/limitations.mdwebsite/src/content/docs/reference/roadmap.mdwebsite/src/content/docs/start/concepts.mdwebsite/src/content/docs/start/installation.mdxwebsite/src/content/docs/start/introduction.mdwebsite/src/content/docs/start/quickstart.mdxwebsite/src/content/docs/start/why-hermes.mdwebsite/src/content/docs/tests/async.mdwebsite/src/content/docs/tests/components.mdxwebsite/src/content/docs/tests/matchers.mdwebsite/src/content/docs/tests/mocks.mdwebsite/src/content/docs/tests/native-modules.mdwebsite/src/content/docs/tests/structure.mdwebsite/src/styles/global.csswebsite/tsconfig.json
| "tailwindcss": "^4.3.3" | ||
| }, | ||
| "pnpm": { | ||
| "onlyBuiltDependencies": ["esbuild", "sharp"] |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Format onlyBuiltDependencies as required by CI.
Biome rejects the current one-line array, so the check job cannot pass.
Proposed fix
- "onlyBuiltDependencies": ["esbuild", "sharp"]
+ "onlyBuiltDependencies": [
+ "esbuild",
+ "sharp"
+ ]📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| "onlyBuiltDependencies": ["esbuild", "sharp"] | |
| "onlyBuiltDependencies": [ | |
| "esbuild", | |
| "sharp" | |
| ] |
🧰 Tools
🪛 GitHub Actions: CI / 0_Typecheck, Check, Test.txt
[error] 22-25: Formatter (Biome) failed: "onlyBuiltDependencies" should be formatted as a multi-line array.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/package.json` at line 22, Update the onlyBuiltDependencies entry in
package.json to the multiline array format required by Biome, preserving the
existing esbuild and sharp values.
Source: Pipeline failures
| ```bash | ||
| cd website | ||
| pnpm build | ||
| wrangler pages deploy dist --project-name argus-hermes |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files | rg '(^|/)website/(README\.md|package\.json)$|(^|/)pnpm-lock\.yaml$' || true
echo
echo "== website README relevant lines =="
if [ -f website/README.md ]; then
nl -ba website/README.md | sed -n '1,90p'
fi
echo
echo "== website package =="
if [ -f website/package.json ]; then
cat website/package.json | jq '{name, scripts, dependencies, devDependencies}'
fi
echo
echo "== wrangler mentions in website =="
rg -n "wrangler|Wrangler" website README.md . --glob '!node_modules**' --glob '!dist**' --glob '!build**' 2>/dev/null | head -100 || trueRepository: malopezr7/argus
Length of output: 320
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== commit status/diff stat =="
git status --short
git diff --stat HEAD~1 HEAD 2>/dev/null || true
echo
echo "== lockfile snippets for wrangler/cloudflare:"
if [ -f pnpm-lock.yaml ]; then
rg -n "wrangler|`@cloudflare/workers`" pnpm-lock.yaml | head -80 || true
fiRepository: malopezr7/argus
Length of output: 296
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== website README relevant lines =="
awk '{printf "%5d\t%s\n", NR, $0}' website/README.md | sed -n '1,120p'
echo
echo "== website package deps/scripts =="
awk '{printf "%5d\t%s\n", NR, $0}' website/package.json | sed -n '1,220p'
echo
echo "== wrangler mentions in repo relevant files =="
for f in website/README.md website/package.json website/pnpm-lock.yaml pnpm-lock.yaml; do
[ -f "$f" ] || continue
echo "--- $f ---"
awk '{printf "%5d\t%s\n", NR, $0}' "$f" | rg -n "wrangler|Wrangler|cloudflare|packages|dependencies|devDependencies|pnpm" -C 2 || true
doneRepository: malopezr7/argus
Length of output: 50373
Make the local deployment command self-contained.
wrangler is not declared in website/package.json, so running this deployment command from website without preinstalling Wrangler can fail with wrangler: command not found. Document a global Wrangler prerequisite, or add it to website/package.json and run it via pnpm exec wrangler.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/README.md` around lines 41 - 44, Update the deployment instructions
around the Wrangler command to make Wrangler availability self-contained: either
document the required global Wrangler installation or declare Wrangler in
website/package.json and invoke it through pnpm exec wrangler. Ensure the
documented command works without an undeclared local binary prerequisite.
| 3 passed, 1 failed, 1 todo, 5 total (52 ms in Hermes) | ||
|
|
||
| ✓ money.test.ts | ||
| ✗ cart.test.ts (test failure) | ||
| ✗ applies a discount — expected 450 but received 500 | ||
| at src/cart.test.ts:24:28 | ||
|
|
||
| 2 files: 1 passed, 1 failed | ||
| 9 tests: 7 passed, 1 failed, 1 todo |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Correct the sample test counts.
The displayed tests contain 2 passed, 1 failed, 1 todo, and 1 skipped test. The summary currently says 3 passed and omits the skipped test.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/cli/reporting.md` around lines 21 - 29, Update the
sample test summary in the reporting documentation to show 2 passed, 1 failed, 1
todo, and 1 skipped test, including the skipped count in the total. Keep the
individual test results unchanged.
| ✗ PROTOCOL FAILURE [no-frame] | ||
| --- raw stdout --- | ||
| <everything the process printed> | ||
| ``` | ||
|
|
||
| The Hermes process exited without producing exactly one valid result frame. Raw stdout is | ||
| dumped in full, because when the protocol breaks the only useful thing left is everything. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Use the actual protocol failure reason.
parseHermesOutput returns reason: 'missing-frame', and the reporter prints that reason directly. This example should show [missing-frame], not [no-frame].
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/cli/reporting.md` around lines 83 - 89, Update the
protocol failure example in the reporting documentation to use the actual
parseHermesOutput reason, changing the displayed reason from [no-frame] to
[missing-frame] while leaving the surrounding output and explanation unchanged.
| Frames that resolve to Argus' own internals — the framework, the polyfills, the virtual | ||
| entry — are dropped, so the stack you read is your code and only your code. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
Document internal-frame preservation accurately.
remapFrame() returns internal frames unchanged; it does not drop them. This wording promises stacks containing only user code, which the implementation does not provide.
Proposed wording
-Frames that resolve to Argus' own internals — the framework, the polyfills, the virtual
-entry — are dropped, so the stack you read is your code and only your code.
+Frames that resolve to Argus' own internals — the framework, the polyfills, the virtual
+entry — are preserved as-is, while user frames are remapped to their original sources.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Frames that resolve to Argus' own internals — the framework, the polyfills, the virtual | |
| entry — are dropped, so the stack you read is your code and only your code. | |
| Frames that resolve to Argus' own internals — the framework, the polyfills, the virtual | |
| entry — are preserved as-is, while user frames are remapped to their original sources. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/internals/source-maps.md` around lines 27 - 28,
Update the documentation around remapFrame() to state that Argus internal frames
are preserved unchanged rather than dropped. Remove the claim that resulting
stacks contain only user code, while retaining the explanation that remapping
resolves user frames.
| Deciding "is this frame Argus' own code?" is a **`startsWith`** check, not a substring | ||
| check. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
Qualify the internal-source matching rule.
The implementation uses prefix checks for Argus paths, but it also detects nested node_modules paths with includes('/node_modules/'). Calling this exclusively a startsWith check is inaccurate.
Proposed wording
-Deciding "is this frame Argus' own code?" is a **`startsWith`** check, not a substring
-check.
+Deciding "is this frame Argus' own code?" uses prefix checks for Argus paths and an
+explicit nested-`node_modules` check, rather than broad substring matching.📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| Deciding "is this frame Argus' own code?" is a **`startsWith`** check, not a substring | |
| check. | |
| Deciding "is this frame Argus' own code?" uses prefix checks for Argus paths and an | |
| explicit nested-`node_modules` check, rather than broad substring matching. |
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/internals/source-maps.md` around lines 47 - 48,
Update the documentation sentence describing internal-source matching to
distinguish the prefix-based Argus path check from the substring-based detection
of nested /node_modules/ paths. Avoid characterizing the entire rule exclusively
as a startsWith check.
| Precedence, lowest to highest: defaults → `package.json` field → config file → environment | ||
| → CLI flags. Loading uses native `import()`; Node type-strips `argus.config.ts` directly, | ||
| so this needs no dependency and no bundler. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -eu
fd -t f 'package.json' -o -name '.node-version' -o -name '.tool-versions' -o -name 'Dockerfile' |
xargs -r rg -n -C2 '"engines"|node-version|FROM node:|nodejs'Repository: malopezr7/argus
Length of output: 314
🏁 Script executed:
#!/usr/bin/env bash
set -eu
echo "== relevant tracked files =="
git ls-files | rg '(^|/)(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb|Dockerfile|\.node-version|\.tool-versions|website/src/content/docs/reference/roadmap\.md)$' || true
echo
echo "== roadmap lines =="
if [ -f website/src/content/docs/reference/roadmap.md ]; then
sed -n '70,86p' website/src/content/docs/reference/roadmap.md | cat -n
fi
echo
echo "== node/ts config/version references =="
git ls-files | rg '(^|/)(package\.json|Dockerfile|\.node-version|\.tool-versions|README\.md|docs/|website/src/content/docs/reference/roadmap\.md)$' | while read -r f; do
echo "--- $f"
rg -n -C2 '"node"|engines|FROM node:|node:|node-version|nodejs|typescript|ts-node|tsx|argus\.config\.ts|config file|loading uses native|import\(\)' "$f" || true
doneRepository: malopezr7/argus
Length of output: 4732
🌐 Web query:
Node.js v24 TypeScript support type stripping default tsconfig ignore declaration comments erasable syntax
💡 Result:
In Node.js v24, type stripping is enabled by default [1][2]. This feature allows Node.js to execute TypeScript files natively by removing erasable syntax (such as type annotations, interfaces, and type aliases) and replacing it with whitespace before execution [1][3]. Key details regarding this support include: - tsconfig.json Interaction: Node.js does not read or use tsconfig.json files at runtime [1][3]. Consequently, features that depend on tsconfig settings—such as module resolution paths or down-leveling JavaScript syntax—are not supported by this native type stripping process [1][4]. - Recommended Configuration: While Node.js ignores tsconfig.json, it is strongly recommended that you configure your editor and the TypeScript compiler (tsc) to align with Node.js behavior. Node.js officially recommends using TypeScript 5.8 or newer with the following compilerOptions [5][6]: { "compilerOptions": { "noEmit": true, "target": "esnext", "module": "nodenext", "rewriteRelativeImportExtensions": true, "erasableSyntaxOnly": true, "verbatimModuleSyntax": true } } - erasableSyntaxOnly: This TypeScript compiler option is recommended because it forces the TypeScript type checker to only allow syntax that can be safely erased by Node.js, ensuring that your code does not contain features (like enums or namespace declarations) that would cause runtime errors when executed by Node.js without transformation [7][8]. - Declaration Comments: Node.js performs type stripping by removing supported syntax and replacing it with whitespace [1][5]. It does not specifically "ignore" or parse declaration comments in the context of a tsconfig file, as it does not parse tsconfig files at all [1][5]. If your project requires TypeScript features that involve JavaScript code generation (such as enums, namespaces, or parameter properties), you must either use a third-party transpiler or enable the --experimental-transform-types flag in Node.js [1][4]. To completely disable native type stripping, you can use the --no-strip-types flag [1][6].
Citations:
- 1: https://nodejs.org/docs/latest-v24.x/api/typescript.html
- 2: https://docs.redhat.com/en/documentation/red_hat_build_of_node.js/24/html/release_notes_for_node.js_24/features-nodejs
- 3: https://nodejs.org/learn/typescript/run-natively
- 4: https://nodejs.org/docs/v24.0.0/api/typescript.html
- 5: https://github.com/nodejs/node/blob/main/doc/api/typescript.md
- 6: https://nodejs.org/api/typescript.html
- 7: https://www.typescriptlang.org/tsconfig/erasableSyntaxOnly.html
- 8: doc: TypeScript docs should recommend
erasableSyntaxOnlynodejs/node#57271
🌐 Web query:
Node 22 TypeScript type stripping default enabled argus.config.ts type annotations enum namespace
💡 Result:
In Node.js 22, native TypeScript support via type stripping is enabled by default as of version 22.18.0 [1][2]. Node.js performs this by removing erasable TypeScript syntax (such as type annotations, interfaces, and type aliases) and replacing it with whitespace [1][3][2]. Regarding specific TypeScript features like enums and namespaces: 1. Default Behavior: By default, Node.js only supports TypeScript syntax that can be erased without changing the runtime JavaScript [3][2]. If a file contains TypeScript features that require transformation—such as enums or namespaces containing runtime code—Node.js will throw an ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX error [2][4]. 2. Namespaces: Namespaces are supported only if they are "type-only" (i.e., they do not contain runtime code) [2][4]. If a namespace exports values, it will trigger an error unless additional flags are used [2][4]. 3. Enabling Full Support: To support features that require code transformation (like enums and instantiated namespaces), you must use the --experimental-transform-types flag [1][2]. 4. Configuration: Node.js does not read or respect tsconfig.json files when using native type stripping [1][2]. Features that rely on tsconfig settings (such as paths or downleveling syntax) are intentionally unsupported [1][2]. Node.js recommends using the verbatimModuleSyntax option in your TypeScript configuration to ensure compatibility with the type-stripping process [5][6]. For scenarios requiring full TypeScript support beyond what is provided by native type stripping (including full tsconfig support), Node.js documentation recommends using third-party packages [1][2].
Citations:
- 1: https://nodejs.org/docs/latest-v22.x/api/typescript.html
- 2: https://nodejs.org/api/typescript.html
- 3: https://nodejs.org/learn/typescript/run-natively
- 4: https://nodejs.org/docs/latest/api/typescript.html
- 5: https://nodejs.org/download/release/v22.12.0/docs/api/typescript.html
- 6: https://nodejs.org/docs/v22.14.0/api/typescript.html
State the runtime limits for direct TypeScript configs.
Native import() type stripping requires at least Node 22.18, is default in Node 24, and only executes erasable TypeScript syntax (tsconfig.json is ignored). Add that Node floor and the config-formatter/erasableSyntaxOnly guidance, or keep/transpile with a loader for older supported runtimes.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/reference/roadmap.md` around lines 79 - 81, Update
the roadmap’s native import() configuration note to state that direct TypeScript
config loading requires Node 22.18 or newer, is enabled by default in Node 24,
and supports only erasable TypeScript syntax while ignoring tsconfig.json. Add
guidance to use the config formatter with erasableSyntaxOnly, or
retain/transpile configs through a loader for older supported runtimes.
| <Tabs syncKey="pm"> | ||
| <TabItem label="pnpm"> | ||
| ```bash | ||
| pnpm add -D @argus/cli | ||
| ``` | ||
| </TabItem> | ||
| <TabItem label="npm"> | ||
| ```bash | ||
| npm install --save-dev @argus/cli | ||
| ``` | ||
| </TabItem> | ||
| <TabItem label="yarn"> | ||
| ```bash | ||
| yarn add -D @argus/cli | ||
| ``` |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | 🏗️ Heavy lift
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== package manifests =="
git ls-files '*package.json' 'pnpm-lock.yaml' 'yarn.lock' 'package-lock.json' | sed -n '1,80p'
echo
echo "== relevant docs lines =="
for f in website/src/content/docs/start/installation.mdx website/src/content/docs/start/quickstart.mdx; do
if [ -f "$f" ]; then
echo "--- $f"
nl -ba "$f" | sed -n '1,80p'
else
echo "missing $f"
fi
done
echo
echo "== references to `@argus/cli` in repo =="
rg -n --hidden '`@argus/cli`|argus/cli|install `@argus`|npm install.*`@argus`|pnpm add.*`@argus`' . || true
echo
echo "== package metadata availability =="
npm view `@argus/cli` version dist-tags --json 2>&1 || trueRepository: malopezr7/argus
Length of output: 782
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== relevant docs lines =="
for f in website/src/content/docs/start/installation.mdx website/src/content/docs/start/quickstart.mdx; do
if [ -f "$f" ]; then
echo "--- $f"
awk '{printf "%4d %s\n", NR, $0}' "$f" | sed -n '1,80p'
else
echo "missing $f"
fi
done
echo
echo "== references to `@argus/cli` in repo =="
grep -RIn '`@argus/cli`|argus/cli|install `@argus`|npm install.*`@argus`|pnpm add.*`@argus`' . || true
echo
echo "== package manifests for `@argus/cli` artifacts =="
if [ -f package.json ]; then
echo "--- root package.json scripts"
python3 - <<'PY'
import json
from pathlib import Path
for p in ["package.json","packages/cli/package.json","website/package.json"]:
if Path(p).exists():
data=json.loads(Path(p).read_text())
print(p, "scripts=", data.get("scripts"))
print(p, "dependencies `@argus/cli`=", data.get("dependencies",{}).get("`@argus/cli`"),
"devDependencies `@argus/cli`=", data.get("devDependencies",{}).get("`@argus/cli`"))
PY
fi
echo
echo "== package metadata availability =="
npm view `@argus/cli` version dist-tags --json 2>&1 || true
echo
echo "== lockfile publishable entries =="
grep -n '`@argus/cli`' pnpm-lock.yaml || trueRepository: malopezr7/argus
Length of output: 7822
Publish @argus/cli before shipping these getting-started install steps.
@argus/cli is referenced from both the installation and quickstart docs, but it is not published and is not present in the repo’s package manifests/lockfile, so users following this path will fail at the first install step. Publish the package first, or replace both commands with supported prerelease/local install instructions.
📍 Affects 2 files
website/src/content/docs/start/installation.mdx#L23-L37(this comment)website/src/content/docs/start/quickstart.mdx#L12-L16
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/start/installation.mdx` around lines 23 - 37, Make
the documented `@argus/cli` installation path usable before shipping the
getting-started docs: publish `@argus/cli`, or replace the package-manager
commands in website/src/content/docs/start/installation.mdx (lines 23-37) and
website/src/content/docs/start/quickstart.mdx (lines 12-16) with supported
prerelease or local installation instructions. Keep both documentation sites
consistent.
| | Matcher | Passes when | | ||
| |---|---| | ||
| | `toBe(expected)` | `Object.is`-style identity (`SameValueZero`) | | ||
| | `toEqual(expected)` | Recursively equal, ignoring `undefined` properties | | ||
| | `toStrictEqual(expected)` | Recursively equal, `undefined` properties significant, types must match | |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/usr/bin/env bash
set -eu
fd -t f -e ts -e tsx -e js -e mjs . -0 |
xargs -0 -r rg -n -C3 'Object\.is|SameValueZero|\btoBe\b'Repository: malopezr7/argus
Length of output: 50372
🏁 Script executed:
#!/usr/bin/env bash
set -eu
# Inspect the matcher documentation and relevant framework source/test examples without loading generated artifacts.
printf '--- docs snippet ---\n'
sed -n '1,40p' website/src/content/docs/tests/matchers.md
printf '\n--- matchers implementation references ---\n'
rg -n -C4 'toBe\s*=|Object\.is|SameValueZero|expected === actual|typeof expected|toBeGreater|toEqual|toStrictEqual' packages frameworks examples website -S | head -n 220
printf '\n--- examples/matchers.test.ts ---\n'
if [ -f examples/matchers.test.ts ]; then sed -n '1,220p' examples/matchers.test.ts; fi
printf '\n--- framework matcher definitions ---\n'
fd -t f . packages/framework src packages -0 2>/dev/null | xargs -0 -r rg -n "toBe|toEqual|toStrictEqual|Object\.is|SameValueZero" --glob '*.ts' | head -n 240
printf '\n--- focused equality implementation files ---\n'
fd -i 'matcher|expect|assert' packages/framework packages -0 2>/dev/null | head -n 80Repository: malopezr7/argus
Length of output: 244
🏁 Script executed:
#!/usr/bin/env bash
set -eu
# Read-only behavioral probe for the documented comparison: same numbers for Object.is and SameValueZero.
node - <<'JS'
const sameValueZero = Object.is;
console.log(JSON.stringify({
Object_is_negative_zero_equals_positive_zero: Object.is(-0, 0),
sameValueZero_negative_zero_equals_positive_zero: sameValueZero(-0, 0),
}, null, 2));
JSRepository: malopezr7/argus
Length of output: 274
🏁 Script executed:
#!/usr/bin/env bash
set -eu
printf '%s\n' '--- docs snippet ---'
sed -n '1,45p' website/src/content/docs/tests/matchers.md
printf '%s\n' ''
printf '%s\n' '--- examples/matchers.test.ts ---'
if [ -f examples/matchers.test.ts ]; then
sed -n '1,240p' examples/matchers.test.ts
else
echo "examples/matchers.test.ts not found"
fi
printf '%s\n' ''
printf '%s\n' '--- Object.is/SameValueZero mentions in tracked TS/TSX/JS/MJ files ---'
git ls-files '*.ts' '*.tsx' '*.js' '*.mjs' | xargs -r rg -n -C3 'Object\.is|SameValueZero|toBe\s*[=:]|toEqual|toStrictEqual|SameValueZero' | head -n 240
printf '%s\n' ''
printf '%s\n' '--- matcher implementation definitions (focused) ---'
git ls-files | rg 'packages/framework|packages/.*matcher|matchers' && \
git ls-files | rg 'packages/framework|packages/.*matcher|matchers' | xap -r rg -n -C4 'function toBe|toBe(?:\(|:| =)|Object\.is|SameValueZero|expected === actual' -- '*.ts' '*.js' | head -n 250 || true
printf '%s\n' ''
printf '%s\n' '--- JS numeric comparison probe ---'
node - <<'JS'
const sameValueZero = Object.is;
console.log(JSON.stringify({
Object_is_negative_zero_equals_positive_zero: Object.is(-0, 0),
sameValueZero_negative_zero_equals_positive_zero: sameValueZero(-0, 0),
}, null, 2));
JSRepository: malopezr7/argus
Length of output: 25852
Document toBe with a single equality algorithm.
Match toBe to the implementation, which uses Object.is, or change the implementation/docs if SameValueZero semantics are intended. Add a signed-zero regression test such as -0 vs 0 and keep the matcher examples/docs consistent.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@website/src/content/docs/tests/matchers.md` around lines 14 - 18, Update the
`toBe(expected)` documentation to describe the single equality algorithm
actually used by its implementation, resolving the `Object.is` versus
SameValueZero inconsistency. Add a regression test covering `-0` versus `0`, and
keep the matcher table and examples aligned with the verified behavior.
CONTRIBUTING.md, SECURITY.md and CODE_OF_CONDUCT.md now exist and cover setup, gates, architecture rules and reporting. The site page restated them, which is two copies of the same rules waiting to diverge, so it now links to them and keeps only what they do not cover: why a green Node suite is not evidence, the adversarial fixtures, and how to work on the site itself.
Adds the Argus documentation site: Astro + Starlight, 27 pages, deployed to
Cloudflare Pages at https://argus-hermes.pages.dev.
Where it lives
website/, deliberately outside the pnpm workspace —pnpm-workspace.yamlonly covers
packages/*— so it installs and builds on its own and nevertouches the runner's dependency graph. Install with
pnpm install --ignore-workspace.Content
Everything is derived from the code in this repository — the provisioning
precedence, the pin sources, the bytecode-version identity, the asset naming,
the cmake flags, the matcher surface and the component-testing API.
One change outside
website/The root
.gitignorehad unanchoreddocs/andopenspec/rules, which matcha directory of that name at any depth and were silently swallowing
website/src/content/docs/— the entire site content. Anchored to/docs/and/openspec/, which is what those rules were for.Note on installation docs
The installation page documents
pnpm add -D @argus/cli, which is notpublished yet.
arguson npm is taken by an unrelated abandoned package; the@argus/*scope is free. If distribution moves to GitHub Release tarballsinstead of npm, that page is the only one that changes.
Verified
pnpm build— 27 pages, cleanSummary by CodeRabbit
New Features
Documentation