@botiverse/porthole 0.5.1 → 0.6.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.
Files changed (73) hide show
  1. package/README.md +25 -0
  2. package/dist/bridge/bridge.js +8 -5
  3. package/dist/bridge/navigation.d.ts +1 -6
  4. package/dist/bridge/navigation.js +11 -0
  5. package/dist/check/check.d.ts +12 -3
  6. package/dist/check/check.js +54 -8
  7. package/dist/check/files.d.ts +26 -0
  8. package/dist/check/files.js +307 -0
  9. package/dist/check/lint.js +27 -10
  10. package/dist/check/page-source.js +1 -1
  11. package/dist/check/tools.d.ts +23 -0
  12. package/dist/check/tools.js +25 -0
  13. package/dist/compile/policy.d.ts +15 -0
  14. package/dist/compile/policy.js +32 -0
  15. package/dist/config/schema.d.ts +8 -0
  16. package/dist/config/validate.js +8 -1
  17. package/dist/conformance/harness-source.js +1 -1
  18. package/dist/files/paths.d.ts +99 -0
  19. package/dist/files/paths.js +263 -0
  20. package/dist/files/types.d.ts +24 -0
  21. package/dist/files/types.js +83 -0
  22. package/dist/guide/guide.js +11 -1
  23. package/dist/host/create-host.js +21 -0
  24. package/dist/index.d.ts +6 -3
  25. package/dist/index.js +8 -3
  26. package/dist/protocol/adapter.d.ts +4 -0
  27. package/dist/protocol/mcp-apps.d.ts +6 -0
  28. package/dist/protocol/mcp-apps.js +6 -0
  29. package/dist/protocol/shell-adapter.js +5 -1
  30. package/dist/server/files.d.ts +44 -0
  31. package/dist/server/files.js +244 -0
  32. package/dist/server/host.d.ts +38 -1
  33. package/dist/server/host.js +37 -2
  34. package/dist/server/index.d.ts +4 -2
  35. package/dist/server/index.js +4 -1
  36. package/dist/server/keys.d.ts +8 -0
  37. package/dist/server/keys.js +34 -0
  38. package/dist/server/server.js +287 -22
  39. package/dist/server/types.d.ts +49 -5
  40. package/dist/shell/document.d.ts +19 -0
  41. package/dist/shell/document.js +30 -0
  42. package/dist/shell/runtime.d.ts +2 -1
  43. package/dist/shell/runtime.js +85 -4
  44. package/docs/ADOPTING.md +56 -4
  45. package/docs/ARCHITECTURE.md +13 -3
  46. package/docs/DECISIONS.md +304 -4
  47. package/docs/DESIGN.md +31 -3
  48. package/package.json +1 -1
  49. package/src/bridge/bridge.ts +8 -5
  50. package/src/bridge/navigation.ts +12 -0
  51. package/src/check/check.ts +92 -14
  52. package/src/check/files.ts +384 -0
  53. package/src/check/lint.ts +29 -10
  54. package/src/check/tools.ts +50 -0
  55. package/src/compile/policy.ts +38 -0
  56. package/src/config/schema.ts +8 -0
  57. package/src/config/validate.ts +8 -1
  58. package/src/files/paths.ts +323 -0
  59. package/src/files/types.ts +101 -0
  60. package/src/guide/guide.ts +20 -0
  61. package/src/host/create-host.ts +21 -0
  62. package/src/index.ts +32 -0
  63. package/src/protocol/adapter.ts +3 -1
  64. package/src/protocol/mcp-apps.ts +7 -0
  65. package/src/protocol/shell-adapter.ts +5 -0
  66. package/src/server/files.ts +312 -0
  67. package/src/server/host.ts +72 -3
  68. package/src/server/index.ts +19 -0
  69. package/src/server/keys.ts +53 -0
  70. package/src/server/server.ts +353 -24
  71. package/src/server/types.ts +56 -4
  72. package/src/shell/document.ts +53 -0
  73. package/src/shell/runtime.ts +85 -4
package/README.md CHANGED
@@ -52,6 +52,31 @@ display.setContent("<p>Hello from an agent</p>");
52
52
  In React: `<PortholeProvider>` around `<PortholeFrame config displayId title scheme content />` from
53
53
  `@botiverse/porthole/react`.
54
54
 
55
+ ## Pages made of many files
56
+
57
+ A served page may come with files of its own: a build's output, a report with its images, a
58
+ dashboard that reads its data (0.6). The store answers a manifest and the bytes by path, and the
59
+ page's relative addresses are its own version's:
60
+
61
+ ```js
62
+ source: async (id, version) => ({
63
+ files: { "index.html": { size: 397, sha256: "…" }, "assets/app.js": { size: 142870, sha256: "…" } },
64
+ read: (path) => myStore.bytes(id, version, path), // Uint8Array or a stream, whole
65
+ }),
66
+ entry: {
67
+ // "/v/3/<file>" is version 3, any other path the latest's: answer with the version's own address.
68
+ at: async (scope, path) => {
69
+ const at = versionedAddress(path), version = at?.version ?? (await latestOf(scope));
70
+ return at && { instance: pageOf(scope, version), base: versionBase(version), file: at.file, pinned: true };
71
+ },
72
+ },
73
+ ```
74
+
75
+ Each file is served from the manifest only, typed by Porthole's own table, `nosniff`, with a CSP
76
+ that opens that version's path and nothing else of its origin; `checkFileSet` checks a version's
77
+ paths and limits when it is published, `lintFiles` and `checkPage({ files })` are the agent's
78
+ side. docs/ADOPTING.md § Pages made of many files.
79
+
55
80
  ## What the agent gets
56
81
 
57
82
  ```js
@@ -1,7 +1,7 @@
1
1
  import { MAX_COPY_CHARS, capabilitySpec, } from "../config/capabilities.js";
2
2
  import { parseReport } from "../annotate/validate.js";
3
3
  import { effectiveGates } from "../compile/policy.js";
4
- import { blockedNavigationMessage } from "./navigation.js";
4
+ import { blockedNavigationMessage, withoutSealedAddresses } from "./navigation.js";
5
5
  import { defaultReason, isRefused, pendingReason, reasonOf, } from "./refusal.js";
6
6
  const isRecord = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
7
7
  const MAX_URL = 4_096;
@@ -77,15 +77,18 @@ const VALIDATORS = {
77
77
  reportError: (args, config) => {
78
78
  // A navigation the shell cancelled (P080): Porthole words it, naming the address without its
79
79
  // query; the address itself goes to the host whole.
80
+ // A frame's sealed files' address never reaches the host from here (P083): `./` instead.
80
81
  const blocked = isRecord(args) ? args.navigationBlocked : undefined;
81
82
  if (blocked !== undefined) {
82
- return typeof blocked === "string" && blocked !== "" && blocked.length <= MAX_URL
83
- ? { message: blockedNavigationMessage(blocked, config), navigationBlocked: blocked }
84
- : null;
83
+ if (typeof blocked !== "string" || blocked === "" || blocked.length > MAX_URL) {
84
+ return null;
85
+ }
86
+ const url = withoutSealedAddresses(blocked);
87
+ return { message: blockedNavigationMessage(url, config), navigationBlocked: url };
85
88
  }
86
89
  const message = isRecord(args) ? args.message : undefined;
87
90
  return typeof message === "string" && message !== ""
88
- ? { message: message.slice(0, 2_000) }
91
+ ? { message: withoutSealedAddresses(message).slice(0, 2_000) }
89
92
  : null;
90
93
  },
91
94
  copyText: (args) => {
@@ -1,10 +1,5 @@
1
1
  import type { PortholeConfig } from "../config/schema.ts";
2
- /**
3
- * A navigation the shell cancelled (P079), as the host is told it (P080): the address, whole, on
4
- * the `navigationBlocked` event (the host's to keep), and a sentence for the content's errors
5
- * (`contentError`, which a host may give the agent that wrote it) that names the address without
6
- * its query or fragment, where a viewer's data would be.
7
- */
2
+ export declare const withoutSealedAddresses: (text: string) => string;
8
3
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
9
4
  export declare function addressWithoutQuery(url: string): string;
10
5
  /** What the content's errors say about a navigation the shell cancelled. */
@@ -4,8 +4,19 @@
4
4
  * (`contentError`, which a host may give the agent that wrote it) that names the address without
5
5
  * its query or fragment, where a viewer's data would be.
6
6
  */
7
+ /**
8
+ * A frame's sealed files' address (P083) is its access: whatever content says, the host is told
9
+ * it as `./`, the page's own files (the shell says it so already; content may not).
10
+ */
11
+ const SEALED = /(?:https?:\/\/[^\s"'<>/]+)?\/__porthole\/f\/[A-Za-z0-9_-]{20,}\//gu;
12
+ export const withoutSealedAddresses = (text) => text.replace(SEALED, "./");
7
13
  /** An address without what could carry data: an http(s) one's origin and path, else its scheme. */
8
14
  export function addressWithoutQuery(url) {
15
+ // A page's own file (P084), as the shell names it: its path, without query or fragment.
16
+ if (url.startsWith("./")) {
17
+ const path = url.split(/[?#]/u)[0] ?? "./";
18
+ return path === url ? path : `${path}?…`;
19
+ }
9
20
  let parsed;
10
21
  try {
11
22
  parsed = new URL(url);
@@ -1,5 +1,5 @@
1
1
  import type { ColorScheme, PortholeConfig } from "../config/schema.ts";
2
- import { type Finding } from "./lint.ts";
2
+ import { type FileContents, type FileFinding } from "./files.ts";
3
3
  import { type CheckCall } from "./instrument.ts";
4
4
  export type { CheckCall } from "./instrument.ts";
5
5
  /**
@@ -34,7 +34,15 @@ export interface CheckDriver {
34
34
  export interface CheckOptions {
35
35
  readonly config: PortholeConfig;
36
36
  /** The content as the agent would send it: a fragment, or a whole document. */
37
- readonly content: string;
37
+ readonly content?: string;
38
+ /**
39
+ * A page that comes with files (P081), in place of `content`: every file by its path. The whole
40
+ * set is served, as people's browsers get it, and its entry is run and measured. Needs a served
41
+ * artifact config and a driver that serves (`playwrightDriver`).
42
+ */
43
+ readonly files?: FileContents;
44
+ /** The page a set opens at (default `index.html`). */
45
+ readonly entry?: string;
38
46
  readonly driver: CheckDriver;
39
47
  /** Widths, px. Default: the manual's phone and desktop widths (`config.layout`). */
40
48
  readonly widths?: readonly number[];
@@ -92,7 +100,8 @@ export interface CheckReport {
92
100
  * refuses, overflow or cut, no lint error.
93
101
  */
94
102
  readonly ok: boolean;
95
- readonly lint: readonly Finding[];
103
+ /** What the lint found (for a page with files, each finding names its file, `path`). */
104
+ readonly lint: readonly FileFinding[];
96
105
  readonly runs: readonly CheckRun[];
97
106
  /** One short summary for the agent: each problem once, with where it happened. */
98
107
  readonly text: string;
@@ -2,6 +2,9 @@ import { presets } from "../presets/presets.js";
2
2
  import { createServer } from "../server/server.js";
3
3
  import { CHECK_CONTENT_DOMAIN, CHECK_ORIGIN } from "./drivers.js";
4
4
  import { lintContent } from "./lint.js";
5
+ import { lintFiles, whereOf } from "./files.js";
6
+ import { DEFAULT_ENTRY, servesFiles } from "../files/paths.js";
7
+ import { sha256 } from "../server/crypto.js";
5
8
  // The check page's script, imported as a module so a bundler takes it in (P075): no file is
6
9
  // looked up beside this one at run time.
7
10
  import PAGE_SCRIPT from "./page-source.js";
@@ -21,9 +24,42 @@ function checkedAs(config) {
21
24
  : opaque;
22
25
  }
23
26
  const escapeScript = (code) => code.replace(/<\/script/giu, "<\\/script");
27
+ /** A set's own files named by their path, as the agent wrote them, not the frame's address. */
28
+ const ownPaths = (text) => text.replace(/https:\/\/[a-z0-9.-]+\/__porthole\/f\/[\w-]+\//gu, "");
29
+ const hex = (bytes) => Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
30
+ /** A set's files as the check's server stores them, its entry instrumented (P081). */
31
+ function checkedFiles(files, entry, page) {
32
+ const bytes = (body) => typeof body === "string" ? new TextEncoder().encode(body) : body;
33
+ const served = new Map(Object.entries(files).map(([path, body]) => [path, path === entry ? bytes(page) : bytes(body)]));
34
+ return {
35
+ files: Object.fromEntries([...served].map(([path, body]) => [
36
+ path,
37
+ { size: body.byteLength, sha256: hex(sha256(body)) },
38
+ ])),
39
+ entry,
40
+ read: (path) => Promise.resolve(served.get(path) ?? null),
41
+ };
42
+ }
24
43
  export async function checkPage(options) {
25
44
  const { config } = options;
26
- const lint = lintContent(config, options.content);
45
+ const entry = options.entry ?? DEFAULT_ENTRY;
46
+ const files = options.files;
47
+ if ((files === undefined) === (options.content === undefined)) {
48
+ throw new TypeError("checkPage takes content, or files: one of them");
49
+ }
50
+ if (files !== undefined && !servesFiles(config)) {
51
+ throw new TypeError("A page with files is checked under a served artifact config");
52
+ }
53
+ const entryText = () => {
54
+ const body = files?.[entry];
55
+ return body === undefined
56
+ ? ""
57
+ : typeof body === "string"
58
+ ? body
59
+ : new TextDecoder().decode(body);
60
+ };
61
+ const written = files === undefined ? (options.content ?? "") : entryText();
62
+ const lint = files === undefined ? lintContent(config, written) : lintFiles(config, files, { entry });
27
63
  if (config.mode === "url") {
28
64
  return {
29
65
  ok: true,
@@ -40,8 +76,12 @@ export async function checkPage(options) {
40
76
  const script = options.page ?? PAGE_SCRIPT;
41
77
  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>`;
42
78
  // Its inline scripts named, so an error says the line in the content as written (P074).
43
- const { content, scriptLines } = namedScripts(options.content);
79
+ const { content, scriptLines } = namedScripts(written);
44
80
  const session = await options.driver.open();
81
+ if (files !== undefined && session.serve === undefined) {
82
+ await session.close();
83
+ throw new TypeError("A page with files is checked served: this driver can't serve (no serve)");
84
+ }
45
85
  // A served config runs served, on a content origin the driver answers, under Porthole's own
46
86
  // server: its CSP in headers, its shell, its storage and cookies (P074). Else opaque.
47
87
  const servedHere = config.isolation === "domain" && config.mode !== "mcp-app" && session.serve !== undefined;
@@ -52,7 +92,11 @@ export async function checkPage(options) {
52
92
  secret: crypto.getRandomValues(new Uint8Array(32)),
53
93
  hostOrigins: [CHECK_ORIGIN],
54
94
  configs: { check: servedConfig },
55
- artifacts: { get: () => Promise.resolve({ html: instrumented(content) }) },
95
+ artifacts: {
96
+ get: () => Promise.resolve(files === undefined
97
+ ? { html: instrumented(content) }
98
+ : checkedFiles(files, entry, instrumented(content))),
99
+ },
56
100
  })
57
101
  : null;
58
102
  const handler = async (request) => {
@@ -122,10 +166,10 @@ export async function checkPage(options) {
122
166
  data?.scrollWidth !== undefined &&
123
167
  data.clientWidth !== null &&
124
168
  data.scrollWidth > data.clientWidth + 1,
125
- errors: unique(data?.errors ?? []),
126
- blocked: uniqueBy(data?.blocked ?? [], (each) => `${each.url} ${each.directive}`),
127
- failedLoads: uniqueBy(data?.failedLoads ?? [], (each) => each.url),
128
- console: uniqueBy(data?.console ?? [], (each) => `${each.level} ${each.text}`),
169
+ errors: unique((data?.errors ?? []).map(ownPaths)),
170
+ blocked: uniqueBy((data?.blocked ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => `${each.url} ${each.directive}`),
171
+ failedLoads: uniqueBy((data?.failedLoads ?? []).map((each) => ({ ...each, url: ownPaths(each.url) })), (each) => each.url),
172
+ console: uniqueBy((data?.console ?? []).map((each) => ({ ...each, text: ownPaths(each.text) })), (each) => `${each.level} ${each.text}`),
129
173
  calls: uniqueBy(data?.calls ?? [], (each) => `${each.capability} ${each.outcome}`),
130
174
  ...(screenshot === undefined ? {} : { screenshot }),
131
175
  });
@@ -211,7 +255,9 @@ function summary(config, lint, runs, most) {
211
255
  }
212
256
  }
213
257
  const lines = [
214
- ...lint.map((each) => `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`),
258
+ ...lint.map((each) => each.path === undefined
259
+ ? `${each.severity === "error" ? "Error" : "Warning"}${each.line === undefined ? "" : ` (line ${each.line})`}: ${each.message}`
260
+ : `${each.severity === "error" ? "Error" : "Warning"} (${whereOf(each).replace(/: $/u, "")}): ${each.message}`),
215
261
  ...[...where].map(([problem, at]) => `${problem} (at ${at.length === runs.length ? "every width and scheme" : at.join(", ")}).`),
216
262
  ];
217
263
  const ran = `${[...new Set(runs.map((run) => `${run.width} px`))].join(" and ")}, ${[...new Set(runs.map((run) => run.scheme))].join(" and ")}`;
@@ -0,0 +1,26 @@
1
+ import type { PortholeConfig } from "../config/schema.ts";
2
+ import { type Finding } from "./lint.ts";
3
+ /**
4
+ * What can be told about a page that comes with files (P081), without running it: each page
5
+ * linted as a page is, the set held to the path rules and limits, and every relative reference
6
+ * looked up in the set. Errors are what certainly fails (`admitFiles` refuses them); the rest
7
+ * are warnings. Pure: any runtime.
8
+ */
9
+ /** A finding about one file of the set (`path`), or about the set as a whole. */
10
+ export interface FileFinding extends Omit<Finding, "rule"> {
11
+ readonly rule: Finding["rule"] | "files" | "missing-file" | "root-path" | "file-type";
12
+ readonly path?: string;
13
+ }
14
+ /** A set's files, by path: text, or bytes. */
15
+ export type FileContents = Readonly<Record<string, string | Uint8Array>>;
16
+ /**
17
+ * Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
18
+ * `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
19
+ * names the address's root rather than the version, is an error in a page's markup), and each
20
+ * file whose extension the server doesn't know (a download).
21
+ */
22
+ export declare function lintFiles(config: PortholeConfig, files: FileContents, options?: {
23
+ readonly entry?: string;
24
+ }): FileFinding[];
25
+ /** Where a finding is, for the agent: `about.html line 3: `. */
26
+ export declare const whereOf: (finding: FileFinding) => string;
@@ -0,0 +1,307 @@
1
+ import { checkFileSet, DEFAULT_ENTRY, fileLimits, lookupFile, servesFiles, } from "../files/paths.js";
2
+ import { fileTypeOf, knownType } from "../files/types.js";
3
+ import { sizeWords } from "../guide/limits.js";
4
+ import { lintContent } from "./lint.js";
5
+ /** A text's line numbers by offset: its line starts found once, each line then a binary search. */
6
+ function linesOf(text) {
7
+ const starts = [0];
8
+ for (let at = text.indexOf("\n"); at >= 0; at = text.indexOf("\n", at + 1)) {
9
+ starts.push(at + 1);
10
+ }
11
+ return (index) => {
12
+ let low = 0;
13
+ let high = starts.length - 1;
14
+ while (low < high) {
15
+ const middle = (low + high + 1) >> 1;
16
+ if ((starts[middle] ?? 0) <= index) {
17
+ low = middle;
18
+ }
19
+ else {
20
+ high = middle - 1;
21
+ }
22
+ }
23
+ return low + 1;
24
+ };
25
+ }
26
+ const textOf = (body) => typeof body === "string" ? body : new TextDecoder().decode(body);
27
+ const sizeOf = (body) => typeof body === "string" ? new TextEncoder().encode(body).byteLength : body.byteLength;
28
+ /** How much of one file the references are looked for in: its first 2 MiB of text. */
29
+ const SCANNED = 2 * 1024 * 1024;
30
+ /** The most references of one kind looked up in one file: past that, a file is only linted. */
31
+ const MOST_REFERENCES = 2_000;
32
+ /** The elements whose attribute names a file the page loads or links: which attribute. */
33
+ const REFERENCE_ATTRIBUTES = {
34
+ script: ["src"],
35
+ img: ["src"],
36
+ source: ["src"],
37
+ video: ["src", "poster"],
38
+ audio: ["src"],
39
+ track: ["src"],
40
+ embed: ["src"],
41
+ input: ["src"],
42
+ link: ["href"],
43
+ a: ["href"],
44
+ area: ["href"],
45
+ };
46
+ /** A tag: its name and its attributes' text. Bounded, and never across another `<`: linear. */
47
+ const TAG = /<([a-z][a-z0-9-]{0,30})\b([^<>]{0,8192})>/giu;
48
+ const isSpace = (code) => code === 32 || code === 9 || code === 10 || code === 12 || code === 13;
49
+ /** A tag's attributes, read once from left to right (linear): each name, value and its offset. */
50
+ function attributesOf(text) {
51
+ const out = [];
52
+ let at = 0;
53
+ while (at < text.length) {
54
+ while (at < text.length && (isSpace(text.charCodeAt(at)) || text[at] === "/")) {
55
+ at += 1;
56
+ }
57
+ const nameStart = at;
58
+ while (at < text.length &&
59
+ !isSpace(text.charCodeAt(at)) &&
60
+ text[at] !== "=" &&
61
+ text[at] !== "/") {
62
+ at += 1;
63
+ }
64
+ const name = text.slice(nameStart, at).toLowerCase();
65
+ if (name === "") {
66
+ at += 1;
67
+ continue;
68
+ }
69
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
70
+ at += 1;
71
+ }
72
+ if (text[at] !== "=") {
73
+ continue;
74
+ }
75
+ at += 1;
76
+ while (at < text.length && isSpace(text.charCodeAt(at))) {
77
+ at += 1;
78
+ }
79
+ const quote = text[at];
80
+ if (quote === '"' || quote === "'") {
81
+ const close = text.indexOf(quote, at + 1);
82
+ const end = close < 0 ? text.length : close;
83
+ out.push({ name, value: text.slice(at + 1, end), at: at + 1 });
84
+ at = end + 1;
85
+ }
86
+ else {
87
+ const start = at;
88
+ while (at < text.length && !isSpace(text.charCodeAt(at))) {
89
+ at += 1;
90
+ }
91
+ out.push({ name, value: text.slice(start, at), at: start });
92
+ }
93
+ }
94
+ return out;
95
+ }
96
+ /** What a page's markup loads or links: each element's `src`, `href` or `poster`. */
97
+ function markupReferences(text) {
98
+ const found = [];
99
+ for (const tag of text.matchAll(TAG)) {
100
+ if (found.length >= MOST_REFERENCES) {
101
+ break;
102
+ }
103
+ const name = (tag[1] ?? "").toLowerCase();
104
+ const wanted = Object.hasOwn(REFERENCE_ATTRIBUTES, name)
105
+ ? REFERENCE_ATTRIBUTES[name]
106
+ : undefined;
107
+ if (wanted === undefined) {
108
+ continue;
109
+ }
110
+ const offset = tag.index + 1 + name.length;
111
+ for (const attribute of attributesOf(tag[2] ?? "")) {
112
+ if (wanted.includes(attribute.name) && attribute.value !== "") {
113
+ found.push({ reference: attribute.value, index: offset + attribute.at });
114
+ }
115
+ }
116
+ }
117
+ return found;
118
+ }
119
+ /**
120
+ * The references a text's patterns find (group 2 of each). Every pattern is bounded and stops at
121
+ * its own delimiters, so a text is read in linear time, however it was written.
122
+ */
123
+ function patternReferences(text, patterns) {
124
+ const found = [];
125
+ for (const pattern of patterns) {
126
+ let count = 0;
127
+ for (const match of text.matchAll(pattern)) {
128
+ found.push({ reference: match[2] ?? "", index: match.index });
129
+ count += 1;
130
+ if (count >= MOST_REFERENCES) {
131
+ break;
132
+ }
133
+ }
134
+ }
135
+ return found;
136
+ }
137
+ const CSS_REFERENCES = [
138
+ /url\(\s{0,64}(["']?)([^"'()\s]{1,2048})\1\s{0,64}\)/giu,
139
+ /@import\s{1,64}(["'])([^"'\n]{1,2048})\1/giu,
140
+ ];
141
+ /** In a script: what resolves from the module (imports, `new URL(…, import.meta.url)`). */
142
+ const MODULE_REFERENCES = [
143
+ /\bfrom\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
144
+ /\bimport\s{0,64}\(?\s{0,64}(["'])(\.{1,2}\/[^"'\n]{0,2048})\1/gu,
145
+ /\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,
146
+ ];
147
+ /** In a script: what resolves from the page (fetches, workers made from a string). */
148
+ const PAGE_REFERENCES = [
149
+ /\bfetch\s{0,64}\(\s{0,64}(["'`])(\.{0,2}\/?[\w./-][^"'`$\n]{0,2048})\1/gu,
150
+ /\bnew\s{1,64}(?:Shared)?Worker\s{0,64}\(\s{0,64}(["'`])([^"'`$\n]{1,2048})\1/gu,
151
+ ];
152
+ /** Whether a reference leaves the set for good reason: another origin, inline data, an anchor. */
153
+ const elsewhere = (reference) => /^[a-z][a-z0-9+.-]*:/iu.test(reference) ||
154
+ reference.startsWith("//") ||
155
+ reference.startsWith("#");
156
+ /** `reference` from a file in `directory` ("" or "a/b/"), as a path of the set; null above it. */
157
+ function resolve(directory, reference) {
158
+ const bare = reference.split("#")[0]?.split("?")[0] ?? "";
159
+ let decoded;
160
+ try {
161
+ decoded = decodeURIComponent(bare);
162
+ }
163
+ catch {
164
+ decoded = bare;
165
+ }
166
+ const segments = `${directory}${decoded}`.split("/");
167
+ const out = [];
168
+ for (const [index, segment] of segments.entries()) {
169
+ if (segment === "..") {
170
+ if (out.length === 0) {
171
+ return null;
172
+ }
173
+ out.pop();
174
+ }
175
+ else if (segment !== "." && (segment !== "" || index === segments.length - 1)) {
176
+ out.push(segment);
177
+ }
178
+ }
179
+ return out.join("/");
180
+ }
181
+ const directoryOf = (path) => path.slice(0, path.lastIndexOf("/") + 1);
182
+ /**
183
+ * Lints a page that comes with files (P081): the set (paths, limits, its entry), each page as
184
+ * `lintContent` lints a page, each relative reference looked up in the set (a leading `/`, which
185
+ * names the address's root rather than the version, is an error in a page's markup), and each
186
+ * file whose extension the server doesn't know (a download).
187
+ */
188
+ export function lintFiles(config, files, options = {}) {
189
+ const findings = [];
190
+ if (!servesFiles(config)) {
191
+ findings.push({
192
+ rule: "files",
193
+ severity: "error",
194
+ message: "A page here is one document: it can't come with files. Put its styles, scripts and data in the page itself.",
195
+ });
196
+ return findings;
197
+ }
198
+ const entry = options.entry ?? DEFAULT_ENTRY;
199
+ const sized = Object.fromEntries(Object.entries(files).map(([path, body]) => [path, { size: sizeOf(body) }]));
200
+ const problems = checkFileSet(sized, { entry, limits: fileLimits(config.limits) });
201
+ for (const problem of problems) {
202
+ findings.push({
203
+ rule: "files",
204
+ severity: "error",
205
+ message: `${problem.message}.`,
206
+ ...(problem.path === undefined ? {} : { path: problem.path }),
207
+ });
208
+ }
209
+ // Over the limits, the version isn't taken: nothing in it is read.
210
+ if (problems.some((each) => each.code === "count" || each.code === "size" || each.code === "total")) {
211
+ return findings;
212
+ }
213
+ const has = (path) => Object.hasOwn(files, path);
214
+ const found = (path) => lookupFile(has, path, { entry, navigation: false }).kind !== "none";
215
+ const reported = new Set();
216
+ const check = (from, lineOf, references, directory, rooted, also) => {
217
+ const seen = new Set();
218
+ for (const { reference, index } of references) {
219
+ if (seen.has(reference)) {
220
+ continue;
221
+ }
222
+ seen.add(reference);
223
+ if (reference === "" || elsewhere(reference) || reference.includes("${")) {
224
+ continue;
225
+ }
226
+ if (reference.startsWith("/")) {
227
+ const key = `${from} / ${reference}`;
228
+ if (!reported.has(key)) {
229
+ reported.add(key);
230
+ findings.push({
231
+ rule: "root-path",
232
+ severity: rooted,
233
+ 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: "./"' : ""}.`,
234
+ path: from,
235
+ line: lineOf(index),
236
+ });
237
+ }
238
+ continue;
239
+ }
240
+ const target = resolve(directory, reference);
241
+ const other = also === undefined ? null : resolve(also, reference);
242
+ const named = (target !== null && found(target)) || (other !== null && found(other));
243
+ const key = `${from} ${target ?? reference}`;
244
+ if (!named && !reported.has(key)) {
245
+ reported.add(key);
246
+ findings.push({
247
+ rule: "missing-file",
248
+ severity: "warning",
249
+ message: target === null && other === null
250
+ ? `${reference} goes above the version's own files: nothing is there.`
251
+ : `${reference} names ${(target ?? other) === "" ? "the version's entry" : (target ?? other)}, which isn't one of the files.`,
252
+ path: from,
253
+ line: lineOf(index),
254
+ });
255
+ }
256
+ }
257
+ };
258
+ const maxPage = config.limits.maxBytes;
259
+ for (const [path, body] of Object.entries(files)) {
260
+ const { role } = fileTypeOf(path);
261
+ if (!knownType(path)) {
262
+ findings.push({
263
+ rule: "file-type",
264
+ severity: "warning",
265
+ message: `${path} is served as a download: its extension isn't one the server knows.`,
266
+ path,
267
+ });
268
+ }
269
+ const directory = directoryOf(path);
270
+ if (role === "page") {
271
+ const bytes = sizeOf(body);
272
+ if (bytes > maxPage) {
273
+ // Over the page's limit: said, and not read further.
274
+ findings.push({
275
+ rule: "size",
276
+ severity: "error",
277
+ 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).`,
278
+ path,
279
+ });
280
+ continue;
281
+ }
282
+ const text = textOf(body);
283
+ for (const finding of lintContent(config, text)) {
284
+ findings.push({ ...finding, path });
285
+ }
286
+ const lines = linesOf(text);
287
+ check(path, lines, markupReferences(text), directory, "error");
288
+ check(path, lines, patternReferences(text, CSS_REFERENCES), directory, "warning");
289
+ check(path, lines, patternReferences(text, [...MODULE_REFERENCES, ...PAGE_REFERENCES]), directory, "warning");
290
+ }
291
+ else if (path.endsWith(".css")) {
292
+ const text = textOf(body).slice(0, SCANNED);
293
+ check(path, linesOf(text), patternReferences(text, CSS_REFERENCES), directory, "warning");
294
+ }
295
+ else if (role === "script") {
296
+ const text = textOf(body).slice(0, SCANNED);
297
+ const lines = linesOf(text);
298
+ check(path, lines, patternReferences(text, MODULE_REFERENCES), directory, "warning");
299
+ // A fetch from a script resolves from the page that runs it: the entry's directory, or the
300
+ // script's own (a worker's).
301
+ check(path, lines, patternReferences(text, PAGE_REFERENCES), directoryOf(entry), "warning", directory);
302
+ }
303
+ }
304
+ return findings;
305
+ }
306
+ /** Where a finding is, for the agent: `about.html line 3: `. */
307
+ export const whereOf = (finding) => `${finding.path === undefined ? "" : finding.path}${finding.line === undefined ? "" : `${finding.path === undefined ? "" : " "}line ${finding.line}`}${finding.path === undefined && finding.line === undefined ? "" : ": "}`;
@@ -21,22 +21,39 @@ export function fragmentOf(content) {
21
21
  .replace(/<head[^>]*>[\s\S]*?<\/head>/iu, "");
22
22
  return body.trim() === "" ? null : `${kept}${kept === "" ? "" : "\n"}${body.trim()}`;
23
23
  }
24
- /** Where content reaches out, by the kind of egress each would need. */
24
+ /**
25
+ * Where content reaches out, by the kind of egress each would need. Each pattern is bounded and
26
+ * never runs past its own delimiters (a tag's `<`, a string's quote), so a text is read in linear
27
+ * time however it was written.
28
+ */
25
29
  const REACHES = [
26
- { kind: "script", pattern: /<script\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
27
- { kind: "script", pattern: /\bimport\s*(?:[\w{}\s*,]+from\s*)?\(?\s*["'](https?:\/\/[^"']+)/gu },
28
- { kind: "style", pattern: /<link\b[^>]*\bhref\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
29
- { kind: "style", pattern: /@import\s+(?:url\()?["']?(https?:\/\/[^"')\s]+)/giu },
30
- { kind: "img", pattern: /<img\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu },
31
- { kind: "img", pattern: /url\(\s*["']?(https?:\/\/[^"')\s]+)/giu },
30
+ {
31
+ kind: "script",
32
+ pattern: /<script\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
33
+ },
34
+ { kind: "script", pattern: /\bfrom\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
35
+ { kind: "script", pattern: /\bimport\s{0,64}\(?\s{0,64}["'](https?:\/\/[^"'\n]{1,2048})/gu },
36
+ {
37
+ kind: "style",
38
+ pattern: /<link\b[^<>]{0,8192}?\bhref\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
39
+ },
40
+ {
41
+ kind: "style",
42
+ pattern: /@import\s{1,64}(?:url\()?["']?(https?:\/\/[^"')\s]{1,2048})/giu,
43
+ },
44
+ {
45
+ kind: "img",
46
+ pattern: /<img\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
47
+ },
48
+ { kind: "img", pattern: /url\(\s{0,64}["']?(https?:\/\/[^"')\s]{1,2048})/giu },
32
49
  {
33
50
  kind: "media",
34
- pattern: /<(?:video|audio|source)\b[^>]*\bsrc\s*=\s*["']?(https?:\/\/[^"'\s>]+)/giu,
51
+ pattern: /<(?:video|audio|source)\b[^<>]{0,8192}?\bsrc\s{0,64}=\s{0,64}["']?(https?:\/\/[^"'\s<>]{1,2048})/giu,
35
52
  },
36
- { kind: "connect", pattern: /\bfetch\s*\(\s*["'`](https?:\/\/[^"'`]+)/gu },
53
+ { kind: "connect", pattern: /\bfetch\s{0,64}\(\s{0,64}["'`](https?:\/\/[^"'`\n]{1,2048})/gu },
37
54
  {
38
55
  kind: "connect",
39
- pattern: /\bnew\s+(?:WebSocket|EventSource)\s*\(\s*["'`]((?:https?|wss?):\/\/[^"'`]+)/gu,
56
+ pattern: /\bnew\s{1,64}(?:WebSocket|EventSource)\s{0,64}\(\s{0,64}["'`]((?:https?|wss?):\/\/[^"'`\n]{1,2048})/gu,
40
57
  },
41
58
  ];
42
59
  const CDN_PACKAGE = /^https:\/\/(?:cdn\.jsdelivr\.net\/npm|unpkg\.com|esm\.sh)\/((?:@[^/]+\/)?[^/@]+)(@[^/]*)?/u;