@heroiclands/package-build 0.1.0

package/manifest.mjs

@@ -0,0 +1,223 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Building the Foundry package manifest — `system.json` or `module.json`.
+ *
+ * Foundry defines exactly two package kinds, and a repository is one of them,
+ * so there is one job here with two spellings: read the repository's manifest
+ * *template*, stamp the facts that must not be transcribed, and write the
+ * result into the build stage.
+ *
+ * **The stamped fields are the ones a human copy rots.** A manifest carries the
+ * version, the repository addresses, and the two release URLs Foundry fetches
+ * to check for and install an update. Every one of them is already stated
+ * somewhere that owns it — `package.json` — and a second, hand-maintained copy
+ * in the template drifts the moment a release is cut. `sohl-kethira-basic`
+ * hand-maintains its whole `module.json`, and its `download` still names an
+ * older version than the module claims.
+ *
+ * **Nothing here invents an address.** The repository URL is read from
+ * `package.json`'s `repository` field, normalised, and everything else is
+ * derived from it. A manifest that advertised another package's URLs would send
+ * Foundry to the wrong release on every update check — which is exactly what a
+ * template copied between repositories produces.
+ *
+ * The rules are pure functions over data. I/O is confined to
+ * {@link writeFoundryManifest}, which is the only export that touches disk.
+ *
+ * @module
+ */
+
+import fs from "node:fs/promises";
+import path from "node:path";
+
+/**
+ * The two package kinds Foundry defines, as the artifact name each one's
+ * manifest and release archive are called.
+ *
+ * A system ships `system.json` / `system.zip`; a module ships `module.json` /
+ * `module.zip`. Foundry fetches those exact names, so the pair is not a naming
+ * convention this project is free to choose.
+ */
+export const ARTIFACTS = Object.freeze(["system", "module"]);
+
+/**
+ * Which artifact a template file builds.
+ *
+ * Inferred from the template's own name so the usual case takes no
+ * configuration: a repository that ships `system.template.json` is a system,
+ * and one that ships `module.template.json` is a module. That is the same pair
+ * `@heroiclands/content-build` resolves a package manifest from, so the two
+ * cannot disagree about what a repository is.
+ *
+ * @param {string} templatePath - Path to the manifest template.
+ * @returns {"system"|"module"} The artifact name.
+ * @throws {TypeError} When the name identifies neither kind — a template called
+ *   something else leaves nothing to infer from, and guessing would silently
+ *   emit a manifest Foundry never looks for.
+ */
+export function artifactFromTemplate(templatePath) {
+    const base = path.basename(String(templatePath ?? ""));
+    const artifact = ARTIFACTS.find((a) => base.startsWith(`${a}.`));
+    if (!artifact) {
+        throw new TypeError(
+            `Cannot tell whether "${base}" builds a system or a module. ` +
+                `Name it system.template.json or module.template.json, or pass ` +
+                `\`artifact\` explicitly.`,
+        );
+    }
+    return artifact;
+}
+
+/**
+ * The repository's web address, from whatever spelling `package.json` carries.
+ *
+ * npm accepts several: a plain `https://` URL, the `git+https://…​.git` form npm
+ * itself writes, and a trailing slash either way. Foundry fetches
+ * `<url>/releases/latest/download/<artifact>.json` literally, so a `git+` prefix
+ * or a `.git` suffix left in place yields a 404 on every update check — with no
+ * error anywhere, because nothing fetches that URL until a user's Foundry does.
+ * `sohl-kethira-basic` declares the `git+…​.git` form today.
+ *
+ * @param {string|{url?: string}} repository - `package.json`'s `repository`
+ *   field, in either object or shorthand-string form.
+ * @returns {string} The normalised `https://` URL, with no trailing slash.
+ * @throws {TypeError} When no URL can be read. A manifest with no addresses is
+ *   worse than a missing one: Foundry installs it and never offers an update.
+ */
+export function normalizeRepoUrl(repository) {
+    const raw =
+        typeof repository === "string" ? repository : (repository?.url ?? "");
+    const url = String(raw)
+        .trim()
+        .replace(/^git\+/, "")
+        .replace(/\.git$/, "")
+        .replace(/\/+$/, "");
+    if (!url) {
+        throw new TypeError(
+            "package.json declares no `repository.url`, so the manifest has no " +
+                "release addresses to advertise. Add it.",
+        );
+    }
+    return url;
+}
+
+/**
+ * The four addresses a Foundry manifest advertises.
+ *
+ * `manifest` deliberately points at **`releases/latest`** rather than at this
+ * version: it is the URL an *installed* package re-fetches to discover that a
+ * newer one exists, so pinning it to the version being built would freeze every
+ * install at that release forever. `download` points at this exact version,
+ * because that is the archive this manifest describes.
+ *
+ * @param {object} opts
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {string} opts.version - The version being built.
+ * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
+ * @returns {{url: string, bugs: string, manifest: string, download: string}}
+ */
+export function releaseUrls({ repoUrl, version, artifact }) {
+    return {
+        url: repoUrl,
+        bugs: `${repoUrl}/issues`,
+        manifest: `${repoUrl}/releases/latest/download/${artifact}.json`,
+        download: `${repoUrl}/releases/download/v${version}/${artifact}.zip`,
+    };
+}
+
+/**
+ * Stamp a manifest template with the facts that must not be transcribed.
+ *
+ * Pure: the template is not mutated, and the result is a new object.
+ *
+ * `flags` is merged **per namespace**, not wholesale, so a template may carry
+ * its own keys under the same namespace and keep them. A caller supplies
+ * whatever its package needs there — the credits journal's UUID, the settings
+ * sidebar's links — because those are facts about one package, not about being
+ * a Foundry package.
+ *
+ * @param {object} template - The parsed manifest template.
+ * @param {object} opts
+ * @param {string} opts.version - The version being built.
+ * @param {string} opts.repoUrl - Normalised repository URL.
+ * @param {"system"|"module"} opts.artifact - Which artifact is shipped.
+ * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
+ * @returns {object} The stamped manifest.
+ */
+export function stampManifest(template, { version, repoUrl, artifact, flags }) {
+    const stamped = {
+        ...template,
+        version,
+        ...releaseUrls({ repoUrl, version, artifact }),
+    };
+
+    if (flags && Object.keys(flags).length) {
+        stamped.flags = { ...(template.flags ?? {}) };
+        for (const [namespace, values] of Object.entries(flags)) {
+            stamped.flags[namespace] = {
+                ...(template.flags?.[namespace] ?? {}),
+                ...values,
+            };
+        }
+    }
+
+    return stamped;
+}
+
+/**
+ * Read a manifest template, stamp it, and write the result into the stage.
+ *
+ * The only export here that touches disk. Everything it decides is decided by
+ * the pure functions above, so the rules stay testable without a filesystem.
+ *
+ * @param {object} opts
+ * @param {string} opts.templatePath - The manifest template to read.
+ * @param {object} opts.packageJson - The parsed `package.json`, which owns the
+ *   version and the repository address.
+ * @param {string} opts.outDir - Directory to write the manifest into, created
+ *   if absent.
+ * @param {"system"|"module"} [opts.artifact] - Overrides the artifact inferred
+ *   from the template's name.
+ * @param {Record<string, object>} [opts.flags] - Namespaced flags to merge.
+ * @returns {Promise<{path: string, manifest: object}>} Where it was written,
+ *   and what was written.
+ */
+export async function writeFoundryManifest({
+    templatePath,
+    packageJson,
+    outDir,
+    artifact = undefined,
+    flags = undefined,
+}) {
+    const kind = artifact ?? artifactFromTemplate(templatePath);
+    const template = JSON.parse(await fs.readFile(templatePath, "utf8"));
+    const manifest = stampManifest(template, {
+        version: packageJson.version,
+        repoUrl: normalizeRepoUrl(packageJson.repository),
+        artifact: kind,
+        flags,
+    });
+
+    await fs.mkdir(outDir, { recursive: true });
+    const outPath = path.join(outDir, `${kind}.json`);
+    // Trailing newline: the file is committed to a release archive and read by
+    // humans as often as by Foundry.
+    await fs.writeFile(
+        outPath,
+        `${JSON.stringify(manifest, null, 2)}\n`,
+        "utf8",
+    );
+    return { path: outPath, manifest };
+}

package/package.json

@@ -0,0 +1,99 @@
+{
+    "name": "@heroiclands/package-build",
+    "version": "0.1.0",
+    "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package — manifest, localization, staging, bundle, release and deployment.",
+    "license": "GPL-3.0-or-later",
+    "type": "module",
+    "main": "./index.mjs",
+    "types": "./types/index.d.mts",
+    "exports": {
+        ".": {
+            "types": "./types/index.d.mts",
+            "import": "./index.mjs"
+        },
+        "./bundle": {
+            "types": "./types/bundle.d.mts",
+            "import": "./bundle.mjs"
+        },
+        "./deploy": {
+            "types": "./types/deploy.d.mts",
+            "import": "./deploy.mjs"
+        },
+        "./lang": {
+            "types": "./types/lang.d.mts",
+            "import": "./lang.mjs"
+        },
+        "./manifest": {
+            "types": "./types/manifest.d.mts",
+            "import": "./manifest.mjs"
+        },
+        "./release": {
+            "types": "./types/release.d.mts",
+            "import": "./release.mjs"
+        },
+        "./stage": {
+            "types": "./types/stage.d.mts",
+            "import": "./stage.mjs"
+        },
+        "./text": {
+            "types": "./types/text.d.mts",
+            "import": "./text.mjs"
+        },
+        "./package.json": "./package.json"
+    },
+    "files": [
+        "bundle.mjs",
+        "deploy.mjs",
+        "index.mjs",
+        "lang.mjs",
+        "manifest.mjs",
+        "release.mjs",
+        "stage.mjs",
+        "text.mjs",
+        "types",
+        "README.md"
+    ],
+    "scripts": {
+        "test": "vitest run",
+        "test:watch": "vitest",
+        "prepack": "npm run build:types",
+        "build:types": "tsc -p tsconfig.dts.json",
+        "format": "prettier --write .",
+        "format:check": "prettier --check .",
+        "prepare": "git config core.hooksPath .githooks || true"
+    },
+    "dependencies": {
+        "acorn": "^8.18.0",
+        "archiver": "^8.0.0",
+        "ssh2-sftp-client": "^12.1.1"
+    },
+    "devDependencies": {
+        "@types/node": "^26.2.0",
+        "prettier": "^3.9.6",
+        "typescript": "^6.0.3",
+        "vitest": "^4.1.10"
+    },
+    "engines": {
+        "node": ">=24.0.0"
+    },
+    "publishConfig": {
+        "access": "public",
+        "provenance": true
+    },
+    "keywords": [
+        "foundry-vtt",
+        "foundryvtt",
+        "heroiclands",
+        "sohl",
+        "song-of-heroic-lands",
+        "build"
+    ],
+    "homepage": "https://heroiclands.org",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/HeroicLands/package-build.git"
+    },
+    "bugs": {
+        "url": "https://github.com/HeroicLands/package-build/issues"
+    }
+}

package/release.mjs

@@ -0,0 +1,113 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The release archive — the two files a Foundry package's GitHub Release
+ * carries.
+ *
+ * Foundry installs a package by fetching the `download` URL its manifest
+ * advertises, so a release publishes exactly two assets: `<artifact>.zip`, the
+ * whole staged tree, and `<artifact>.json` beside it, which is what an already
+ * installed package re-fetches to notice a new version. Both names are fixed by
+ * what the manifest says, not chosen here — see `manifest.mjs`.
+ *
+ * Kept apart from `stage.mjs` because this is the only part of assembling a
+ * package that needs a dependency. A repository that never cuts a release from
+ * a local build imports the staging half and pays nothing for this one.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import fsp from "node:fs/promises";
+import path from "node:path";
+
+// archiver 8 is pure ESM and exports **classes**, with no default export. The
+// old `import archiver from "archiver"` factory call throws at import —
+// `does not provide an export named 'default'` — which is how this repository's
+// release job came to fail before a single byte was written (#1683).
+import { ZipArchive } from "archiver";
+
+/**
+ * Zip the staged tree and place the manifest beside the archive.
+ *
+ * **Waits for the output stream to close, not merely for the archive to
+ * finalize.** `finalize()` resolves once archiver has finished *appending*
+ * entries, which is before the bytes have necessarily reached disk; returning
+ * there can hand a later step — an upload, a checksum — a truncated file. The
+ * failure is timing-dependent, so it survives every run that happens to be
+ * fast enough, which is what makes it worth being explicit about.
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.stageDir] - The staged package tree.
+ * @param {string} [opts.outDir] - Where the release assets are written.
+ * @param {"system"|"module"} [opts.artifact] - Which artifact is shipped.
+ *   Determines both asset names.
+ * @returns {Promise<{zip: string, manifest: string, bytes: number,
+ *   version: string}>} The two paths written, the archive's size, and the
+ *   version the manifest declares.
+ * @throws {Error} When the stage has no manifest — there is nothing to release,
+ *   and an archive without one installs as nothing.
+ */
+export async function packRelease({
+    stageDir = "build/stage",
+    outDir = "build/dist",
+    artifact = "system",
+} = {}) {
+    const stage = path.resolve(stageDir);
+    const out = path.resolve(outDir);
+    const manifestName = `${artifact}.json`;
+    const stagedManifest = path.join(stage, manifestName);
+
+    if (!fs.existsSync(stagedManifest)) {
+        throw new Error(
+            `${stagedManifest} does not exist, so there is nothing to release. ` +
+                `Build the package first.`,
+        );
+    }
+
+    const manifest = JSON.parse(await fsp.readFile(stagedManifest, "utf8"));
+    await fsp.mkdir(out, { recursive: true });
+
+    const zipPath = path.join(out, `${artifact}.zip`);
+    const output = fs.createWriteStream(zipPath);
+    const archive = new ZipArchive({ zlib: { level: 9 } });
+
+    // Settled before anything is appended, so an error raised during the walk
+    // rejects rather than leaving the await below hanging forever.
+    const closed = new Promise((resolve, reject) => {
+        output.on("close", resolve);
+        output.on("error", reject);
+        archive.on("error", reject);
+        // A warning archiver can recover from (a vanished file, say) still
+        // means the archive is not the tree that was asked for.
+        archive.on("warning", reject);
+    });
+
+    archive.pipe(output);
+    // `false` — no top-level directory inside the zip. Foundry unpacks the
+    // archive *into* the package directory, so an extra level would nest the
+    // manifest one deeper than it looks for it.
+    archive.directory(stage, false);
+    await archive.finalize();
+    await closed;
+
+    await fsp.copyFile(stagedManifest, path.join(out, manifestName));
+
+    return {
+        zip: zipPath,
+        manifest: path.join(out, manifestName),
+        bytes: archive.pointer(),
+        version: manifest.version,
+    };
+}

package/stage.mjs

@@ -0,0 +1,177 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * The build **stage** — assembling the tree that becomes a Foundry package, and
+ * clearing it away again.
+ *
+ * A Foundry package is a directory: a manifest, some assets, compiled packs,
+ * and (if it ships code) a bundle. Every HeroicLands repository assembles that
+ * directory the same way and then either deploys it or zips it, so the copying,
+ * the cleaning and the archiving are one implementation with a per-repository
+ * *list*, not per-repository code.
+ *
+ * They were two implementations. This module takes the better half of each:
+ *
+ * - the **transform hook** from the system repository, which themes bundled SVG
+ *   icons for light and dark mode as they are staged;
+ * - the **missing-source guard** from `sohl-thalorna`, which fails loudly on a
+ *   listed path that does not exist. Without it a mistyped or moved source is a
+ *   silent omission — a module that ships with no `lang/` and no warning, which
+ *   is precisely the failure this project keeps finding in its own satellites.
+ *
+ * The rules are pure functions over data; the functions that touch disk are
+ * named for the effect they have.
+ *
+ * @module
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+
+/**
+ * Directories every HeroicLands repository regenerates and none commits.
+ *
+ * A repository adds its own — `sohl-thalorna` also clears the Hugo output
+ * beneath `site/` — but these four are common to all of them because they come
+ * from the shared toolchain rather than from any one package's layout.
+ */
+export const BUILD_ARTIFACT_DIRS = Object.freeze([
+    "build",
+    ".vite",
+    ".vitepress",
+    ".rollup.cache",
+]);
+
+/**
+ * A source that does not exist, described for a human.
+ *
+ * Pure, and separate from the copying, so the whole list is reported at once.
+ * Discovering missing sources one exception at a time means one fix, one
+ * rebuild, one more exception.
+ *
+ * @param {ReadonlyArray<readonly [string, string]>} entries - `[source, dest]`
+ *   pairs, sources relative to `cwd` or absolute.
+ * @param {string} [cwd] - Resolved against this. Defaults to the process cwd.
+ * @returns {string[]} Every source that is absent, in the order listed.
+ */
+export function missingSources(entries, cwd = process.cwd()) {
+    return entries
+        .map(([src]) => src)
+        .filter((src) => !fs.existsSync(path.resolve(cwd, src)));
+}
+
+/**
+ * Recursively copy `src` to `dest`.
+ *
+ * `transform(sourcePath)` may return a string to write **instead of** a byte
+ * copy; returning `null` or `undefined` falls back to copying the bytes. That
+ * is what lets a repository theme its icons, rewrite a config, or stamp a file
+ * as it stages it, without this function knowing anything about why.
+ *
+ * @param {string} src - Source file or directory.
+ * @param {string} dest - Destination path.
+ * @param {object} [opts]
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   Per-file transform.
+ * @returns {number} How many files were written.
+ */
+export function copyTree(src, dest, { transform } = {}) {
+    if (fs.statSync(src).isDirectory()) {
+        fs.mkdirSync(dest, { recursive: true });
+        let written = 0;
+        for (const entry of fs.readdirSync(src)) {
+            written += copyTree(path.join(src, entry), path.join(dest, entry), {
+                transform,
+            });
+        }
+        return written;
+    }
+
+    fs.mkdirSync(path.dirname(dest), { recursive: true });
+    const transformed = transform ? transform(src) : null;
+    if (transformed != null) fs.writeFileSync(dest, transformed);
+    else fs.copyFileSync(src, dest);
+    return 1;
+}
+
+/**
+ * Copy every listed source into the stage, refusing to start if any is absent.
+ *
+ * **The guard is the point.** A listed path that does not exist is an error,
+ * not a silent skip: a missing `lang/` ships a package with no localization and
+ * nothing said so, and a missing `templates/` ships one whose every sheet fails
+ * to render. Both are indistinguishable from a successful build in the log.
+ *
+ * The check runs over the whole list *before* anything is copied, so a bad list
+ * leaves no half-populated stage behind.
+ *
+ * @param {ReadonlyArray<readonly [string, string]>} entries - `[source, dest]`
+ *   pairs.
+ * @param {object} [opts]
+ * @param {string} [opts.cwd] - Sources and destinations resolve against this.
+ * @param {(sourcePath: string) => string|null|undefined} [opts.transform] -
+ *   Per-file transform, applied to every entry.
+ * @returns {{entries: number, files: number}} What was staged.
+ * @throws {Error} When any source is missing, naming all of them.
+ */
+export function stageAssets(entries, { cwd = process.cwd(), transform } = {}) {
+    const missing = missingSources(entries, cwd);
+    if (missing.length) {
+        throw new Error(
+            `Cannot stage assets — these paths do not exist:\n` +
+                missing.map((p) => `   ${p}`).join("\n"),
+        );
+    }
+
+    let files = 0;
+    for (const [src, dest] of entries) {
+        files += copyTree(path.resolve(cwd, src), path.resolve(cwd, dest), {
+            transform,
+        });
+    }
+    return { entries: entries.length, files };
+}
+
+/**
+ * Remove the build artefacts a repository regenerates.
+ *
+ * A directory that is already gone is not an error — the command has to be safe
+ * to run repeatedly, and "clean when already clean" is the ordinary case.
+ *
+ * @param {string} root - Repository root; every directory resolves against it.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.extra] - Directories beyond
+ *   {@link BUILD_ARTIFACT_DIRS} that this repository also regenerates.
+ * @param {boolean} [opts.includeNodeModules] - Also remove `node_modules`, the
+ *   `distclean` case.
+ * @returns {string[]} The directories removed, as listed.
+ */
+export function cleanBuildArtifacts(
+    root,
+    { extra = [], includeNodeModules = false } = {},
+) {
+    const dirs = [
+        ...BUILD_ARTIFACT_DIRS,
+        ...extra,
+        ...(includeNodeModules ? ["node_modules"] : []),
+    ];
+    const removed = [];
+    for (const dir of dirs) {
+        const target = path.resolve(root, dir);
+        if (!fs.existsSync(target)) continue;
+        fs.rmSync(target, { recursive: true, force: true });
+        removed.push(dir);
+    }
+    return removed;
+}

package/text.mjs

@@ -0,0 +1,74 @@
+/*
+ * This file is part of the Song of Heroic Lands (SoHL) system for Foundry VTT.
+ * Copyright (c) 2024-2026 Tom Rodriguez ("Toasty") — <toasty@heroiclands.org>
+ *
+ * This work is licensed under the GNU General Public License v3.0 (GPLv3).
+ * You may copy, modify, and distribute it under the terms of that license.
+ *
+ * For full terms, see the LICENSE.md file in the project root or visit:
+ * https://www.gnu.org/licenses/gpl-3.0.html
+ *
+ * SPDX-License-Identifier: GPL-3.0-or-later
+ */
+
+/**
+ * Locating a literal inside an arbitrary text file.
+ *
+ * A build check reports a **finding**, and a finding is only actionable if it
+ * says where it is (#1668). Most findings are *about* a string the check
+ * matched — a key, a marker, a caption — so its position is one string search
+ * away, and making that search is the difference between a finding that can be
+ * opened and one that has to be hunted for.
+ *
+ * `@heroiclands/content-build` owns the diagnostic **format**, and its
+ * `positionInBody` maps an offset within a parsed content note back to its
+ * file. That is a different job: the checks here read localization files,
+ * manifests, source and bundles — none of which are notes. So this module
+ * carries the generic operation, and nothing carries it twice.
+ *
+ * Plain ESM with no filesystem access, so it is unit-testable.
+ *
+ * @module
+ */
+
+/**
+ * Where a literal sits in a text.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based. Repeats of the same
+ *   literal are otherwise indistinguishable, which is the symptom the
+ *   diagnostic format exists to remove.
+ * @returns {{line: number, column: number}|undefined} 1-based position, or
+ *   `undefined` when the literal is not there. A caller that gets `undefined`
+ *   reports the file alone rather than a position that is not the problem.
+ */
+export function locateInText(text, needle, occurrence = 1) {
+    if (typeof text !== "string" || !needle) return undefined;
+    let at = -1;
+    for (let n = 0; n < occurrence; n++) {
+        at = text.indexOf(needle, at + 1);
+        if (at === -1) return undefined;
+    }
+    const before = text.slice(0, at);
+    return {
+        line: before.split("\n").length,
+        column: at - before.lastIndexOf("\n"),
+    };
+}
+
+/**
+ * Where a literal sits, as spreadable diagnostic fields.
+ *
+ * Keeps the drop-rather-than-guess rule in one place: an unfound literal
+ * contributes no position at all, rather than `undefined` fields that read as a
+ * bug or a `1:1` that sends the reader to the top of the file.
+ *
+ * @param {string} text - The file's contents.
+ * @param {string} needle - The literal to locate.
+ * @param {number} [occurrence] - Which occurrence, 1-based.
+ * @returns {{line?: number, column?: number}} Spreadable position fields.
+ */
+export function positionOf(text, needle, occurrence = 1) {
+    return locateInText(text, needle, occurrence) ?? {};
+}