@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/furnace/scaffold.js

@@ -0,0 +1,311 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * What `furnace create` writes: a component's sources, and optionally a test
+ * in one of three harnesses. A test scaffold is described once, as data, and
+ * the same description is written by create, moved by rename and taken away
+ * by remove. Where the test is registered (its manifest, and the moz.build
+ * that lists a new manifest) is `register`'s policy.
+ */
+import { posix } from 'node:path';
+import { escapeRegExp } from '../kernel/text.js';
+import { findMozBuildLists, listTests, mozBuildTestManifests, removeFromMozBuildList, removeTest, } from '../mozbuild/index.js';
+import { licenseHeader } from '../project/index.js';
+import { applyEdits, planRegister } from '../register/index.js';
+import { className, ELEMENTS_URL } from './config.js';
+/**
+ * The sources of a new custom component, by file name. The module loads its
+ * Fluent resource through `MozXULElement.insertFTLIfNeeded` at module level,
+ * since `MozLitElement` has no such method and already connects its shadow
+ * root to `document.l10n`.
+ *
+ * @param template - The component
+ */
+export function componentSources(template) {
+    const { name, license, ftl } = template;
+    const cls = className(name);
+    const doc = (template.description || name).replace(/\*\//g, '*\\/');
+    const fluent = ftl === undefined ? '' : `\nwindow.MozXULElement?.insertFTLIfNeeded(${JSON.stringify(ftl)});\n`;
+    const sources = new Map([
+        [
+            `${name}.mjs`,
+            `${licenseHeader(license, 'js')}
+
+import { html } from "chrome://global/content/vendor/lit.all.mjs";
+import { MozLitElement } from "chrome://global/content/lit-utils.mjs";
+${fluent}
+/**
+ * ${doc}
+ *
+ * @tagname ${name}
+ */
+export default class ${cls} extends MozLitElement {
+  /** @type {Record<string, unknown>} */
+  static properties = {};
+
+  render() {
+    return html\`
+      <link rel="stylesheet" href="${ELEMENTS_URL}${name}.css" />
+      <slot></slot>
+    \`;
+  }
+}
+customElements.define("${name}", /** @type {CustomElementConstructor} */ (${cls}));
+`,
+        ],
+        [`${name}.css`, `${licenseHeader(license, 'css')}\n\n:host {\n  display: block;\n}\n`],
+    ]);
+    if (template.ownFtl) {
+        sources.set(`${name}.ftl`, `${licenseHeader(license, 'hash')}\n\n## Strings of the ${name} component\n`);
+    }
+    return sources;
+}
+/** The test harnesses a component can be created with. */
+export const TEST_STYLES = ['browser-chrome', 'mochikit', 'xpcshell'];
+/** `moz-mybrowser-sidebar` in a project named `mybrowser` is `sidebar`. */
+function testStem(name, binaryName) {
+    const bare = name.startsWith('moz-') ? name.slice(4) : name;
+    const own = bare.startsWith(`${binaryName}-`) ? bare.slice(binaryName.length + 1) : bare;
+    return own.replace(/-/g, '_');
+}
+/**
+ * A component's test scaffold in one harness.
+ *
+ * - browser-chrome: `browser/base/content/test/<binary>/browser_<binary>_<stem>.js`,
+ *   needs a tabbrowser in the top-level chrome document.
+ * - mochikit: `toolkit/content/tests/widgets/test_<name>.html`, for forks whose
+ *   chrome document has no tabbrowser.
+ * - xpcshell: checks the files reached the packaged tree; xpcshell has no
+ *   `window`, so a Lit module cannot be imported there.
+ *
+ * @param name - The component
+ * @param binaryName - The project's binary name
+ * @param style - The harness
+ * @param license - The header the files carry
+ */
+export function testScaffold(name, binaryName, style, license) {
+    const js = licenseHeader(license, 'js');
+    const fn = name.replace(/-/g, '_');
+    if (style === 'browser-chrome') {
+        const dir = `browser/base/content/test/${binaryName}`;
+        const file = `browser_${binaryName}_${testStem(name, binaryName)}.js`;
+        return {
+            style,
+            test: {
+                path: `${dir}/${file}`,
+                content: `${js}
+
+"use strict";
+
+add_task(async function test_${fn}_defined() {
+  const ctor = await waitForElement("${name}");
+  Assert.ok(ctor, "${name} custom element should be defined");
+  Assert.equal(typeof ctor, "function", "Constructor should be a function");
+});
+`,
+            },
+            support: {
+                path: `${dir}/head.js`,
+                content: `${js}
+
+"use strict";
+
+/**
+ * Waits for a custom element to be defined.
+ * @param {string} tag - Custom element tag name
+ * @returns {Promise<CustomElementConstructor>}
+ */
+async function waitForElement(tag) {
+  document.createElement(tag);
+  return customElements.whenDefined(tag);
+}
+`,
+            },
+            defaults: { 'support-files': ['head.js'] },
+        };
+    }
+    if (style === 'mochikit') {
+        const dir = 'toolkit/content/tests/widgets';
+        const file = `test_${name}.html`;
+        return {
+            style,
+            test: {
+                path: `${dir}/${file}`,
+                content: `<!DOCTYPE html>
+<html>
+  <head>
+    <meta charset="utf-8" />
+    <title>Test the ${name} custom element</title>
+    <script src="chrome://mochikit/content/tests/SimpleTest/SimpleTest.js"></script>
+    <link rel="stylesheet" href="chrome://mochikit/content/tests/SimpleTest/test.css" />
+  </head>
+  <body>
+    <script type="module">
+      import "${ELEMENTS_URL}${name}.mjs";
+
+      add_task(async function test_${fn}_defined() {
+        const ctor = await customElements.whenDefined("${name}");
+        ok(ctor, "${name} custom element should be defined");
+        is(typeof ctor, "function", "Constructor should be a function");
+      });
+    </script>
+  </body>
+</html>
+`,
+            },
+            manifest: 'chrome.toml',
+        };
+    }
+    return xpcshellScaffold(name, binaryName, js);
+}
+function xpcshellScaffold(name, binaryName, js) {
+    const fn = name.replace(/-/g, '_');
+    const dir = `browser/base/content/test/${binaryName}-xpcshell/${name}`;
+    const file = `test_${fn}_packaged.js`;
+    const probe = (ext) => `  probe(["chrome", "global", "elements", "${name}.${ext}"], ["browser", "chrome", "global", "elements", "${name}.${ext}"]);`;
+    return {
+        style: 'xpcshell',
+        test: {
+            path: `${dir}/${file}`,
+            content: `${js}
+
+"use strict";
+
+// The module imports Lit, which needs a window that xpcshell lacks, so this
+// test checks that the files reached the unpacked build; behaviour belongs
+// in a browser-chrome test.
+
+add_task(async function test_${fn}_files_packaged() {
+  const appDir = Services.dirsvc.get("XCurProcD", Ci.nsIFile);
+  function probe(primary, fallback) {
+    const candidates = [primary, fallback].map(segments => {
+      const file = appDir.clone();
+      for (const segment of segments) {
+        file.append(segment);
+      }
+      return file;
+    });
+    const found = candidates.find(file => file.exists());
+    Assert.ok(found, \`\${primary.at(-1)} is packaged (looked in \${candidates.map(file => file.path).join(" and ")})\`);
+    Assert.greater(found.fileSize, 0, \`\${primary.at(-1)} is not empty\`);
+  }
+${probe('mjs')}
+${probe('css')}
+});
+`,
+        },
+        defaults: { head: '' },
+    };
+}
+/** The test manifest a scaffold's test is listed in. */
+function manifestOf(scaffold) {
+    const dir = posix.dirname(scaffold.test.path);
+    const name = scaffold.manifest ?? (scaffold.style === 'xpcshell' ? 'xpcshell.toml' : 'browser.toml');
+    return `${dir}/${name}`;
+}
+/**
+ * Writes a test scaffold and registers its test: in its manifest, created
+ * and wired into a moz.build when missing. An existing test or support file
+ * is kept.
+ *
+ * @param tracked - The project's tracked engine files
+ * @param tx - The transaction the writes join
+ * @param scaffold - What to write
+ * @param project - The module directory and license
+ * @returns Notes for the operator: files kept, and the registrations made
+ */
+export async function writeTestScaffold(tracked, tx, scaffold, project) {
+    const notes = [];
+    for (const file of [scaffold.test, scaffold.support]) {
+        if (file === undefined)
+            continue;
+        if ((await tracked.read(file.path)) === undefined)
+            await tracked.write(tx, file.path, file.content);
+        else if (file === scaffold.test)
+            notes.push(`${file.path} already exists and was kept.`);
+    }
+    const plan = await planRegister(tracked, {
+        path: scaffold.test.path,
+        moduleDir: project.moduleDir,
+        license: project.license,
+        createManifest: true,
+        ...(scaffold.manifest === undefined ? {} : { testManifest: scaffold.manifest }),
+        ...(scaffold.defaults === undefined ? {} : { manifestDefaults: scaffold.defaults }),
+    });
+    await applyEdits(tx, tracked, plan.edits);
+    notes.push(...plan.steps
+        .filter((step) => !step.present)
+        .map((step) => `Registered in ${step.path}: ${step.change}`));
+    return notes;
+}
+/**
+ * Takes a test scaffold away: the test file, its manifest entry, and the
+ * manifest and its moz.build entry once no test is left in it. A shared
+ * support file stays.
+ *
+ * @param tracked - The project's tracked engine files
+ * @param tx - The transaction the edits join
+ * @param scaffold - The scaffold
+ * @returns Whether the scaffold's test existed
+ */
+export async function removeTestScaffold(tracked, tx, scaffold) {
+    const existed = (await tracked.read(scaffold.test.path)) !== undefined;
+    if (existed)
+        await tracked.remove(tx, scaffold.test.path);
+    const manifest = manifestOf(scaffold);
+    const text = await tracked.read(manifest);
+    if (text === undefined)
+        return existed;
+    const edited = removeTest(manifest, text, posix.basename(scaffold.test.path));
+    // Only the xpcshell manifest belongs to one component; the others are shared by a directory.
+    if (scaffold.style !== 'xpcshell' || listTests(manifest, edited.text).length > 0) {
+        if (edited.changed)
+            await tracked.write(tx, manifest, edited.text);
+        return existed;
+    }
+    await tracked.remove(tx, manifest);
+    for (let dir = posix.dirname(manifest); dir !== '.'; dir = posix.dirname(dir)) {
+        const owner = `${dir}/moz.build`;
+        const build = await tracked.read(owner);
+        const listed = build === undefined
+            ? undefined
+            : mozBuildTestManifests(owner, build).find((entry) => entry.path === manifest);
+        if (build === undefined || listed === undefined)
+            continue;
+        const list = findMozBuildLists(build, listed.variable, { conditional: true }).find((candidate) => candidate.items.some((item) => item.value === listed.value));
+        const dropped = removeFromMozBuildList(build, listed.variable, listed.value, {
+            line: list?.startLine ?? -1,
+        });
+        if (dropped.changed)
+            await tracked.write(tx, owner, dropped.text);
+        break;
+    }
+    return existed;
+}
+/**
+ * Text with the mentions of a tag replaced, for moving a component or its
+ * test to a new name. Three spellings are mentions:
+ *
+ *  - the tag (`moz-panel`) and its class name (`MozPanel`), as whole words:
+ *    `moz-panel-group` and `MozPanelGroup` name another component;
+ *  - the tag with underscores (`moz_panel`), which identifiers are built
+ *    from by appending `_<what>` (`test_moz_panel_defined`). A word boundary
+ *    cannot tell that from another component's identifier
+ *    (`test_moz_panel_group_defined`), so the longer tags the project knows
+ *    are named in `others` and their identifiers are left alone.
+ *
+ * @param text - Source text
+ * @param from - The old tag
+ * @param to - The new tag
+ * @param others - The other component tags of the project
+ */
+export function renameTag(text, from, to, others = []) {
+    const snake = (tag) => tag.replace(/-/g, '_');
+    const longer = others
+        .filter((tag) => tag.startsWith(`${from}-`))
+        .map((tag) => escapeRegExp(snake(tag).slice(snake(from).length)));
+    const notLonger = longer.length === 0 ? '' : `(?!(?:${longer.join('|')})(?![a-z0-9]))`;
+    return text
+        .replace(new RegExp(`(?<![\\w-])${escapeRegExp(from)}(?![\\w-])`, 'g'), to)
+        .replace(new RegExp(`\\b${escapeRegExp(className(from))}\\b`, 'g'), className(to))
+        .replace(new RegExp(`(?<![a-z0-9])${escapeRegExp(snake(from))}(?![a-z0-9])${notLonger}`, 'g'), snake(to));
+}

package/dist/src/furnace/typing.js

@@ -0,0 +1,252 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The typing files Furnace generates from the components, so code that
+ * imports a component module or creates its element is typed:
+ *
+ * - `typecheckJsconfig`: in each named jsconfig, a `compilerOptions.paths`
+ *   entry per component module, mapping its chrome URL to the source in
+ *   `components/custom/`. Furnace manages only entries under the elements
+ *   URL that point into `components/custom/`; every other entry is the
+ *   jsconfig owner's and is kept.
+ * - `typecheckTagMap`: a declaration adding each registered element whose
+ *   module exports its class to `HTMLElementTagNameMap`. Furnace owns the
+ *   whole file.
+ *
+ * A path starting `engine/` names the project's tracked copy of that engine
+ * file; any other path is relative to the project root.
+ */
+import { dirname, join, relative, resolve } from 'node:path';
+import { isInside, listDir, readTextIfExists, toPosixPath } from '../kernel/fs.js';
+import { isRecord, parseJson } from '../kernel/json.js';
+import { editJsonText } from '../kernel/json-edit.js';
+import { configuredPath } from '../project/index.js';
+import { isStringLiteral, parseJs, walkJs } from '../syntax/index.js';
+import { componentDir, ELEMENTS_URL, furnaceError, jsconfigPaths, } from './config.js';
+async function locate(project, tracked, file) {
+    const named = configuredPath(file);
+    if (named.tree === 'engine') {
+        return { absolute: tracked.locate(named.path), current: await tracked.read(named.path) };
+    }
+    const absolute = join(project.paths.root, named.path);
+    return { absolute, current: await readTextIfExists(absolute) };
+}
+/** The `.mjs` files of each custom component, by component. */
+async function componentModules(project, config, include) {
+    const modules = [];
+    for (const name of Object.keys(config.custom).filter(include)) {
+        const dir = componentDir(project, 'custom', name);
+        const files = (await listDir(dir))
+            .filter((entry) => entry.kind === 'file' && entry.name.endsWith('.mjs'))
+            .map((entry) => entry.name);
+        modules.push({ name, dir, files });
+    }
+    return modules;
+}
+async function jsconfigFile(project, config, tracked, file) {
+    const { absolute, current } = await locate(project, tracked, file);
+    const document = current === undefined ? undefined : parseJson(current, { source: file });
+    if (current === undefined || !isRecord(document)) {
+        throw furnaceError('furnace-jsconfig-invalid', `furnace.json "typecheckJsconfig" names ${file}, which ${current === undefined ? 'does not exist' : 'is not a JSON object'}.`, {
+            hint: 'Create the jsconfig (Furnace maintains only its component paths), or remove the setting.',
+        });
+    }
+    const base = dirname(absolute);
+    const customRoot = join(project.paths.components, 'custom');
+    const wanted = new Map();
+    for (const { dir, files } of await componentModules(project, config, () => true)) {
+        for (const name of files) {
+            const path = toPosixPath(relative(base, join(dir, name)));
+            wanted.set(`${ELEMENTS_URL}${name}`, path.startsWith('.') ? path : `./${path}`);
+        }
+    }
+    const options = isRecord(document['compilerOptions']) ? document['compilerOptions'] : {};
+    const paths = isRecord(options['paths']) ? options['paths'] : {};
+    const next = {};
+    const changes = [];
+    for (const [key, value] of Object.entries(paths)) {
+        const target = Array.isArray(value) && value.length === 1 ? value[0] : undefined;
+        const managed = key.startsWith(ELEMENTS_URL) &&
+            typeof target === 'string' &&
+            isInside(customRoot, resolve(base, target)) &&
+            resolve(base, target) !== customRoot;
+        const want = wanted.get(key);
+        if (!managed || want === undefined) {
+            if (managed)
+                changes.push(`orphaned ${key}`);
+            else
+                next[key] = value;
+            continue;
+        }
+        const same = resolve(base, target) === resolve(base, want);
+        if (!same)
+            changes.push(`stale ${key}`);
+        next[key] = same ? value : [want];
+    }
+    for (const [key, want] of wanted) {
+        if (next[key] !== undefined)
+            continue;
+        next[key] = [want];
+        changes.push(`missing ${key}`);
+    }
+    if (changes.length === 0)
+        return { file, absolute, current, next: current, detail: '' };
+    const edited = { ...document, compilerOptions: { ...options, paths: next } };
+    const text = editJsonText(current, edited);
+    if (text === undefined) {
+        throw furnaceError('furnace-jsconfig-invalid', `${file} could not be edited in place.`);
+    }
+    return { file, absolute, current, next: text, detail: changes.join('; ') };
+}
+/** `customElements.define("tag", Class)` calls of a module, autonomous elements only. */
+function definedElements(program) {
+    const defined = new Map();
+    walkJs(program, (node) => {
+        if (node.type !== 'CallExpression' || node.callee.type !== 'MemberExpression')
+            return;
+        const { object, property } = node.callee;
+        const receiver = object.type === 'Identifier'
+            ? object.name
+            : object.type === 'MemberExpression' && object.property.type === 'Identifier'
+                ? object.property.name
+                : undefined;
+        if (receiver !== 'customElements' ||
+            property.type !== 'Identifier' ||
+            property.name !== 'define') {
+            return;
+        }
+        const [tag, cls, options] = node.arguments;
+        const builtIn = options?.type === 'ObjectExpression' &&
+            options.properties.some((entry) => entry.type === 'Property' &&
+                ((entry.key.type === 'Identifier' && entry.key.name === 'extends') ||
+                    (entry.key.type === 'Literal' && entry.key.value === 'extends')));
+        if (isStringLiteral(tag) && cls?.type === 'Identifier' && !builtIn) {
+            defined.set(tag.value, cls.name);
+        }
+    });
+    return defined;
+}
+/** The name each exported local binding is exported under; a named export wins over `default`. */
+function exportedNames(program) {
+    const named = new Map();
+    const defaults = new Map();
+    for (const statement of program.body) {
+        if (statement.type === 'ExportNamedDeclaration' && statement.source == null) {
+            if (statement.declaration?.type === 'ClassDeclaration') {
+                named.set(statement.declaration.id.name, statement.declaration.id.name);
+            }
+            for (const specifier of statement.specifiers) {
+                if (specifier.local.type !== 'Identifier' || named.has(specifier.local.name))
+                    continue;
+                const exported = specifier.exported;
+                named.set(specifier.local.name, exported.type === 'Identifier' ? exported.name : String(exported.value));
+            }
+        }
+        else if (statement.type === 'ExportDefaultDeclaration') {
+            const declaration = statement.declaration;
+            const local = declaration.type === 'ClassDeclaration'
+                ? declaration.id?.name
+                : declaration.type === 'Identifier'
+                    ? declaration.name
+                    : undefined;
+            if (local !== undefined)
+                defaults.set(local, 'default');
+        }
+    }
+    for (const [local, name] of defaults)
+        if (!named.has(local))
+            named.set(local, name);
+    return named;
+}
+async function tagMapEntries(project, config) {
+    const entries = [];
+    const registered = (name) => {
+        const entry = config.custom[name];
+        return entry !== undefined && entry.register && entry.kind !== 'library';
+    };
+    for (const { dir, files } of await componentModules(project, config, registered)) {
+        for (const file of files) {
+            const source = await readTextIfExists(join(dir, file));
+            let program;
+            try {
+                program = parseJs(source ?? '', 'module').program;
+            }
+            catch {
+                continue; // A module that does not parse is validation's finding, not a typing entry.
+            }
+            const exported = exportedNames(program);
+            for (const [tag, cls] of definedElements(program)) {
+                const exportName = exported.get(cls);
+                if (exportName !== undefined)
+                    entries.push({ tag, module: `${ELEMENTS_URL}${file}`, exportName });
+            }
+        }
+    }
+    return entries.sort((a, b) => (a.tag < b.tag ? -1 : a.tag > b.tag ? 1 : 0));
+}
+function renderTagMap(entries) {
+    const members = entries.map((entry) => {
+        const member = /^[A-Za-z_$][\w$]*$/.test(entry.exportName)
+            ? `.${entry.exportName}`
+            : `[${JSON.stringify(entry.exportName)}]`;
+        return `  ${JSON.stringify(entry.tag)}: HTMLElement & import(${JSON.stringify(entry.module)})${member};`;
+    });
+    return [
+        '// Generated by FireForge from furnace.json (typecheckTagMap). Do not edit:',
+        '// fireforge furnace types rewrites it, and furnace validate reports drift.',
+        'interface HTMLElementTagNameMap {',
+        ...members,
+        '}',
+        '',
+    ].join('\n');
+}
+async function typingFiles(project, config, tracked) {
+    const files = [];
+    for (const file of jsconfigPaths(config))
+        files.push(await jsconfigFile(project, config, tracked, file));
+    if (config.typecheckTagMap !== undefined) {
+        const file = config.typecheckTagMap;
+        const { absolute, current } = await locate(project, tracked, file);
+        const next = renderTagMap(await tagMapEntries(project, config));
+        const detail = current === undefined ? 'the file does not exist' : 'custom element definitions changed';
+        files.push({ file, absolute, current, next, detail });
+    }
+    return files;
+}
+/**
+ * The generated typing files that are out of date.
+ *
+ * @param project - The project
+ * @param config - Its configuration
+ * @param tracked - The project's tracked engine files
+ * @throws `furnace-jsconfig-invalid` when a named jsconfig is missing or not plain JSON
+ */
+export async function typingDrift(project, config, tracked) {
+    return (await typingFiles(project, config, tracked))
+        .filter((file) => file.next !== file.current)
+        .map(({ file, detail }) => ({ file, detail }));
+}
+/**
+ * Brings the generated typing files up to date as part of a transaction.
+ *
+ * @param project - The project
+ * @param config - The configuration as it will be once the transaction commits
+ * @param tracked - The project's tracked engine files
+ * @param tx - The transaction the writes join
+ * @returns The files written
+ */
+export async function writeTypingFiles(project, config, tracked, tx) {
+    const written = [];
+    for (const file of await typingFiles(project, config, tracked)) {
+        if (file.next === file.current)
+            continue;
+        const named = configuredPath(file.file);
+        if (named.tree === 'engine') {
+            await tracked.write(tx, named.path, file.next);
+        }
+        else {
+            await tx.write(file.absolute, file.next);
+        }
+        written.push(file.file);
+    }
+    return written;
+}