@botiverse/porthole 0.5.1 → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +41 -0
- package/dist/bridge/bridge.d.ts +13 -0
- package/dist/bridge/bridge.js +208 -13
- package/dist/bridge/navigation.d.ts +1 -6
- package/dist/bridge/navigation.js +11 -0
- package/dist/bridge/refusal.d.ts +5 -1
- package/dist/bridge/refusal.js +16 -0
- package/dist/bridge/types.d.ts +41 -4
- package/dist/check/check.d.ts +19 -3
- package/dist/check/check.js +55 -8
- package/dist/check/files.d.ts +26 -0
- package/dist/check/files.js +307 -0
- package/dist/check/instrument.d.ts +3 -0
- package/dist/check/lint.js +31 -12
- package/dist/check/page-source.js +1 -1
- package/dist/check/page.js +14 -0
- package/dist/check/tools.d.ts +23 -0
- package/dist/check/tools.js +27 -3
- package/dist/compile/policy.d.ts +34 -0
- package/dist/compile/policy.js +74 -0
- package/dist/config/capabilities.d.ts +62 -3
- package/dist/config/capabilities.js +20 -0
- package/dist/config/schema.d.ts +32 -0
- package/dist/config/validate.d.ts +1 -1
- package/dist/config/validate.js +74 -5
- package/dist/conformance/harness-source.js +1 -1
- package/dist/conformance/index.d.ts +1 -0
- package/dist/conformance/index.js +2 -0
- package/dist/conformance/runtime.d.ts +58 -0
- package/dist/conformance/runtime.js +314 -0
- package/dist/files/paths.d.ts +99 -0
- package/dist/files/paths.js +263 -0
- package/dist/files/types.d.ts +24 -0
- package/dist/files/types.js +83 -0
- package/dist/guide/gates.d.ts +3 -0
- package/dist/guide/gates.js +19 -0
- package/dist/guide/guide.d.ts +2 -0
- package/dist/guide/guide.js +44 -32
- package/dist/guide/limits.js +4 -4
- package/dist/guide/runtime.d.ts +13 -0
- package/dist/guide/runtime.js +202 -0
- package/dist/host/create-host.js +45 -0
- package/dist/host/locate.js +8 -0
- package/dist/host/locator.js +7 -0
- package/dist/host/types.d.ts +18 -0
- package/dist/index.d.ts +13 -4
- package/dist/index.js +16 -3
- package/dist/isolation/types.d.ts +8 -0
- package/dist/presets/presets.d.ts +6 -0
- package/dist/presets/presets.js +1 -0
- package/dist/protocol/adapter.d.ts +4 -0
- package/dist/protocol/mcp-apps.d.ts +6 -0
- package/dist/protocol/mcp-apps.js +6 -0
- package/dist/protocol/runtime-calls.d.ts +28 -0
- package/dist/protocol/runtime-calls.js +113 -0
- package/dist/protocol/shell-adapter.js +52 -3
- package/dist/react/dialog.js +31 -0
- package/dist/react/frame.d.ts +13 -0
- package/dist/react/frame.js +6 -0
- package/dist/runtime/contract.d.ts +193 -0
- package/dist/runtime/contract.js +216 -0
- package/dist/runtime/db.d.ts +153 -0
- package/dist/runtime/db.js +398 -0
- package/dist/runtime/declaration.d.ts +86 -0
- package/dist/runtime/declaration.js +266 -0
- package/dist/runtime/levels.d.ts +33 -0
- package/dist/runtime/levels.js +41 -0
- package/dist/runtime/requests.d.ts +125 -0
- package/dist/runtime/requests.js +199 -0
- package/dist/runtime/segments.d.ts +8 -0
- package/dist/runtime/segments.js +14 -0
- package/dist/runtime/types.generated.d.ts +1 -0
- package/dist/runtime/types.generated.js +19 -0
- package/dist/server/files.d.ts +57 -0
- package/dist/server/files.js +338 -0
- package/dist/server/host.d.ts +44 -2
- package/dist/server/host.js +42 -2
- package/dist/server/index.d.ts +5 -2
- package/dist/server/index.js +5 -1
- package/dist/server/keys.d.ts +8 -0
- package/dist/server/keys.js +34 -0
- package/dist/server/pseudonym.d.ts +9 -0
- package/dist/server/pseudonym.js +20 -0
- package/dist/server/server.d.ts +0 -5
- package/dist/server/server.js +468 -24
- package/dist/server/types.d.ts +118 -5
- package/dist/shell/document.d.ts +27 -0
- package/dist/shell/document.js +46 -2
- package/dist/shell/legacy.d.ts +21 -0
- package/dist/shell/legacy.js +63 -0
- package/dist/shell/plan.d.ts +17 -1
- package/dist/shell/plan.js +13 -2
- package/dist/shell/runtime.d.ts +2 -1
- package/dist/shell/runtime.js +114 -46
- package/dist/shell/use.d.ts +15 -0
- package/dist/shell/use.js +235 -0
- package/docs/ADOPTING.md +142 -5
- package/docs/ARCHITECTURE.md +34 -5
- package/docs/DECISIONS.md +716 -7
- package/docs/DESIGN.md +97 -3
- package/package.json +3 -1
- package/src/bridge/bridge.ts +281 -17
- package/src/bridge/navigation.ts +12 -0
- package/src/bridge/refusal.ts +16 -0
- package/src/bridge/types.ts +46 -4
- package/src/check/check.ts +100 -14
- package/src/check/files.ts +384 -0
- package/src/check/instrument.ts +3 -0
- package/src/check/lint.ts +33 -12
- package/src/check/page.ts +14 -0
- package/src/check/tools.ts +52 -3
- package/src/compile/policy.ts +92 -0
- package/src/config/capabilities.ts +49 -2
- package/src/config/schema.ts +32 -0
- package/src/config/validate.ts +107 -5
- package/src/conformance/index.ts +7 -0
- package/src/conformance/runtime.ts +573 -0
- package/src/files/paths.ts +323 -0
- package/src/files/types.ts +101 -0
- package/src/guide/gates.ts +25 -0
- package/src/guide/guide.ts +78 -52
- package/src/guide/limits.ts +4 -4
- package/src/guide/runtime.ts +244 -0
- package/src/host/create-host.ts +55 -0
- package/src/host/locate.ts +10 -0
- package/src/host/locator.ts +11 -0
- package/src/host/types.ts +18 -0
- package/src/index.ts +121 -0
- package/src/isolation/types.ts +8 -0
- package/src/presets/presets.ts +7 -0
- package/src/protocol/adapter.ts +3 -1
- package/src/protocol/mcp-apps.ts +7 -0
- package/src/protocol/runtime-calls.ts +138 -0
- package/src/protocol/shell-adapter.ts +56 -2
- package/src/react/dialog.tsx +33 -0
- package/src/react/frame.tsx +19 -0
- package/src/runtime/contract.ts +305 -0
- package/src/runtime/db.ts +530 -0
- package/src/runtime/declaration.ts +378 -0
- package/src/runtime/levels.ts +69 -0
- package/src/runtime/requests.ts +339 -0
- package/src/runtime/segments.ts +17 -0
- package/src/runtime/types.generated.ts +19 -0
- package/src/server/files.ts +425 -0
- package/src/server/host.ts +84 -3
- package/src/server/index.ts +22 -0
- package/src/server/keys.ts +53 -0
- package/src/server/pseudonym.ts +21 -0
- package/src/server/server.ts +565 -26
- package/src/server/types.ts +124 -4
- package/src/shell/document.ts +74 -4
- package/src/shell/legacy.ts +64 -0
- package/src/shell/plan.ts +37 -3
- package/src/shell/runtime.ts +114 -46
- package/src/shell/use.ts +235 -0
- package/types/runtime/v1/artifact.d.ts +50 -0
- package/types/runtime/v1/assets.d.ts +43 -0
- package/types/runtime/v1/chat.d.ts +13 -0
- package/types/runtime/v1/clipboard.d.ts +14 -0
- package/types/runtime/v1/comments.d.ts +24 -0
- package/types/runtime/v1/context.d.ts +16 -0
- package/types/runtime/v1/data.d.ts +29 -0
- package/types/runtime/v1/db.d.ts +110 -0
- package/types/runtime/v1/downloads.d.ts +22 -0
- package/types/runtime/v1/links.d.ts +13 -0
- package/types/runtime/v1/porthole.d.ts +44 -0
- package/types/runtime/v1/user.d.ts +19 -0
package/src/bridge/types.ts
CHANGED
|
@@ -5,6 +5,9 @@ import type {
|
|
|
5
5
|
HandledCapability,
|
|
6
6
|
} from "../config/capabilities.ts";
|
|
7
7
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
8
|
+
import type { RuntimeCapabilityName } from "../runtime/contract.ts";
|
|
9
|
+
import type { DeclaredData, DeclaredDb } from "../runtime/declaration.ts";
|
|
10
|
+
import type { ViewerInfo } from "../runtime/levels.ts";
|
|
8
11
|
import type { RefusalReason } from "./refusal.ts";
|
|
9
12
|
|
|
10
13
|
/**
|
|
@@ -20,16 +23,33 @@ export interface CallContext {
|
|
|
20
23
|
/** The display's title, as the host gave it (never the content's words). */
|
|
21
24
|
readonly title: string;
|
|
22
25
|
readonly capability: CapabilityName;
|
|
26
|
+
/** The instance the host gave the display (which artifact, which version), if any. */
|
|
27
|
+
readonly instance?: InstanceRef;
|
|
28
|
+
/**
|
|
29
|
+
* Who is viewing, as the host said (P087): the bridge already checked the method's level
|
|
30
|
+
* against it. A host's own API checks again: it is its data's wall.
|
|
31
|
+
*/
|
|
32
|
+
readonly viewer?: ViewerInfo;
|
|
33
|
+
/**
|
|
34
|
+
* The page's declaration for this capability (P086): its levels, `data`'s resources and tools,
|
|
35
|
+
* `db`'s rules (the fields of the one it is).
|
|
36
|
+
*/
|
|
37
|
+
readonly declared?: DeclaredData & DeclaredDb;
|
|
23
38
|
}
|
|
24
39
|
|
|
25
40
|
export type CapabilityHandler<N extends CapabilityName> = (
|
|
26
41
|
args: CapabilityArgs[N],
|
|
27
|
-
context: N extends "subscribeData"
|
|
42
|
+
context: N extends "subscribeData"
|
|
43
|
+
? SubscriptionContext
|
|
44
|
+
: N extends "db"
|
|
45
|
+
? DbContext
|
|
46
|
+
: CallContext,
|
|
28
47
|
) => CapabilityResults[N] | Promise<CapabilityResults[N]>;
|
|
29
48
|
|
|
30
49
|
/**
|
|
31
|
-
* A subscription's context (`subscribeData`, P079): how the host tells the
|
|
32
|
-
* changed, and when to stop.
|
|
50
|
+
* A subscription's context (`subscribeData`, P079; a `db` watch, P088): how the host tells the
|
|
51
|
+
* content its resource changed, and when to stop. A `db` watch's `changed` takes the new state
|
|
52
|
+
* (a snapshot, or a collection's `{ docs }`), which goes to the content as it is.
|
|
33
53
|
*/
|
|
34
54
|
export interface SubscriptionContext extends CallContext {
|
|
35
55
|
/**
|
|
@@ -42,6 +62,9 @@ export interface SubscriptionContext extends CallContext {
|
|
|
42
62
|
readonly signal: AbortSignal;
|
|
43
63
|
}
|
|
44
64
|
|
|
65
|
+
/** A `db` call's context: a watch's (`op: "watch"`) carries its channel back and its end. */
|
|
66
|
+
export type DbContext = CallContext & Partial<Pick<SubscriptionContext, "changed" | "signal">>;
|
|
67
|
+
|
|
45
68
|
/** The host's handlers: one for each declared capability served by a handler. */
|
|
46
69
|
export type CapabilityHandlers = { readonly [N in HandledCapability]?: CapabilityHandler<N> };
|
|
47
70
|
|
|
@@ -125,7 +148,20 @@ export type Refusal =
|
|
|
125
148
|
| "denied"
|
|
126
149
|
| "rate-limited"
|
|
127
150
|
/** The host's handler threw or rejected. */
|
|
128
|
-
| "failed"
|
|
151
|
+
| "failed"
|
|
152
|
+
/**
|
|
153
|
+
* The display's page declared capabilities and not this one (P086): a built-in needs none, any
|
|
154
|
+
* other is reachable only by a page that declared it (and only the resources and tools it named).
|
|
155
|
+
*/
|
|
156
|
+
| "undeclared"
|
|
157
|
+
/**
|
|
158
|
+
* The viewer's level doesn't reach the method's (P087), or the call reaches data that isn't
|
|
159
|
+
* theirs (another person's `data/users/<id>`); or the host gave the display no viewer, which a
|
|
160
|
+
* runtime capability needs.
|
|
161
|
+
*/
|
|
162
|
+
| "level"
|
|
163
|
+
/** Past a limit: a document, a batch, an upload, a publish (P088). */
|
|
164
|
+
| "too-large";
|
|
129
165
|
|
|
130
166
|
export type CallOutcome<T> =
|
|
131
167
|
/** `stale`: a `readData` answered from the host's cache (`DataCache`). */
|
|
@@ -157,4 +193,10 @@ export interface HostFunctionBridge {
|
|
|
157
193
|
options?: CallOptions,
|
|
158
194
|
): Promise<CallOutcome<CapabilityResults[N]>>;
|
|
159
195
|
declared(capability: CapabilityName): boolean;
|
|
196
|
+
/**
|
|
197
|
+
* What the runtime offers this display (P085): each runtime capability it may `use`, with its
|
|
198
|
+
* methods. Empty without `config.runtime`. The same whatever the viewer's level: levels refuse
|
|
199
|
+
* at call time.
|
|
200
|
+
*/
|
|
201
|
+
roster(): Readonly<Partial<Record<RuntimeCapabilityName, readonly string[]>>>;
|
|
160
202
|
}
|
package/src/check/check.ts
CHANGED
|
@@ -1,9 +1,14 @@
|
|
|
1
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
1
2
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
3
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
4
|
import { presets } from "../presets/presets.ts";
|
|
4
5
|
import { createServer } from "../server/server.ts";
|
|
5
6
|
import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.ts";
|
|
6
|
-
import { lintContent
|
|
7
|
+
import { lintContent } from "./lint.ts";
|
|
8
|
+
import { lintFiles, whereOf, type FileContents, type FileFinding } from "./files.ts";
|
|
9
|
+
import { DEFAULT_ENTRY, servesFiles } from "../files/paths.ts";
|
|
10
|
+
import { sha256 } from "../server/crypto.ts";
|
|
11
|
+
import type { StoredFiles } from "../server/types.ts";
|
|
7
12
|
// The check page's script, imported as a module so a bundler takes it in (P075): no file is
|
|
8
13
|
// looked up beside this one at run time.
|
|
9
14
|
import PAGE_SCRIPT from "./page-source.ts";
|
|
@@ -55,7 +60,21 @@ export interface CheckDriver {
|
|
|
55
60
|
export interface CheckOptions {
|
|
56
61
|
readonly config: PortholeConfig;
|
|
57
62
|
/** The content as the agent would send it: a fragment, or a whole document. */
|
|
58
|
-
readonly content
|
|
63
|
+
readonly content?: string;
|
|
64
|
+
/**
|
|
65
|
+
* A page that comes with files (P081), in place of `content`: every file by its path. The whole
|
|
66
|
+
* set is served, as people's browsers get it, and its entry is run and measured. Needs a served
|
|
67
|
+
* artifact config and a driver that serves (`playwrightDriver`).
|
|
68
|
+
*/
|
|
69
|
+
readonly files?: FileContents;
|
|
70
|
+
/** The page a set opens at (default `index.html`). */
|
|
71
|
+
readonly entry?: string;
|
|
72
|
+
/**
|
|
73
|
+
* Under a runtime (P085): what the page declares (default null: a page with none, so a
|
|
74
|
+
* declared capability is null in the check, as in a preview). Its calls are answered as a
|
|
75
|
+
* declining host answers, by a view-level viewer.
|
|
76
|
+
*/
|
|
77
|
+
readonly declaration?: PageDeclaration | null;
|
|
59
78
|
readonly driver: CheckDriver;
|
|
60
79
|
/** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
|
|
61
80
|
readonly widths?: readonly number[];
|
|
@@ -106,7 +125,8 @@ export interface CheckReport {
|
|
|
106
125
|
* refuses, overflow or cut, no lint error.
|
|
107
126
|
*/
|
|
108
127
|
readonly ok: boolean;
|
|
109
|
-
|
|
128
|
+
/** What the lint found (for a page with files, each finding names its file, `path`). */
|
|
129
|
+
readonly lint: readonly FileFinding[];
|
|
110
130
|
readonly runs: readonly CheckRun[];
|
|
111
131
|
/** One short summary for the agent: each problem once, with where it happened. */
|
|
112
132
|
readonly text: string;
|
|
@@ -130,9 +150,53 @@ function checkedAs(config: PortholeConfig): PortholeConfig {
|
|
|
130
150
|
|
|
131
151
|
const escapeScript = (code: string) => code.replace(/<\/script/giu, "<\\/script");
|
|
132
152
|
|
|
153
|
+
/** A set's own files named by their path, as the agent wrote them, not the frame's address. */
|
|
154
|
+
const ownPaths = (text: string): string =>
|
|
155
|
+
text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
|
|
156
|
+
|
|
157
|
+
const hex = (bytes: Uint8Array): string =>
|
|
158
|
+
Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
|
|
159
|
+
|
|
160
|
+
/** A set's files as the check's server stores them, its entry instrumented (P081). */
|
|
161
|
+
function checkedFiles(files: FileContents, entry: string, page: string): StoredFiles {
|
|
162
|
+
const bytes = (body: string | Uint8Array): Uint8Array =>
|
|
163
|
+
typeof body === "string" ? new TextEncoder().encode(body) : body;
|
|
164
|
+
const served = new Map<string, Uint8Array>(
|
|
165
|
+
Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]),
|
|
166
|
+
);
|
|
167
|
+
return {
|
|
168
|
+
files: Object.fromEntries(
|
|
169
|
+
[...served].map(([path, body]) => [
|
|
170
|
+
path,
|
|
171
|
+
{ size: body.byteLength, sha256: hex(sha256(body)) },
|
|
172
|
+
]),
|
|
173
|
+
),
|
|
174
|
+
entry,
|
|
175
|
+
read: (path) => Promise.resolve(served.get(path) ?? null),
|
|
176
|
+
};
|
|
177
|
+
}
|
|
178
|
+
|
|
133
179
|
export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
134
180
|
const { config } = options;
|
|
135
|
-
const
|
|
181
|
+
const entry = options.entry ?? DEFAULT_ENTRY;
|
|
182
|
+
const files = options.files;
|
|
183
|
+
if ((files === undefined) === (options.content === undefined)) {
|
|
184
|
+
throw new TypeError("checkPage takes content, or files: one of them");
|
|
185
|
+
}
|
|
186
|
+
if (files !== undefined && !servesFiles(config)) {
|
|
187
|
+
throw new TypeError("A page with files is checked under a served artifact config");
|
|
188
|
+
}
|
|
189
|
+
const entryText = (): string => {
|
|
190
|
+
const body = files?.[entry];
|
|
191
|
+
return body === undefined
|
|
192
|
+
? ""
|
|
193
|
+
: typeof body === "string"
|
|
194
|
+
? body
|
|
195
|
+
: new TextDecoder().decode(body);
|
|
196
|
+
};
|
|
197
|
+
const written = files === undefined ? (options.content ?? "") : entryText();
|
|
198
|
+
const lint: FileFinding[] =
|
|
199
|
+
files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
|
|
136
200
|
if (config.mode === "url") {
|
|
137
201
|
return {
|
|
138
202
|
ok: true,
|
|
@@ -149,9 +213,13 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
149
213
|
const script = options.page ?? PAGE_SCRIPT;
|
|
150
214
|
const html = `<!doctype html><html><head><meta charset="utf-8"><title>Porthole check</title><style>body{margin:0;padding:8px}section{margin-bottom:16px}</style></head><body><script>${escapeScript(script)}</script></body></html>`;
|
|
151
215
|
// Its inline scripts named, so an error says the line in the content as written (P074).
|
|
152
|
-
const { content, scriptLines } = namedScripts(
|
|
216
|
+
const { content, scriptLines } = namedScripts(written);
|
|
153
217
|
|
|
154
218
|
const session = await options.driver.open();
|
|
219
|
+
if (files !== undefined && session.serve === undefined) {
|
|
220
|
+
await session.close();
|
|
221
|
+
throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
|
|
222
|
+
}
|
|
155
223
|
// A served config runs served, on a content origin the driver answers, under Porthole's own
|
|
156
224
|
// server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
|
|
157
225
|
const servedHere =
|
|
@@ -163,7 +231,14 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
163
231
|
secret: crypto.getRandomValues(new Uint8Array(32)),
|
|
164
232
|
hostOrigins: [CHECK_ORIGIN],
|
|
165
233
|
configs: { check: servedConfig },
|
|
166
|
-
artifacts: {
|
|
234
|
+
artifacts: {
|
|
235
|
+
get: () =>
|
|
236
|
+
Promise.resolve(
|
|
237
|
+
files === undefined
|
|
238
|
+
? { html: instrumented(content) }
|
|
239
|
+
: checkedFiles(files, entry, instrumented(content)),
|
|
240
|
+
),
|
|
241
|
+
},
|
|
167
242
|
})
|
|
168
243
|
: null;
|
|
169
244
|
const handler = async (request: Request): Promise<Response> => {
|
|
@@ -209,6 +284,7 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
209
284
|
content,
|
|
210
285
|
scriptLines,
|
|
211
286
|
...(instance === undefined ? {} : { instance }),
|
|
287
|
+
...(options.declaration === undefined ? {} : { declaration: options.declaration }),
|
|
212
288
|
widthPx: width,
|
|
213
289
|
...(fills ? { heightPx: 700 } : {}),
|
|
214
290
|
scheme,
|
|
@@ -240,10 +316,19 @@ export async function checkPage(options: CheckOptions): Promise<CheckReport> {
|
|
|
240
316
|
data?.scrollWidth !== undefined &&
|
|
241
317
|
data.clientWidth !== null &&
|
|
242
318
|
data.scrollWidth > data.clientWidth + 1,
|
|
243
|
-
errors: unique(data?.errors ?? []),
|
|
244
|
-
blocked: uniqueBy(
|
|
245
|
-
|
|
246
|
-
|
|
319
|
+
errors: unique((data?.errors ?? []).map(ownPaths)),
|
|
320
|
+
blocked: uniqueBy(
|
|
321
|
+
(data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
|
|
322
|
+
(each) => `${each.url} ${each.directive}`,
|
|
323
|
+
),
|
|
324
|
+
failedLoads: uniqueBy(
|
|
325
|
+
(data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })),
|
|
326
|
+
(each) => each.url,
|
|
327
|
+
),
|
|
328
|
+
console: uniqueBy(
|
|
329
|
+
(data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })),
|
|
330
|
+
(each) => `${each.level} ${each.text}`,
|
|
331
|
+
),
|
|
247
332
|
calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
|
|
248
333
|
...(screenshot === undefined ? {} : { screenshot }),
|
|
249
334
|
});
|
|
@@ -297,7 +382,7 @@ const clip = (text: string, most = 200) =>
|
|
|
297
382
|
*/
|
|
298
383
|
function summary(
|
|
299
384
|
config: PortholeConfig,
|
|
300
|
-
lint: readonly
|
|
385
|
+
lint: readonly FileFinding[],
|
|
301
386
|
runs: readonly CheckRun[],
|
|
302
387
|
most: number,
|
|
303
388
|
): string {
|
|
@@ -348,9 +433,10 @@ function summary(
|
|
|
348
433
|
}
|
|
349
434
|
}
|
|
350
435
|
const lines = [
|
|
351
|
-
...lint.map(
|
|
352
|
-
|
|
353
|
-
`${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}
|
|
436
|
+
...lint.map((each) =>
|
|
437
|
+
each.path === undefined
|
|
438
|
+
? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
|
|
439
|
+
: `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`,
|
|
354
440
|
),
|
|
355
441
|
...[...where].map(
|
|
356
442
|
([problem, at]) =>
|
|
@@ -0,0 +1,384 @@
|
|
|
1
|
+
import type { PortholeConfig } from "../config/schema.ts";
|
|
2
|
+
import {
|
|
3
|
+
checkFileSet,
|
|
4
|
+
DEFAULT_ENTRY,
|
|
5
|
+
fileLimits,
|
|
6
|
+
lookupFile,
|
|
7
|
+
servesFiles,
|
|
8
|
+
} from "../files/paths.ts";
|
|
9
|
+
import { fileTypeOf, knownType } from "../files/types.ts";
|
|
10
|
+
import { sizeWords } from "../guide/limits.ts";
|
|
11
|
+
import { lintContent, type Finding } from "./lint.ts";
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* What can be told about a page that comes with files (P081), without running it: each page
|
|
15
|
+
* linted as a page is, the set held to the path rules and limits, and every relative reference
|
|
16
|
+
* looked up in the set. Errors are what certainly fails (`admitFiles` refuses them); the rest
|
|
17
|
+
* are warnings. Pure: any runtime.
|
|
18
|
+
*/
|
|
19
|
+
|
|
20
|
+
/** A finding about one file of the set (`path`), or about the set as a whole. */
|
|
21
|
+
export interface FileFinding extends Omit<Finding, "rule"> {
|
|
22
|
+
readonly rule: Finding["rule"] | "files" | "missing-file" | "root-path" | "file-type";
|
|
23
|
+
readonly path?: string;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/** A set's files, by path: text, or bytes. */
|
|
27
|
+
export type FileContents = Readonly<Record<string, string | Uint8Array>>;
|
|
28
|
+
|
|
29
|
+
/** A text's line numbers by offset: its line starts found once, each line then a binary search. */
|
|
30
|
+
function linesOf(text: string): (index: number) => number {
|
|
31
|
+
const starts = [0];
|
|
32
|
+
for (let at = text.indexOf("\n"); at >= 0; at = text.indexOf("\n", at + 1)) {
|
|
33
|
+
starts.push(at + 1);
|
|
34
|
+
}
|
|
35
|
+
return (index) => {
|
|
36
|
+
let low = 0;
|
|
37
|
+
let high = starts.length - 1;
|
|
38
|
+
while (low < high) {
|
|
39
|
+
const middle = (low + high + 1) >> 1;
|
|
40
|
+
if ((starts[middle] ?? 0) <= index) {
|
|
41
|
+
low = middle;
|
|
42
|
+
} else {
|
|
43
|
+
high = middle - 1;
|
|
44
|
+
}
|
|
45
|
+
}
|
|
46
|
+
return low + 1;
|
|
47
|
+
};
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
const textOf = (body: string | Uint8Array): string =>
|
|
51
|
+
typeof body === "string" ? body : new TextDecoder().decode(body);
|
|
52
|
+
|
|
53
|
+
const sizeOf = (body: string | Uint8Array): number =>
|
|
54
|
+
typeof body === "string" ? new TextEncoder().encode(body).byteLength : body.byteLength;
|
|
55
|
+
|
|
56
|
+
/** How much of one file the references are looked for in: its first 2 MiB of text. */
|
|
57
|
+
const SCANNED = 2 * 1024 * 1024;
|
|
58
|
+
/** The most references of one kind looked up in one file: past that, a file is only linted. */
|
|
59
|
+
const MOST_REFERENCES = 2_000;
|
|
60
|
+
|
|
61
|
+
/** A reference a file makes, and where it starts in the file's text. */
|
|
62
|
+
interface Reference {
|
|
63
|
+
readonly reference: string;
|
|
64
|
+
readonly index: number;
|
|
65
|
+
}
|
|
66
|
+
|
|
67
|
+
/** The elements whose attribute names a file the page loads or links: which attribute. */
|
|
68
|
+
const REFERENCE_ATTRIBUTES: Readonly<Record<string, readonly string[]>> = {
|
|
69
|
+
script: ["src"],
|
|
70
|
+
img: ["src"],
|
|
71
|
+
source: ["src"],
|
|
72
|
+
video: ["src", "poster"],
|
|
73
|
+
audio: ["src"],
|
|
74
|
+
track: ["src"],
|
|
75
|
+
embed: ["src"],
|
|
76
|
+
input: ["src"],
|
|
77
|
+
link: ["href"],
|
|
78
|
+
a: ["href"],
|
|
79
|
+
area: ["href"],
|
|
80
|
+
};
|
|
81
|
+
|
|
82
|
+
/** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
|
|
83
|
+
const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
|
|
84
|
+
|
|
85
|
+
const isSpace = (code: number): boolean =>
|
|
86
|
+
code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
|
|
87
|
+
|
|
88
|
+
/** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
|
|
89
|
+
function attributesOf(text: string): { name: string; value: string; at: number }[] {
|
|
90
|
+
const out: { name: string; value: string; at: number }[] = [];
|
|
91
|
+
let at = 0;
|
|
92
|
+
while (at < text.length) {
|
|
93
|
+
while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
|
|
94
|
+
at += 1;
|
|
95
|
+
}
|
|
96
|
+
const nameStart = at;
|
|
97
|
+
while (
|
|
98
|
+
at < text.length &&
|
|
99
|
+
!isSpace(text.charCodeAt(at)) &&
|
|
100
|
+
text[at] !== "=" &&
|
|
101
|
+
text[at] !== "/"
|
|
102
|
+
) {
|
|
103
|
+
at += 1;
|
|
104
|
+
}
|
|
105
|
+
const name = text.slice(nameStart, at).toLowerCase();
|
|
106
|
+
if (name === "") {
|
|
107
|
+
at += 1;
|
|
108
|
+
continue;
|
|
109
|
+
}
|
|
110
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
111
|
+
at += 1;
|
|
112
|
+
}
|
|
113
|
+
if (text[at] !== "=") {
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
at += 1;
|
|
117
|
+
while (at < text.length && isSpace(text.charCodeAt(at))) {
|
|
118
|
+
at += 1;
|
|
119
|
+
}
|
|
120
|
+
const quote = text[at];
|
|
121
|
+
if (quote === '"' || quote === "'") {
|
|
122
|
+
const close = text.indexOf(quote, at + 1);
|
|
123
|
+
const end = close < 0 ? text.length : close;
|
|
124
|
+
out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
|
|
125
|
+
at = end + 1;
|
|
126
|
+
} else {
|
|
127
|
+
const start = at;
|
|
128
|
+
while (at < text.length && !isSpace(text.charCodeAt(at))) {
|
|
129
|
+
at += 1;
|
|
130
|
+
}
|
|
131
|
+
out.push({ name, value: text.slice(start, at), at: start });
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
return out;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
|
|
138
|
+
function markupReferences(text: string): Reference[] {
|
|
139
|
+
const found: Reference[] = [];
|
|
140
|
+
for (const tag of text.matchAll(TAG)) {
|
|
141
|
+
if (found.length >= MOST_REFERENCES) {
|
|
142
|
+
break;
|
|
143
|
+
}
|
|
144
|
+
const name = (tag[1] ?? "").toLowerCase();
|
|
145
|
+
const wanted = Object.hasOwn(REFERENCE_ATTRIBUTES, name)
|
|
146
|
+
? REFERENCE_ATTRIBUTES[name]
|
|
147
|
+
: undefined;
|
|
148
|
+
if (wanted === undefined) {
|
|
149
|
+
continue;
|
|
150
|
+
}
|
|
151
|
+
const offset = tag.index + 1 + name.length;
|
|
152
|
+
for (const attribute of attributesOf(tag[2] ?? "")) {
|
|
153
|
+
if (wanted.includes(attribute.name) && attribute.value !== "") {
|
|
154
|
+
found.push({ reference: attribute.value, index: offset + attribute.at });
|
|
155
|
+
}
|
|
156
|
+
}
|
|
157
|
+
}
|
|
158
|
+
return found;
|
|
159
|
+
}
|
|
160
|
+
|
|
161
|
+
/**
|
|
162
|
+
* The references a text's patterns find (group 2 of each). Every pattern is bounded and stops at
|
|
163
|
+
* its own delimiters, so a text is read in linear time, however it was written.
|
|
164
|
+
*/
|
|
165
|
+
function patternReferences(text: string, patterns: readonly RegExp[]): Reference[] {
|
|
166
|
+
const found: Reference[] = [];
|
|
167
|
+
for (const pattern of patterns) {
|
|
168
|
+
let count = 0;
|
|
169
|
+
for (const match of text.matchAll(pattern)) {
|
|
170
|
+
found.push({ reference: match[2] ?? "", index: match.index });
|
|
171
|
+
count += 1;
|
|
172
|
+
if (count >= MOST_REFERENCES) {
|
|
173
|
+
break;
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
}
|
|
177
|
+
return found;
|
|
178
|
+
}
|
|
179
|
+
|
|
180
|
+
const CSS_REFERENCES: readonly RegExp[] = [
|
|
181
|
+
/url\(\s{0,64}(["']?)([^"'()\s]{1,2048})\1\s{0,64}\)/giu,
|
|
182
|
+
/@import\s{1,64}(["'])([^"'\n]{1,2048})\1/giu,
|
|
183
|
+
];
|
|
184
|
+
/** In a script: what resolves from the module (imports, `new URL(…, import.meta.url)`). */
|
|
185
|
+
const MODULE_REFERENCES: readonly RegExp[] = [
|
|
186
|
+
/\bfrom\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
|
|
187
|
+
/\bimport\s{0,64}\(?\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
|
|
188
|
+
/\bnew\s{1,64}URL\s{0,64}\(\s{0,64}(["'])([^"'\n]{1,2048})\1\s{0,64},\s{0,64}import\.meta\.url\b/gu,
|
|
189
|
+
];
|
|
190
|
+
/** In a script: what resolves from the page (fetches, workers made from a string). */
|
|
191
|
+
const PAGE_REFERENCES: readonly RegExp[] = [
|
|
192
|
+
/\bfetch\s{0,64}\(\s{0,64}(["'`])(\.{0,2}\/?[\w./-][^"'`$\n]{0,2048})\1/gu,
|
|
193
|
+
/\bnew\s{1,64}(?:Shared)?Worker\s{0,64}\(\s{0,64}(["'`])([^"'`$\n]{1,2048})\1/gu,
|
|
194
|
+
];
|
|
195
|
+
|
|
196
|
+
/** Whether a reference leaves the set for good reason: another origin, inline data, an anchor. */
|
|
197
|
+
const elsewhere = (reference: string): boolean =>
|
|
198
|
+
/^[a-z][a-z0-9+.-]*:/iu.test(reference) ||
|
|
199
|
+
reference.startsWith("//") ||
|
|
200
|
+
reference.startsWith("#");
|
|
201
|
+
|
|
202
|
+
/** `reference` from a file in `directory` ("" or "a/b/"), as a path of the set; null above it. */
|
|
203
|
+
function resolve(directory: string, reference: string): string | null {
|
|
204
|
+
const bare = reference.split("#")[0]?.split("?")[0] ?? "";
|
|
205
|
+
let decoded: string;
|
|
206
|
+
try {
|
|
207
|
+
decoded = decodeURIComponent(bare);
|
|
208
|
+
} catch {
|
|
209
|
+
decoded = bare;
|
|
210
|
+
}
|
|
211
|
+
const segments = `${directory}${decoded}`.split("/");
|
|
212
|
+
const out: string[] = [];
|
|
213
|
+
for (const [index, segment] of segments.entries()) {
|
|
214
|
+
if (segment === "..") {
|
|
215
|
+
if (out.length === 0) {
|
|
216
|
+
return null;
|
|
217
|
+
}
|
|
218
|
+
out.pop();
|
|
219
|
+
} else if (segment !== "." && (segment !== "" || index === segments.length - 1)) {
|
|
220
|
+
out.push(segment);
|
|
221
|
+
}
|
|
222
|
+
}
|
|
223
|
+
return out.join("/");
|
|
224
|
+
}
|
|
225
|
+
|
|
226
|
+
const directoryOf = (path: string): string => path.slice(0, path.lastIndexOf("/") + 1);
|
|
227
|
+
|
|
228
|
+
/**
|
|
229
|
+
* Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
|
|
230
|
+
* `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
|
|
231
|
+
* names the address's root rather than the version, is an error in a page's markup), and each
|
|
232
|
+
* file whose extension the server doesn't know (a download).
|
|
233
|
+
*/
|
|
234
|
+
export function lintFiles(
|
|
235
|
+
config: PortholeConfig,
|
|
236
|
+
files: FileContents,
|
|
237
|
+
options: { readonly entry?: string } = {},
|
|
238
|
+
): FileFinding[] {
|
|
239
|
+
const findings: FileFinding[] = [];
|
|
240
|
+
if (!servesFiles(config)) {
|
|
241
|
+
findings.push({
|
|
242
|
+
rule: "files",
|
|
243
|
+
severity: "error",
|
|
244
|
+
message:
|
|
245
|
+
"A page here is one document: it can't come with files. Put its styles, scripts and data in the page itself.",
|
|
246
|
+
});
|
|
247
|
+
return findings;
|
|
248
|
+
}
|
|
249
|
+
const entry = options.entry ?? DEFAULT_ENTRY;
|
|
250
|
+
const sized = Object.fromEntries(
|
|
251
|
+
Object.entries(files).map(([path, body]) => [path, { size: sizeOf(body) }]),
|
|
252
|
+
);
|
|
253
|
+
const problems = checkFileSet(sized, { entry, limits: fileLimits(config.limits) });
|
|
254
|
+
for (const problem of problems) {
|
|
255
|
+
findings.push({
|
|
256
|
+
rule: "files",
|
|
257
|
+
severity: "error",
|
|
258
|
+
message: `${problem.message}.`,
|
|
259
|
+
...(problem.path === undefined ? {} : { path: problem.path }),
|
|
260
|
+
});
|
|
261
|
+
}
|
|
262
|
+
// Over the limits, the version isn't taken: nothing in it is read.
|
|
263
|
+
if (
|
|
264
|
+
problems.some((each) => each.code === "count" || each.code === "size" || each.code === "total")
|
|
265
|
+
) {
|
|
266
|
+
return findings;
|
|
267
|
+
}
|
|
268
|
+
const has = (path: string): boolean => Object.hasOwn(files, path);
|
|
269
|
+
const found = (path: string): boolean =>
|
|
270
|
+
lookupFile(has, path, { entry, navigation: false }).kind !== "none";
|
|
271
|
+
const reported = new Set<string>();
|
|
272
|
+
const check = (
|
|
273
|
+
from: string,
|
|
274
|
+
lineOf: (index: number) => number,
|
|
275
|
+
references: readonly Reference[],
|
|
276
|
+
directory: string,
|
|
277
|
+
rooted: "error" | "warning",
|
|
278
|
+
also?: string,
|
|
279
|
+
) => {
|
|
280
|
+
const seen = new Set<string>();
|
|
281
|
+
for (const { reference, index } of references) {
|
|
282
|
+
if (seen.has(reference)) {
|
|
283
|
+
continue;
|
|
284
|
+
}
|
|
285
|
+
seen.add(reference);
|
|
286
|
+
if (reference === "" || elsewhere(reference) || reference.includes("${")) {
|
|
287
|
+
continue;
|
|
288
|
+
}
|
|
289
|
+
if (reference.startsWith("/")) {
|
|
290
|
+
const key = `${from} / ${reference}`;
|
|
291
|
+
if (!reported.has(key)) {
|
|
292
|
+
reported.add(key);
|
|
293
|
+
findings.push({
|
|
294
|
+
rule: "root-path",
|
|
295
|
+
severity: rooted,
|
|
296
|
+
message: `${reference} starts with /: that is the address's root, not this version's files. Write it relative (.${reference})${reference.startsWith("/assets/") ? '; for a Vite build, set base: "./"' : ""}.`,
|
|
297
|
+
path: from,
|
|
298
|
+
line: lineOf(index),
|
|
299
|
+
});
|
|
300
|
+
}
|
|
301
|
+
continue;
|
|
302
|
+
}
|
|
303
|
+
const target = resolve(directory, reference);
|
|
304
|
+
const other = also === undefined ? null : resolve(also, reference);
|
|
305
|
+
const named = (target !== null && found(target)) || (other !== null && found(other));
|
|
306
|
+
const key = `${from} ${target ?? reference}`;
|
|
307
|
+
if (!named && !reported.has(key)) {
|
|
308
|
+
reported.add(key);
|
|
309
|
+
findings.push({
|
|
310
|
+
rule: "missing-file",
|
|
311
|
+
severity: "warning",
|
|
312
|
+
message:
|
|
313
|
+
target === null && other === null
|
|
314
|
+
? `${reference} goes above the version's own files: nothing is there.`
|
|
315
|
+
: `${reference} names ${(target ?? other) === "" ? "the version's entry" : (target ?? other)}, which isn't one of the files.`,
|
|
316
|
+
path: from,
|
|
317
|
+
line: lineOf(index),
|
|
318
|
+
});
|
|
319
|
+
}
|
|
320
|
+
}
|
|
321
|
+
};
|
|
322
|
+
const maxPage = config.limits.maxBytes;
|
|
323
|
+
for (const [path, body] of Object.entries(files)) {
|
|
324
|
+
const { role } = fileTypeOf(path);
|
|
325
|
+
if (!knownType(path)) {
|
|
326
|
+
findings.push({
|
|
327
|
+
rule: "file-type",
|
|
328
|
+
severity: "warning",
|
|
329
|
+
message: `${path} is served as a download: its extension isn't one the server knows.`,
|
|
330
|
+
path,
|
|
331
|
+
});
|
|
332
|
+
}
|
|
333
|
+
const directory = directoryOf(path);
|
|
334
|
+
if (role === "page") {
|
|
335
|
+
const bytes = sizeOf(body);
|
|
336
|
+
if (bytes > maxPage) {
|
|
337
|
+
// Over the page's limit: said, and not read further.
|
|
338
|
+
findings.push({
|
|
339
|
+
rule: "size",
|
|
340
|
+
severity: "error",
|
|
341
|
+
message: `It is ${sizeWords(bytes)}; a page may be at most ${sizeWords(maxPage)}: move what it holds into files of its own (scripts, styles, data).`,
|
|
342
|
+
path,
|
|
343
|
+
});
|
|
344
|
+
continue;
|
|
345
|
+
}
|
|
346
|
+
const text = textOf(body);
|
|
347
|
+
for (const finding of lintContent(config, text)) {
|
|
348
|
+
findings.push({ ...finding, path });
|
|
349
|
+
}
|
|
350
|
+
const lines = linesOf(text);
|
|
351
|
+
check(path, lines, markupReferences(text), directory, "error");
|
|
352
|
+
check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
|
|
353
|
+
check(
|
|
354
|
+
path,
|
|
355
|
+
lines,
|
|
356
|
+
patternReferences(text, [...MODULE_REFERENCES, ...PAGE_REFERENCES]),
|
|
357
|
+
directory,
|
|
358
|
+
"warning",
|
|
359
|
+
);
|
|
360
|
+
} else if (path.endsWith(".css")) {
|
|
361
|
+
const text = textOf(body).slice(0, SCANNED);
|
|
362
|
+
check(path, linesOf(text), patternReferences(text, CSS_REFERENCES), directory, "warning");
|
|
363
|
+
} else if (role === "script") {
|
|
364
|
+
const text = textOf(body).slice(0, SCANNED);
|
|
365
|
+
const lines = linesOf(text);
|
|
366
|
+
check(path, lines, patternReferences(text, MODULE_REFERENCES), directory, "warning");
|
|
367
|
+
// A fetch from a script resolves from the page that runs it: the entry's directory, or the
|
|
368
|
+
// script's own (a worker's).
|
|
369
|
+
check(
|
|
370
|
+
path,
|
|
371
|
+
lines,
|
|
372
|
+
patternReferences(text, PAGE_REFERENCES),
|
|
373
|
+
directoryOf(entry),
|
|
374
|
+
"warning",
|
|
375
|
+
directory,
|
|
376
|
+
);
|
|
377
|
+
}
|
|
378
|
+
}
|
|
379
|
+
return findings;
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
/** Where a finding is, for the agent: `about.html line 3: `. */
|
|
383
|
+
export const whereOf = (finding: FileFinding): string =>
|
|
384
|
+
`${finding.path === undefined ? "" : finding.path}${finding.line === undefined ? "" : `${finding.path === undefined ? "" : " "}line ${finding.line}`}${finding.path === undefined && finding.line === undefined ? "" : ": "}`;
|
package/src/check/instrument.ts
CHANGED
|
@@ -1,3 +1,4 @@
|
|
|
1
|
+
import type { PageDeclaration } from "../runtime/declaration.ts";
|
|
1
2
|
import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
|
|
2
3
|
import type { InstanceRef } from "../isolation/types.ts";
|
|
3
4
|
|
|
@@ -14,6 +15,8 @@ export interface CheckRunSpec {
|
|
|
14
15
|
readonly scriptLines: readonly number[];
|
|
15
16
|
/** A served config's instance (located through the check's own server), else opaque. */
|
|
16
17
|
readonly instance?: InstanceRef;
|
|
18
|
+
/** Under a runtime: the page's declaration (null: none). */
|
|
19
|
+
readonly declaration?: PageDeclaration | null;
|
|
17
20
|
readonly widthPx: number;
|
|
18
21
|
readonly heightPx?: number;
|
|
19
22
|
readonly scheme: ColorScheme;
|