Repository navigation
refactor: make module imports point one way - #1339
brendanjryan wants to merge 32 commits into
Conversation
mppx/validation imported the CLI's payment flow, which pulled in the bundled incur dependency, so the published entry failed to load. validate() now takes an optional payment validator, and mppx validate passes the CLI's. Shared HTML payment-page infrastructure, x402 wire helpers and the MCP credential helpers move under src/internal, and the MCP SDK server transport moves under src/server, so core, internal, client and server no longer import methods, adapters or the CLI. A new layering test enforces the order. Public entry points are unchanged.
Codex Review Summary: ✅ CompletedThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
commit: |
| export type PaymentValidator = ( | ||
| baseUrl: string, | ||
| endpoint: EndpointSpec, | ||
| verbose: boolean, | ||
| options: { | ||
| body?: string | undefined | ||
| query?: string[] | undefined | ||
| extraHeaders?: string[] | undefined | ||
| yes?: boolean | undefined | ||
| silent?: boolean | undefined | ||
| interactive?: boolean | undefined | ||
| onResults?: (results: CheckResult[]) => void | ||
| }, | ||
| ) => Promise<CheckResult[]> |
There was a problem hiding this comment.
Low (exposure unconfirmed): validateStream reports custom payment validators as failed without CLI display label
The PR lets library callers pass their own PaymentValidator, but validateStream still derives the payment event's succeeded flag from a passing check labelled exactly 'Payment: successful'. Only the CLI validator emits that undocumented label, so a custom validator returning all-passing checks yields succeeded: false.
Valid? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 09e96d2. A PaymentValidator can now return { results, succeeded }, and validateStream uses that flag directly. A plain array still counts as succeeded only with a passing paymentSuccessLabel check, and that label is now exported. Tests in src/cli/validate.test.ts cover both forms.
| const specifier = | ||
| /(?:import|export)(\s+type)?[^'"]*?from\s+['"](\.[^'"]+)['"]|import\(\s*['"](\.[^'"]+)['"]\s*\)/g |
There was a problem hiding this comment.
Informational: Layering test regex misses side-effect and comment-quoted runtime imports
The new layering test finds imports with a regex that requires a from clause or a literal import() call. A side-effect import, or a binding import with a quote character before from, never matches, so violations() returns no entry for a forbidden validation-to-CLI edge and the test passes.
Valid? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 09e96d2. The layering test now strips comments first, then matches side-effect imports, dynamic import() calls and binding lists that contain quotes. Type-only imports are still skipped. A new test covers each kind.
…yering test (1/2) Cyclops review of ece7ab0: - A custom payment validator decided success only through the CLI's "Payment: successful" label. Validators can now return { results, succeeded }; a plain array keeps the label rule, exported as paymentSuccessLabel. - The layering test missed side-effect imports, dynamic import(), and binding lists that contain quotes. It now strips comments and matches all three, with a test for each.
…yering test (2/2)
| function violations() { | ||
| const found: string[] = [] | ||
| for (const file of sourceFiles(src)) { | ||
| const relative = path.relative(src, file).split(path.sep).join('/') | ||
| if (allowed.has(relative)) continue | ||
| const layer = layerOf(file) | ||
| const rules = forbidden[layer] | ||
| if (!rules) continue | ||
| for (const specifier of runtimeImports(fs.readFileSync(file, 'utf8'))) { | ||
| const target = path.resolve(path.dirname(file), specifier) | ||
| if (!target.startsWith(src + path.sep)) continue | ||
| const targetLayer = layerOf(target) | ||
| if (rules.includes(targetLayer)) found.push(`${relative} (${layer}) imports ${targetLayer}`) | ||
| } |
There was a problem hiding this comment.
Informational: Layering test misses imports routed through composing entry points
The new layering test treats root entry points such as index.ts and bin.ts as core. A constrained module that imports them is never flagged, even though they pull in EVM, x402 or the CLI. As a result, the guard cannot catch a validation-to-CLI edge that goes through bin.ts, which is exactly what it says it prevents.
Valid? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in 343d4b3. The composing entry points (index.ts, bin.ts and the client/server barrels) are now their own top layer, and every constrained layer is forbidden from importing it. Adding an import of ../bin.js to validation/core.ts now fails the test with "validation/core.ts (validation) imports entry". A new test pins the layer mapping.
| const paymentResults = Array.isArray(validation) ? validation : validation.results | ||
| const succeeded = Array.isArray(validation) | ||
| ? validation.some((r) => r.severity === 'pass' && r.label === paymentSuccessLabel) | ||
| : validation.succeeded |
There was a problem hiding this comment.
Medium: validate() batch result drops a payment validator's explicit succeeded flag
This PR lets a PaymentValidator return {results, succeeded}, so the outcome no longer has to appear in the checks. validateStream keeps that flag, but validate() saves only the checks for each endpoint and builds the summary from check severities. A validator that reports succeeded false with no failing checks gives the same batch result as a successful payment.
Valid? React with 👍 / 👎.
There was a problem hiding this comment.
Fixed in a944c6e. validate() now stores the flag as paymentSucceeded on each endpoint. When a validator returns succeeded: false without a failing check, validateStream adds a "Payment: failed" check, so the stream, the batch result and its summary all count the failure. A new test in src/cli/validate.test.ts covers both outcomes through validate().
Root entry points such as index.ts and bin.ts compose higher layers. The layering test now treats them as their own top layer, so a lower module that imports one of them (for example validation importing bin.ts) fails the test.
…e() (1/2) validate() now keeps the flag a payment validator returns as paymentSucceeded on each endpoint. When a validator reports succeeded: false without a failing check, validateStream adds a "Payment: failed" check, so the stream, the batch result and its summary all count the failure.
| // A validator that reports failure without a failing check still fails the run. | ||
| if ( | ||
| !Array.isArray(validation) && | ||
| !succeeded && | ||
| !paymentResults.some((r) => r.severity === 'fail') | ||
| ) | ||
| paymentResults = [ | ||
| ...paymentResults, | ||
| fail( | ||
| 'Payment: failed', | ||
| 'the payment validator reported that the payment did not succeed', | ||
| ), | ||
| ] |
There was a problem hiding this comment.
Low (trigger unconfirmed) · unverified: Synthesized 'Payment: failed' check is not forwarded to onPaymentResults
Mechanism: when a custom PaymentValidator returns {results, succeeded:false} with no failing check, validateStream (src/validation/core.ts:224-236) appends fail('Payment: failed', ...) to the yielded event's results. It never calls options.onPaymentResults with that check.
Full finding
Mechanism: when a custom PaymentValidator returns {results, succeeded:false} with no failing check, validateStream (src/validation/core.ts:224-236) appends fail('Payment: failed', ...) to the yielded event's results. It never calls options.onPaymentResults with that check. The sibling branch that synthesizes a result for a missing validator does forward it (core.ts:207, onResults?.(results)), which shows the core is responsible for forwarding its own synthesized results to the streaming callback. Trigger: a library caller uses validateStream with onPaymentResults and a validator that returns the object form with succeeded:false. Impact: streaming consumers that follow the reference CLI pattern, counting and printing payment checks only through onPaymentResults (src/cli/validate/index.ts:84, 125-127), never see the failure. Their failure tally and output show a failed payment with zero failing checks, which contradicts the comment's promise that the run 'still fails'. Batch validate() and consumers that read event.results do see it. Preconditions: the shipped CLI is unaffected because validatePaymentFlow returns CheckResult[] (payment.ts:178-192). The defect needs an object-returning custom validator together with onPaymentResults. Remediation: call options.onPaymentResults?.([failCheck]) when appending the synthesized check, mirroring the no-validator branch. Alternatively, document that onPaymentResults only carries validator-emitted checks and that consumers must also read event.results.
Valid? React with 👍 / 👎.
| /** Removes comments so imports quoted in them are not counted (and cannot hide real ones). */ | ||
| function stripComments(code: string) { | ||
| return code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"\\])\/\/.*$/gm, '$1') | ||
| } | ||
|
|
||
| /** Relative module specifiers that create runtime edges. Type-only imports are erased at build time. */ | ||
| function runtimeImports(code: string) { | ||
| const found: string[] = [] | ||
| for (const match of stripComments(code).matchAll(specifier)) { |
There was a problem hiding this comment.
Informational · unverified: Comment stripping can erase live imports from the layering check
The new stripComments pass treats any /* through the next */ as a comment, even when both delimiters are inside ordinary string literals. For example, in a scanned validation source file, put const opening = '/*' before import { validatePaymentFlow } from '../cli/validate/payment.js' and const closing = '*/' after it.
Full finding
The new stripComments pass treats any /* through the next */ as a comment, even when both delimiters are inside ordinary string literals. For example, in a scanned validation source file, put const opening = '/*' before import { validatePaymentFlow } from '../cli/validate/payment.js' and const closing = '*/' after it. The import is valid and remains live in TypeScript, but the exact regexes report its specifier before stripping and return no specifier after stripping. The forbidden validation-to-CLI rule is therefore never applied. This requires a source change, not a remote payment request. If such an import ships and is retained in the validation build, its CLI account dependency can make the public validation entry fail to load on installations without incur. No such shipped edge was demonstrated. Replace the source-text stripping and matching with TypeScript-aware syntax parsing, and add a regression fixture with a real import between string literals containing the comment delimiters.
Valid? React with 👍 / 👎.
| function violations() { | ||
| const found: string[] = [] | ||
| for (const file of sourceFiles(src)) { | ||
| const relative = path.relative(src, file).split(path.sep).join('/') | ||
| if (allowed.has(relative)) continue | ||
| const layer = layerOf(file) | ||
| const rules = forbidden[layer] | ||
| if (!rules) continue | ||
| for (const specifier of runtimeImports(fs.readFileSync(file, 'utf8'))) { | ||
| const target = path.resolve(path.dirname(file), specifier) | ||
| if (!target.startsWith(src + path.sep)) continue | ||
| const targetLayer = layerOf(target) | ||
| if (rules.includes(targetLayer)) found.push(`${relative} (${layer}) imports ${targetLayer}`) | ||
| } | ||
| } | ||
| return found | ||
| } |
There was a problem hiding this comment.
Informational: Layering test skips unclassified layers, missing transitive validation-to-CLI imports
The new layering test checks only direct imports and skips every file whose top-level directory has no rule, without reading it. src/validation/core.ts imports src/discovery/Validate.ts at runtime, and discovery has no rule, so a CLI import added there passes the test. The head tree contains no such edge. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const methods = ['tempo', 'stripe', 'evm', 'x402', 'integrations'] | ||
| const adapters = ['cli', 'middlewares', 'proxy', 'mcp', 'validation', 'extensions'] | ||
|
|
||
| const forbidden: Record<string, readonly string[]> = { | ||
| core: ['client', 'server', ...methods, ...adapters, 'entry'], | ||
| internal: ['client', 'server', ...methods, ...adapters, 'entry'], | ||
| client: [...methods, ...adapters, 'entry'], | ||
| server: [...methods, ...adapters, 'entry'], | ||
| validation: ['cli', 'entry'], | ||
| } |
There was a problem hiding this comment.
Informational · unverified: Layering guard leaves cloudflare and viem unclassified although they import the tempo…
Mechanism: src/layering.test.ts is meant to keep core, internal, client and server free of methods, adapters and entry points. This push added the 'entry' class for composing entry points. However, the forbidden map (lines 20-29) lists method and adapter directories by name. src/cloudflare and src/viem are in neither list, and layerOf (lines 62-66) gives them their own directory names as layers.
Full finding
Layering guard leaves cloudflare and viem unclassified although they import the tempo method layer
Mechanism: src/layering.test.ts is meant to keep core, internal, client and server free of methods, adapters and entry points. This push added the 'entry' class for composing entry points. However, the forbidden map (lines 20-29) lists method and adapter directories by name. src/cloudflare and src/viem are in neither list, and layerOf (lines 62-66) gives them their own directory names as layers. Both directories import the tempo method layer at runtime: src/cloudflare/Channels.ts:6-15 imports tempo/internal/proof.js, tempo/session/precompile/Protocol.js and tempo/session/server/CloseSupervisor.js, and src/viem/Client.ts:6 imports tempo/internal/remote-fee-payer.js. Trigger: a core, internal, client, server or validation module adds import ... from '../viem/Client.js' or '../cloudflare/index.js'. The edge has target layer 'viem' or 'cloudflare', which is in no forbidden list, so violations() returns nothing and the test passes. The lower layer still pulls the tempo method in at runtime. Impact: the guard misses the cross-layer dependency it exists to catch. For example, mppx/server or mppx/client could start bundling tempo session and precompile code, or the validation entry could pick up method dependencies, with no failing test. This is the same gap the entry-layer fix closed for index.ts and bin.ts, here in a sibling population. Evidence: E1-E5. Preconditions: a future edit adds such an import. A repository-wide grep found no current core, internal, client, server or validation import of viem/ or cloudflare/, so nothing is violated today. Remediation: classify every top-level directory under src/ explicitly, with cloudflare and viem at the method level (add them to methods) and discovery and identity at their intended level. Also make the test fail when layerOf returns a directory missing from the classification, so new directories cannot go unchecked.
First reported at 343d4b3; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const specifier = | ||
| /\bimport\s*['"]([^'"]+)['"]|\b(?:import|export)\b(\s+type\b)?(?:[^;'"=()]|'[^']*'|"[^"]*")*?\bfrom\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g |
There was a problem hiding this comment.
Informational: Layering check reports erased import type queries as runtime imports
The layering test added in this PR skips import type declarations as erased, but its dynamic-import pattern also matches inline import types such as typeof import('../cli/config.js'). Those emit no JavaScript, yet violations() reports them as forbidden runtime edges. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| function runtimeImports(code: string) { | ||
| const found: string[] = [] | ||
| for (const match of stripComments(code).matchAll(specifier)) { | ||
| if (match[2]) continue | ||
| const target = match[1] ?? match[3] ?? match[4]! | ||
| if (target.startsWith('.')) found.push(target) | ||
| } | ||
| return found | ||
| } |
There was a problem hiding this comment.
Informational: Layering test ignores package self-reference imports of forbidden layers
The new layering test only inspects dot-prefixed import specifiers. A value import of the CLI layer through the package's own export name, such as 'mppx/cli' or 'mppx/cli/plugins', from src/validation is never classified, so the test passes on a tree it is meant to reject. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const specifier = | ||
| /\bimport\s*['"]([^'"]+)['"]|\b(?:import|export)\b(\s+type\b)?(?:[^;'"=()]|'[^']*'|"[^"]*")*?\bfrom\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g | ||
|
|
||
| /** Removes comments so imports quoted in them are not counted (and cannot hide real ones). */ | ||
| function stripComments(code: string) { | ||
| return code.replace(/\/\*[\s\S]*?\*\//g, '').replace(/(^|[^:'"\\])\/\/.*$/gm, '$1') | ||
| } |
There was a problem hiding this comment.
Informational: Layering test reports imports inside comments and strings as violations
The new layering test matches import specifiers against raw file text, so import-like text in a comment, JSDoc example, string or template literal counts as a dependency. A ruled-layer file that only mentions a forbidden layer's relative path this way fails the test without importing anything. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const specifier = | ||
| /\bimport\s*['"]([^'"]+)['"]|\b(?:import|export)\b(\s+type\b)?(?:[^;'"=()]|'[^']*'|"[^"]*")*?\bfrom\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g |
There was a problem hiding this comment.
Informational: Layering test regex scans quote-free source in quadratic time
The specifier regex that violations() runs over every eligible source file restarts a lazy scan to the next quote from each import or export token. A quote-free file with many such tokens costs quadratic time: 458,769 bytes took 5.2 s, against 0.13 ms for same-size text without tokens. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const specifier = | ||
| /\bimport\s*['"]([^'"]+)['"]|\b(?:import|export)\b(\s+type\b)?(?:[^;'"=()]|'[^']*'|"[^"]*")*?\bfrom\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g |
There was a problem hiding this comment.
Informational: Layering guard misses imports whose specifier uses string escapes
The layering test extracts import specifiers with a regex and resolves the raw quoted text without decoding string escapes. An import written '../\u0063li/validate/payment.js' loads ../cli/validate/payment.js at runtime, but the guard computes the layer '\u0063li' and reports nothing. No file at the pinned commit uses such a spelling.
Full finding
The layering test extracts import specifiers with a regex and resolves the raw quoted text without decoding string escapes. An import written '../\u0063li/validate/payment.js' loads ../cli/validate/payment.js at runtime, but the guard computes the layer '\u0063li' and reports nothing. No file at the pinned commit uses such a spelling.
First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| function* sourceFiles(dir: string): Generator<string> { | ||
| for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { | ||
| const file = path.join(dir, entry.name) | ||
| if (entry.isDirectory()) yield* sourceFiles(file) | ||
| else if (/\.tsx?$/.test(entry.name) && !/\.(test|test-d|gen)\.tsx?$/.test(entry.name)) | ||
| yield file | ||
| } | ||
| } |
There was a problem hiding this comment.
Informational: Layering test follows symlinks under src and can fail or hang
The walker in src/layering.test.ts yields every non-directory entry ending in .ts or .tsx, including symbolic links, and violations() opens each with readFileSync. A link under a checked layer makes the test parse a file outside src, throw ENOENT when the link dangles, or block when the target never returns EOF. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const forbidden: Record<string, readonly string[]> = { | ||
| core: ['client', 'server', ...methods, ...adapters, 'entry'], | ||
| internal: ['client', 'server', ...methods, ...adapters, 'entry'], | ||
| client: [...methods, ...adapters, 'entry'], | ||
| server: [...methods, ...adapters, 'entry'], | ||
| validation: ['cli', 'entry'], | ||
| } |
There was a problem hiding this comment.
Informational: Layering test throws TypeError for directories named like Object properties
The layering test looks up each source layer in a plain object and checks only truthiness. A top-level src directory named constructor, __proto__ or toString resolves to an inherited Object.prototype member, so the test throws instead of skipping the unlisted layer. First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
| const specifier = | ||
| /\bimport\s*['"]([^'"]+)['"]|\b(?:import|export)\b(\s+type\b)?(?:[^;'"=()]|'[^']*'|"[^"]*")*?\bfrom\s*['"]([^'"]+)['"]|\bimport\(\s*['"]([^'"]+)['"]\s*\)/g |
There was a problem hiding this comment.
Informational: Layering test misses template-literal and two-argument dynamic imports
The new layering test finds dynamic imports with a regex that requires import(, one quoted relative string and a closing parenthesis. A forbidden import written with a no-substitution template literal or a second options argument produces no match, so violations() returns nothing for it and the test passes. No file at the pinned commit uses a missed spelling.
Full finding
The new layering test finds dynamic imports with a regex that requires import(, one quoted relative string and a closing parenthesis. A forbidden import written with a no-substitution template literal or a second options argument produces no match, so violations() returns nothing for it and the test passes. No file at the pinned commit uses a missed spelling.
First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
|
Low (exposure unconfirmed): Standalone validation suggestions promise wallet provisioning without a payment validator validate() from mppx/validation now skips the payment phase when no payment validator is supplied, but computeSuggestions still tells mainnet-only callers to validate testnet because "Tempo wallets are automatically provisioned". Provisioning exists only in the CLI's injected validator, so following the suggestion through the same API yields another skipped payment check. First reported at ece7ab0; recheck at this head: still present. Valid? React with 👍 / 👎. |
| function* sourceFiles(dir: string): Generator<string> { | ||
| for (const entry of fs.readdirSync(dir, { withFileTypes: true })) { | ||
| const file = path.join(dir, entry.name) | ||
| if (entry.isDirectory()) yield* sourceFiles(file) | ||
| else if (/\.tsx?$/.test(entry.name) && !/\.(test|test-d|gen)\.tsx?$/.test(entry.name)) | ||
| yield file | ||
| } | ||
| } |
There was a problem hiding this comment.
Informational: Layering test skips imports in .mts source modules
The new layering guard walks src with a filter that accepts only .ts and .tsx names, so a .mts module is never scanned. A forbidden runtime import placed in such a file, for example validation importing cli, does not fail the test. No .mts file exists at this commit.
Full finding
The new layering guard walks src with a filter that accepts only .ts and .tsx names, so a .mts module is never scanned. A forbidden runtime import placed in such a file, for example validation importing cli, does not fail the test. No .mts file exists at this commit.
First reported at ece7ab0; recheck at this head: still present.
Valid? React with 👍 / 👎.
What
Makes module imports point one way, from low-level modules up to the CLI:
A new
src/layering.test.tsenforces this order:core,internal,clientandservermay not import methods, adapters or the CLI, andvalidationmay not import the CLI. Entry points and barrels (index.ts,bin.ts,client/*,server/*,Methods.ts,client/node.ts) are allowlisted. Type-only imports are ignored.Fix:
mppx/validationloads againsrc/validation/core.tsimportedvalidatePaymentFlowfromsrc/cli/validate/payment.ts, which pulls in the CLI's account and config code andincur.incuris bundled intodist/bin.jsand isn't a runtime dependency, so in a clean install of 0.21.1,import('mppx/validation')throwsCannot find package 'incur'.challenge,discovery,helpers,messages) move fromsrc/cli/validatetosrc/validation.src/cli/validate/print.ts. Thepccolors move tosrc/internal/pc.ts, andcli/utilsstill re-exportspc.validate()andvalidateStream()take an optionalpayment: PaymentValidator, andmppx validatepasses the CLI's. Without one, the payment phase reports a skipped check instead of paying.Moves (no behavior change)
server/internal/html/*internal/html/*Html.tsandMethod.ts(core) imported server internalsserver/internal/challengeMeta.tsinternal/challengeMeta.tsx402/{Header,Siwx,Types}.ts,x402/internal/ChallengeBrand.tsinternal/x402/*internal/AcceptPaymentandserver/Mppximportedx402/mcp/internal/Credential.tsinternal/McpCredential.tsserver/Transportmcp/server/Transport.tsserver/internal/mcpSdk.tsserver/Transport⇄mcp/server/Transportwas a cyclemppx/x402,mppx/mcp-sdk/serverand every other export resolve to the same API.mcp/server/Transport.tsremains as a re-export.Checks
pnpm build,pnpm check:types,pnpm check:ciandpnpm check:packagepass.vp test --project node --project cliagainst a Tempo localnet: 4531 passed. The two failures are insrc/cli/mcp.test.ts(Linux keyring…text where JSON was expected). They fail the same way onmainon this machine, which has no keyring.import('mppx/validation')loads andvalidate({ skipPayment: true })runs.mppx,mppx/client,mppx/server,mppx/x402andmppx/mcp-sdk/serverimport, andmppx validate --helpruns.The branch has 27 signed commits because the commit API takes a limited payload per call. Squash merge makes them one commit.