functionalscript 0.46.0 → 0.47.0

package/fjs/website/browser-source.mjs

@@ -0,0 +1,202 @@
+/**
+ * Static reading of authored source text: whether a module exports `proof`,
+ * and which modules a browser would have to link to load it.
+ *
+ * The manifest generator classifies modules without importing them — that is
+ * the point of reading them as text — and TypeScript 7 exposes no compiler API,
+ * so both questions are answered here by reading the source as tokens, with
+ * their own proofs, rather than by patterns over lines: whether a declaration
+ * fits on one line, and how it is spaced, are not part of the syntax.
+ */
+
+/**
+ * The characters a name is spelled with. A name outside this set — a Unicode
+ * identifier, a quoted export name — reads as punctuation and so never matches
+ * `proof`, `from` or `import`, the only names looked for here.
+ *
+ * @type {(char: string) => boolean}
+ */
+const nameChar = char =>
+    (char >= 'a' && char <= 'z')
+    || (char >= 'A' && char <= 'Z')
+    || (char >= '0' && char <= '9')
+    || char === '_' || char === '$'
+
+/** @type {(char: string) => boolean} */
+const space = char => char === ' ' || char === '\t' || char === '\n' || char === '\r'
+
+/** @typedef {{ readonly kind: 'name' | 'string' | 'punctuation', readonly text: string }} _Token */
+
+/**
+ * Separates tokens while they are collected. The scan is a single pass over a
+ * whole file, so tokens accumulate as text rather than into a growing array;
+ * authored source holds no U+0000 to be mistaken for the separator.
+ */
+const separator = '\u0000'
+
+/**
+ * The source as tokens: names, the text of string literals, and single
+ * characters of punctuation. A comment produces nothing, so what is written in
+ * one is never read as code. A template produces a backtick and nothing else —
+ * it can hold an entire embedded module, and it is never a module specifier.
+ *
+ * An escape inside a string becomes a space: escapes belong to prose, and a
+ * module specifier — the only string this module reads — has none.
+ *
+ * @type {(source: string) => readonly _Token[]}
+ */
+const read = source => {
+    let out = ''
+    let index = 0
+    while (index < source.length) {
+        const char = source[index] ?? ''
+        const next = source[index + 1]
+        if (char === '/' && next === '/') {
+            while (index < source.length && source[index] !== '\n') { index += 1 }
+            continue
+        }
+        if (char === '/' && next === '*') {
+            index += 2
+            while (index < source.length
+                && !(source[index] === '*' && source[index + 1] === '/')) { index += 1 }
+            index += 2
+            continue
+        }
+        if (char === '\'' || char === '"' || char === '`') {
+            index += 1
+            let text = ''
+            while (index < source.length && source[index] !== char) {
+                if (source[index] === '\\') {
+                    text += ' '
+                    index += 2
+                    continue
+                }
+                text += source[index]
+                index += 1
+            }
+            index += 1
+            out += char === '`' ? `${separator}p\`` : `${separator}s${text}`
+            continue
+        }
+        if (nameChar(char)) {
+            let text = ''
+            while (nameChar(source[index] ?? '')) {
+                text += source[index]
+                index += 1
+            }
+            out += `${separator}n${text}`
+            continue
+        }
+        if (!space(char)) { out += `${separator}p${char}` }
+        index += 1
+    }
+    return out.split(separator).slice(1).map(token => ({
+        kind: token[0] === 'n' ? 'name' : token[0] === 's' ? 'string' : 'punctuation',
+        text: token.slice(1),
+    }))
+}
+
+/**
+ * The tokens as bare words, every string literal standing in as a quote: a
+ * declaration is read by its names, and no string can pass for one.
+ *
+ * @type {(tokens: readonly _Token[]) => readonly string[]}
+ */
+const words = tokens => tokens.map(token => token.kind === 'string' ? '\'' : token.text)
+
+/** The keywords that can introduce an `export <keyword> proof` declaration. */
+const declarations = ['const', 'let', 'var', 'function', 'class']
+
+/**
+ * Where the declared name sits relative to its keyword. `function*` declares a
+ * generator, so the name follows the star.
+ *
+ * @type {(list: readonly string[], at: number) => number}
+ */
+const declaredName = (list, at) =>
+    list[at] === 'function' && list[at + 1] === '*' ? at + 2 : at + 1
+
+/**
+ * Whether a bracketed group starting at `at` binds `proof`. A named export list
+ * and a binding pattern name what they bind the same way — the last name of an
+ * entry — so `{ implementation as proof }` and `{ value: proof }` both bind
+ * `proof`, while `{ proof as implementation }` and `{ proof: alias }` bind the
+ * other name. An unclosed group is incomplete syntax and binds nothing.
+ *
+ * @type {(list: readonly string[], at: number, close: string) => boolean}
+ */
+const groupBinds = (list, at, close) => {
+    const end = list.indexOf(close, at + 1)
+    if (end === -1) { return false }
+    return list.slice(at + 1, end)
+        .join(' ')
+        .split(',')
+        .some(item => {
+            const names = item.split(' ').filter(name => name !== '')
+            return names[names.length - 1] === 'proof'
+        })
+}
+
+/**
+ * Whether the words following an `export` bind the name `proof`: a declaration
+ * — `async`, `function*` and binding patterns included — a namespace re-export,
+ * or a named list.
+ *
+ * @type {(list: readonly string[], at: number) => boolean}
+ */
+const bindsProof = (list, at) => {
+    const head = list[at]
+    if (head === undefined) { return false }
+    // `async` modifies the declaration that follows it and binds nothing itself.
+    if (head === 'async') { return bindsProof(list, at + 1) }
+    if (declarations.includes(head)) {
+        // A declaration binds one name, or a pattern of them: the repository
+        // exports through one already — `export const { merge, get } = map`.
+        const name = declaredName(list, at)
+        const bound = list[name]
+        if (bound === '{') { return groupBinds(list, name, '}') }
+        if (bound === '[') { return groupBinds(list, name, ']') }
+        return bound === 'proof'
+    }
+    if (head === '*') { return list[at + 1] === 'as' && list[at + 2] === 'proof' }
+    return head === '{' && groupBinds(list, at, '}')
+}
+
+/**
+ * Whether `source` exports a binding named `proof`. A mention inside a comment,
+ * a string, or a template is not one — the website generator embeds the page's
+ * entry module as source text — because none of them reaches the words below.
+ *
+ * @type {(source: string) => boolean}
+ */
+export const exportsProof = source => {
+    const list = words(read(source))
+    return list.some((word, index) => word === 'export' && bindsProof(list, index + 1))
+}
+
+/**
+ * Every static module specifier in `source`: the string literal following the
+ * `from` of a declaration, or an `import` naming its module directly.
+ *
+ * A dynamic `import(...)` is left out, and left out structurally — its string
+ * follows a `(`, not the keyword. That is the reading the manifest wants: a
+ * dynamic import fails inside the test that reaches it rather than while the
+ * page links. A `from` written in prose or inside a string is left out for the
+ * same reason: neither is a sequence of tokens.
+ *
+ * @type {(source: string) => readonly string[]}
+ */
+export const specifiers = source => {
+    const tokens = read(source)
+    return tokens.flatMap((token, index) => {
+        if (token.kind !== 'string') { return [] }
+        const previous = tokens[index - 1]
+        return previous?.kind === 'name'
+            && (previous.text === 'from' || previous.text === 'import')
+            ? [token.text]
+            : []
+    })
+}
+
+/** @type {(specifier: string) => boolean} */
+export const local = specifier => specifier.startsWith('./') || specifier.startsWith('../')

package/fjs/website/browser-source.proof.d.mts

@@ -0,0 +1,31 @@
+/**
+ * Proofs for the static source reading behind the browser proof manifest.
+ *
+ * A misread here is expensive and silent: a module wrongly selected fails the
+ * generated page while it links, before the runner can publish a report, and a
+ * module wrongly skipped simply never runs in the browser.
+ */
+export declare const proof: {
+    exportsProof: {
+        declarations: () => void;
+        modifiers: () => void;
+        spacing: () => void;
+        patterns: () => void;
+        namespace: () => void;
+        namedList: () => void;
+        otherNames: () => void;
+        notCode: () => void;
+        unterminated: () => void;
+    };
+    specifiers: {
+        imports: () => void;
+        reExports: () => void;
+        compactStar: () => void;
+        notCode: () => void;
+        multiLine: () => void;
+        inText: () => void;
+        prose: () => void;
+        dynamic: () => void;
+    };
+    local: () => void;
+};

package/fjs/website/browser-source.proof.mjs

@@ -0,0 +1,162 @@
+/**
+ * Proofs for the static source reading behind the browser proof manifest.
+ *
+ * A misread here is expensive and silent: a module wrongly selected fails the
+ * generated page while it links, before the runner can publish a report, and a
+ * module wrongly skipped simply never runs in the browser.
+ */
+
+import { assert, assertStructurallySame } from '../asserts/module.f.mjs'
+import { exportsProof, local, specifiers } from './browser-source.mjs'
+
+/** @type {(source: string) => void} */
+const exports = source => assert(exportsProof(source), source)
+
+/** @type {(source: string) => void} */
+const doesNot = source => assert(!exportsProof(source), source)
+
+export const proof = {
+    exportsProof: {
+        declarations: () => {
+            exports('export const proof = {}')
+            exports('export let proof = {}')
+            exports('export var proof = {}')
+            exports('export function proof() {}')
+            exports('export class proof {}')
+        },
+        modifiers: () => {
+            // Both are zero-argument named exports the ordinary runner accepts,
+            // so the manifest has to see them too.
+            exports('export async function proof() {}')
+            exports('export function* proof() {}')
+            exports('export async function* proof() {}')
+            doesNot('export async function proofs() {}')
+            doesNot('export function* proofs() {}')
+        },
+        spacing: () => {
+            // Whitespace between the parts is not part of the syntax.
+            exports('export\n    const\n    proof = {}')
+            exports('export{ proof }')
+            exports('export {proof} from \'./x.mjs\'')
+        },
+        patterns: () => {
+            // A declaration can bind through a pattern, and the repository
+            // already exports through one: `export const { merge, get } = map`.
+            exports('export const { proof } = value')
+            exports('export const { value: proof } = source')
+            exports('export const { a, proof } = source')
+            exports('export const [proof] = source')
+            doesNot('export const { proof: alias } = source')
+            doesNot('export const { other } = source')
+        },
+        namespace: () => {
+            exports('export * as proof from \'./x.mjs\'')
+            exports('export *as proof from \'./x.mjs\'')
+            doesNot('export * from \'./x.mjs\'')
+        },
+        namedList: () => {
+            // A list entry exports the last name of its `as` chain.
+            exports('export { implementation as proof }')
+            exports('export { a, b as proof, c }')
+            doesNot('export { proof as implementation }')
+            doesNot('export { a, b }')
+        },
+        otherNames: () => {
+            // `proof` is a whole name, never a prefix of one.
+            doesNot('export const proofs = {}')
+            doesNot('export const proofOf = {}')
+            doesNot('export { proofs }')
+            doesNot('export default proof')
+        },
+        notCode: () => {
+            // The generator itself embeds a module as source text, so a mention
+            // inside a comment, a string, or a template is not an export.
+            doesNot('// export const proof = {}')
+            doesNot('/* export const proof = {} */')
+            doesNot('const source = \'export const proof = {}\'')
+            doesNot('const source = `export const proof = {}`')
+            doesNot('const source = \'export \\\' const proof = {}\'')
+        },
+        unterminated: () => {
+            // Truncated syntax answers `false` rather than running off the end.
+            doesNot('export')
+            doesNot('export const')
+            doesNot('export * as')
+            doesNot('export { a as proof')
+        },
+    },
+    specifiers: {
+        imports: () => {
+            assertStructurallySame(
+                [...specifiers('import { a } from \'./x.mjs\'\nimport \'node:fs\'\n')],
+                ['./x.mjs', 'node:fs'])
+        },
+        reExports: () => {
+            // Both spacings `exportsProof` accepts are walked for dependencies.
+            assertStructurallySame(
+                [...specifiers('export { proof } from \'./x.mjs\'\nexport{ proof } from \'./y.mjs\'\n')],
+                ['./x.mjs', './y.mjs'])
+        },
+        compactStar: () => {
+            // Every spacing the syntax allows, so a module whose dependencies
+            // are written compactly is still walked.
+            assertStructurallySame(
+                [...specifiers('export*as proof from \'node:fs\'\nimport*as dep from \'package\'\n')],
+                ['node:fs', 'package'])
+        },
+        notCode: () => {
+            // An embedded code sample is not a dependency: a proof read this
+            // way would be dropped from the suite as unlinkable.
+            assertStructurallySame(
+                [...specifiers('/*\nimport \'node:fs\'\n*/\n')],
+                [])
+            assertStructurallySame(
+                [...specifiers('const sample = `\nimport \'node:fs\'\n`\n')],
+                [])
+        },
+        multiLine: () => {
+            // Line boundaries are not part of the syntax, wherever they fall.
+            assertStructurallySame(
+                [...specifiers('import {\n    a,\n} from \'./x.mjs\'\n')],
+                ['./x.mjs'])
+            assertStructurallySame(
+                [...specifiers('import\n\'node:fs\'\n')],
+                ['node:fs'])
+            assertStructurallySame(
+                [...specifiers('export { a }\nfrom\n\'package\'\n')],
+                ['package'])
+        },
+        inText: () => {
+            // A `from` inside prose or a string literal is not a declaration.
+            assertStructurallySame(
+                [...specifiers('const s = "tells \'empty\' from \'missing\'"\n')],
+                [])
+            assertStructurallySame(
+                [...specifiers('// import \'node:fs\'\n')],
+                [])
+            // Including when the prose trails a declaration that is real: a
+            // module blocked by its own comment would be dropped in silence.
+            assertStructurallySame(
+                [...specifiers('import \'./ok.mjs\' // import \'node:fs\'\n')],
+                ['./ok.mjs'])
+        },
+        prose: () => {
+            // A documentation line quoting names is not an import declaration.
+            assertStructurallySame(
+                [...specifiers(' * tells `\'empty\'` from `\'missing\'`\n')],
+                [])
+        },
+        dynamic: () => {
+            // Only what the browser links eagerly counts.
+            assertStructurallySame(
+                [...specifiers('const m = await import(\'./x.mjs\')\n')],
+                [])
+        },
+    },
+    local: () => {
+        assert(local('./x.mjs'))
+        assert(local('../x.mjs'))
+        assert(!local('node:fs'))
+        assert(!local('functionalscript/x.mjs'))
+    },
+}

package/fjs/website/browser.d.mts

@@ -0,0 +1,5 @@
+/** Browser-realm smoke proof for the generated website. */
+export declare const proof: {
+    window: () => void;
+    document: () => void;
+};

package/fjs/website/browser.mjs

@@ -0,0 +1,8 @@
+/** Browser-realm smoke proof for the generated website. */
+
+import { assert } from '../asserts/module.f.mjs'
+
+export const proof = {
+    window: () => assert(window.document === document),
+    document: () => assert(document.documentElement.localName === 'html'),
+}

package/fjs/website/module.f.d.mts

@@ -3,9 +3,9 @@
  *
  * @module
  *
- * @import { Write, WriteFile } from '../effects/node/types.ts'
+ * @import { All, Write, WriteFile } from '../effects/node/types.ts'
  * @import { Effect } from '../effects/types.ts'
  */
-import type { Write, WriteFile } from '../effects/node/types.ts';
+import type { All, Write, WriteFile } from '../effects/node/types.ts';
 import type { Effect } from '../effects/types.ts';
-export declare const main: () => Effect<Write | WriteFile, 0, number>;
+export declare const main: () => Effect<All | Write | WriteFile, 0, number>;

package/fjs/website/module.f.mjs

@@ -3,20 +3,73 @@
  *
  * @module
  *
- * @import { Write, WriteFile } from '../effects/node/types.ts'
+ * @import { All, Write, WriteFile } from '../effects/node/types.ts'
  * @import { Effect } from '../effects/types.ts'
  */
 
 import { htmlUtf8 } from '../media/html/module.f.mjs'
-import { exitStep, writeFile } from '../effects/node/module.f.mjs'
+import { utf8 } from '../text/module.f.mjs'
+import { allOk, exitStep, writeFile } from '../effects/node/module.f.mjs'
+import { mapStep } from '../effects/module.f.mjs'
 
-const html = htmlUtf8()(
-    ['a',
-        { href: 'https://github.com/functionalscript/functionalscript' },
-        'GitHub Repository'
-    ])
+const html = htmlUtf8(
+    ['title', 'Emergent Testing in the Browser'],
+    ['style', `
+:root { color-scheme: light dark; --bg: white; --text: black; --pass: #137333; --fail: #b3261e }
+@media (prefers-color-scheme: dark) {
+    :root { --bg: #121212; --text: #f1f1f1; --pass: #81c995; --fail: #f28b82 }
+}
+body { background-color: var(--bg); color: var(--text); font: 16px system-ui; margin: 3rem auto; max-width: 48rem; padding: 0 1rem }
+[data-state="passed"] [data-test-summary] { color: var(--pass) }
+[data-state="failed"] [data-test-summary], [data-state="infrastructure-error"] [data-test-summary] { color: var(--fail) }
+[data-test-results] { color: var(--text) }
+[data-status="passed"]::marker { color: var(--pass) }
+[data-status="failed"] { color: var(--fail) }
+pre { white-space: pre-wrap }
+`]
+)(
+    ['main', { 'data-browser-tests': '', 'data-state': 'loading' },
+        ['p', ['a',
+            { href: 'https://github.com/functionalscript/functionalscript' },
+            'GitHub Repository'
+        ]],
+        ['h1', 'Emergent Testing in the Browser'],
+        ['p',
+            'FunctionalScript derives this browser-native unit-test suite from exported proofs. ',
+            ['a',
+                { href: 'https://medium.com/javascript-in-plain-english/emergent-testing-in-javascript-e44760d71688' },
+                'Read “Emergent Testing in JavaScript”'
+            ],
+            '.'
+        ],
+        ['p', { 'data-test-summary': '' }, 'Loading…'],
+        ['button', { type: 'button', 'data-test-run': '' }, 'Run again'],
+        ['pre', ['ol', { 'data-test-results': '' }]]
+    ],
+    ['script', { type: 'module', src: './_browser-test-entry.mjs' }]
+)
 
-/** @type {Effect<WriteFile | Write, 0, number>} */
-const program = exitStep(writeFile('index.html', html))
+const entry = utf8(`import { startBrowserTestSources } from './fjs/emergent_testing/browser.mjs'
+import { browserProofSources } from './fjs/emergent_testing/_browser-suite.mjs'
+
+const root = /** @type {Element} */ (document.querySelector('[data-browser-tests]'))
+const sources = [...browserProofSources, './fjs/website/browser.mjs']
+const runButton = /** @type {Element} */ (document.querySelector('[data-test-run]'))
+const start = () => {
+    runButton.setAttribute('disabled', '')
+    return startBrowserTestSources(root, sources, source => import(source)).then(report => {
+        runButton.removeAttribute('disabled')
+        return report
+    })
+}
+runButton.addEventListener('click', start)
+if (new URL(location.href).searchParams.get('run') !== 'false') { start() }
+`)
+
+/** @type {Effect<WriteFile | Write | All, 0, number>} */
+const program = exitStep(mapStep(allOk(
+    writeFile('index.html', html),
+    writeFile('_browser-test-entry.mjs', entry)
+), () => undefined))
 
 export const main = () => program

package/fjs/website/proof.f.d.mts

@@ -1,3 +1,7 @@
+/**
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ */
 export declare const proof: {
     main: () => void;
     run: () => void;

package/fjs/website/proof.f.mjs

@@ -1,15 +1,30 @@
+/**
+ * @import { Dir } from '../effects/node/virtual/types.ts'
+ * @import { Vec } from '../types/bit_vec/types.ts'
+ */
+
 import { exitCode } from '../effects/node/module.f.mjs'
 import { main } from './module.f.mjs'
 import { emptyState, virtual } from '../effects/node/virtual/module.f.mjs'
-import { assertEq, assertNotNullish } from '../asserts/module.f.mjs'
+import { assert, assertEq, assertNotNullish } from '../asserts/module.f.mjs'
+import { utf8ToString } from '../text/module.f.mjs'
 
 export const proof = {
     main: () => {
         assertNotNullish(main(), 'expected a program effect')
     },
     run: () => {
-        const state = { ...emptyState, root: { '.github': { workflows: {} } } }
-        const [_, result] = virtual(state)(main())
+        /** @type {Dir} */
+        const root = { '.github': { workflows: {} } }
+        const state = { ...emptyState, root }
+        const [generated, result] = virtual(state)(main())
         assertEq(exitCode(result), 0)
+        const page = assertNotNullish(generated.root['index.html'], 'expected generated HTML')
+        assertNotNullish(generated.root['_browser-test-entry.mjs'], 'expected generated entry module')
+        assert(Array.isArray(page), 'expected the generated HTML to be a file')
+        const source = page.map(value => utf8ToString(/** @type {Vec} */ (value))).join('')
+        assert(source.includes('<h1>Emergent Testing in the Browser</h1>'))
+        assert(source.includes('emergent-testing-in-javascript-e44760d71688'))
+        assert(!source.includes('?sk='))
     },
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "functionalscript",
-  "version": "0.46.0",
+  "version": "0.47.0",
   "type": "module",
   "files": [
     "**/*.js",
@@ -17,8 +17,7 @@
     "ci-update": "node ./fjs/module.mjs ci && node ./fjs/module.mjs r ./fjs/nanvm/update/module.f.mjs",
     "dev-update": "node ./fjs/module.mjs r ./fjs/dev/update/module.f.mjs",
     "update": "npm run ci-update && npm install && deno install && bun install",
-    "index-html": "node ./fjs/module.mjs r ./fjs/website/module.f.mjs",
-    "website": "npm run prepack && npm run index-html"
+    "website": "node ./fjs/website/browser-prepare.mjs"
   },
   "engines": {
     "node": ">=22"