@heroiclands/package-build 0.3.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,79 @@
 # @heroiclands/package-build
 
+## 0.5.0
+
+### Minor Changes
+
+- 905254d: **`text.mjs` is deleted; the one implementation lives with the diagnostics
+  contract it serves.**
+  
+  `locateInText` and `positionOf` computed which line and column a substring sits
+  on. `@heroiclands/content-build` computes the same thing in
+  `engine/diagnostics.mjs` as `positionOfLiteral`, and has said so in a comment
+  for some time:
+  
+  > That is a duplicate worth naming: unlike the diagnostic _format_ or a
+  > validation _rule_, "which line and column is this substring on" has exactly
+  > one correct answer and cannot drift into disagreement. The tidier arrangement
+  > is for that package to re-export this one — the dependency runs that way — and
+  > it should, next time either is touched.
+  
+  This is that time. Rather than re-export, the module is removed outright: the
+  `./text` subpath was a library surface with one internal caller (`lang.mjs`) and
+  one external one, and this package's job is a command line, not a text-utility
+  grab bag.
+  
+  **Breaking for anyone importing `@heroiclands/package-build/text`.** Import
+  `positionOfLiteral` from `@heroiclands/content-build/engine/diagnostics`
+  instead; it is the same arithmetic, and returns `{}` rather than `undefined`
+  when the literal is absent — the shape the diagnostics contract already spreads.
+  `locateInText` had no callers anywhere and is simply gone.
+
+## 0.4.0
+
+### Minor Changes
+
+- 2c2fc37: **`package-build bundle check` — the last capability that had no command.**
+  
+  The bundle-loading check was exported as a library function and reachable no
+  other way, so a consumer that wanted it had to write the script the command line
+  exists to remove: read the manifest, read the bundle, call the function, decide
+  how to print findings, choose an exit code. It now runs from configuration like
+  every other job.
+  
+  It catches three ways a package builds successfully and still does not load,
+  none of which a bundler can see, because each is a disagreement between two
+  files rather than a fault in either:
+  
+  | The manifest says                                                         | What Foundry does                                                                  |
+  | ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+  | the entry under both `esmodules` and `scripts`                            | loads the bundle twice                                                             |
+  | the entry under neither                                                   | never loads it at all                                                              |
+  | the entry under `esmodules`, but the file only parses as a classic script | fails at load, naming whichever `import` came first and nothing about the manifest |
+  
+  Both files are read from the stage, because the stage is what ships.
+  
+  **The entry is derived, not stated.** `packageBuild.bundle.entry` defaults to
+  `<packageId>.mjs`, which is already derived from `package.json` `name`; a
+  repository states it only when its bundler emits something else. It is
+  deliberately _not_ read back out of the generated manifest — a value taken from
+  there would agree with itself by construction, and the check's whole question is
+  whether the manifest declares this file the way Foundry needs it.
+  
+  **Reporting is now decided once.** `lang check` had the diagnostic contract —
+  `file:line:column: severity: message`, the path starting the line, a field
+  dropped rather than guessed — spelled out inline in its handler. Both commands
+  now report through one seam that maps findings onto the format
+  `@heroiclands/content-build` already owns, so the two packages cannot drift into
+  two nearly-identical formats. `lang check`'s output is unchanged.
+  
+  **The command surface has a stated shape.** A capability with a single operation
+  is a bare command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`);
+  one with more than a single operation takes a positional action, so a second can
+  be added without renaming the first (`lang check`, `bundle check`).
+  
+  Closes #12
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -96,6 +96,14 @@ packageBuild:
     # Prefix of the shared SFTP override variables. Default `SOHL`.
     envPrefix: SOHL
 
+  bundle:
+    # The file Foundry loads, as the manifest spells it, relative to the stage.
+    # Defaults to `<packageId>.mjs`; state it only when the bundler emits
+    # something else. Deliberately not read back out of the manifest — a value
+    # taken from there would agree with itself by construction, and `bundle
+    # check` asks whether the manifest declares this file correctly.
+    entry: sohl.mjs
+
   # Optional. A module exporting `flags(config)` returning namespaced Foundry
   # flags the repository has to *compute* — an address that only exists once
   # the content tree has been walked, say. Merged over any declared below.
@@ -176,11 +184,12 @@ other's schema — they split by input, and the dependency runs one way.
 
 **What is derived, not stated:**
 
-| Field                      | Derived from                                                         |
-| -------------------------- | -------------------------------------------------------------------- |
-| the repository root        | the configuration file's own location                                |
-| `packageKind`, `packageId` | the shared configuration's top level                                 |
-| the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json` |
+| Field                      | Derived from                                                                |
+| -------------------------- | --------------------------------------------------------------------------- |
+| the repository root        | the configuration file's own location                                       |
+| `packageKind`, `packageId` | the shared configuration's top level                                        |
+| the release artifact       | `packageKind` — a system ships `system.json`, a module `module.json`        |
+| the bundle entry           | `packageId` — `<id>.mjs`, unless `packageBuild.bundle.entry` says otherwise |
 
 ## Command line
 
@@ -189,6 +198,7 @@ npx package-build clean [--distclean]
 npx package-build assets
 npx package-build manifest
 npx package-build lang check
+npx package-build bundle check
 npx package-build release
 npx package-build deploy <stage>
 ```
@@ -201,11 +211,34 @@ Wrapped as npm scripts — SoHL spells them:
   "distclean": "package-build clean --distclean",
   "build:assets": "package-build assets",
   "lint:lang": "package-build lang check",
+  "lint:bundle-globals": "package-build bundle check",
   "build:pack-release": "package-build release",
   "push:qa": "package-build deploy qa"
 }
 ```
 
+**The shape of the surface.** A capability with a single operation is a bare
+command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`); one with
+more than a single operation takes a positional action, so a second can be added
+without renaming the first (`lang check`, `bundle check`). Flat `lang:check`
+names would make every operation a new top-level command and hide which ones
+belong together.
+
+**What `bundle check` checks.** Three ways a package builds successfully and
+still does not load, none of which a bundler can see, because each is a
+disagreement between two files rather than a fault in either:
+
+| The manifest says                                                         | What Foundry does                                                                  |
+| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
+| the entry under both `esmodules` and `scripts`                            | loads the bundle twice                                                             |
+| the entry under neither                                                   | never loads it at all                                                              |
+| the entry under `esmodules`, but the file only parses as a classic script | fails at load, naming whichever `import` came first and nothing about the manifest |
+
+It reads both files from the stage, because the stage is what ships — checking
+sources would answer for a package nobody installs. Findings are emitted as
+`file:line:column: severity: message`, and the command exits non-zero when any
+of them is an error.
+
 **Why the CLI exists.** This package was library-only, so every consuming
 repository wrote a wrapper script per job — six of them in the SoHL repository,
 441 lines that between them contained no logic. `clean.mjs` was 47 lines that

package/bin/package-build.mjs

@@ -34,6 +34,13 @@
  * stay import-safe, so a consuming repository's build — or a test — can call
  * them without any of it happening.
  *
+ * **The shape of the command surface.** A capability with a single operation is
+ * a bare command (`clean`, `assets`, `manifest`, `release`, `deploy <stage>`);
+ * one with more than a single operation takes a positional action, so it can
+ * grow another without renaming the first (`lang check`, `bundle check`). The
+ * alternative — flat `lang:check`-style names — makes the second operation a
+ * new top-level command and the relationship between them invisible.
+ *
  * The side effects that need *configuration* live inside the command handlers,
  * never at module scope, so `--version` and `--help` answer in a directory with
  * no configuration at all. Running an actual command still resolves it, and
@@ -44,6 +51,7 @@
  *   npx package-build assets
  *   npx package-build manifest
  *   npx package-build lang check
+ *   npx package-build bundle check
  *   npx package-build release
  *   npx package-build deploy <stage>
  *
@@ -51,6 +59,7 @@
  *   npm run clean                          // → … clean
  *   npm run build:assets                   // → … assets
  *   npm run lint:lang                      // → … lang check
+ *   npm run lint:bundle-globals            // → … bundle check
  *   npm run build:pack-release             // → … release
  *   npm run push:qa                        // → … deploy qa
  */
@@ -66,9 +75,11 @@ import { loadPackageBuildConfig } from "../config.mjs";
 import { loadPackConfig } from "@heroiclands/content-build/engine/pack-config";
 import { cleanBuildArtifacts, stageAssets } from "../stage.mjs";
 import { validateLangSource } from "../lang.mjs";
+import { checkBundleLoading } from "../bundle.mjs";
 import { packRelease } from "../release.mjs";
 import { writeManifest } from "../manifest.mjs";
 import { deployStage } from "../deploy.mjs";
+import { reportFindings } from "./report.mjs";
 
 /**
  * This package's own version, for `--version`.
@@ -312,20 +323,10 @@ function langCommand() {
 
             let total = 0;
             for (const file of files.sort()) {
-                const relative = path.relative(config.rootDir, file);
-                for (const finding of validateLangSource(
-                    fs.readFileSync(file, "utf8"),
-                )) {
-                    total++;
-                    // The diagnostics contract: the path starts the line, and a
-                    // field is dropped rather than guessed.
-                    const at = [relative, finding.line, finding.column]
-                        .filter((part) => part !== undefined && part !== null)
-                        .join(":");
-                    console.error(
-                        `${at}: ${finding.severity ?? "error"}: ${finding.message}`,
-                    );
-                }
+                total += reportFindings(
+                    validateLangSource(fs.readFileSync(file, "utf8")),
+                    { file: path.relative(config.rootDir, file) },
+                );
             }
 
             if (total) {
@@ -340,6 +341,72 @@ function langCommand() {
     };
 }
 
+/**
+ * `bundle check` — does the manifest agree with the bundle it points at?
+ *
+ * Three ways a package can be built successfully and still not load, none of
+ * which the bundler can see because each is a disagreement between two files:
+ * the entry listed under both `esmodules` and `scripts` (Foundry loads it
+ * twice), under neither (Foundry never loads it), or under `esmodules` while
+ * the emitted file only parses as a classic script. The last fails at runtime
+ * with a message about whichever `import` came first and says nothing about the
+ * manifest, which is the kind of error that costs an afternoon.
+ *
+ * Both files are read from the stage, because the stage is what ships. Checking
+ * sources would answer for a package nobody installs.
+ *
+ * @returns {object} The yargs command module.
+ */
+function bundleCommand() {
+    return {
+        command: "bundle <action>",
+        describe: "Code-bundle checks",
+        builder: (y) =>
+            y.positional("action", {
+                choices: ["check"],
+                describe:
+                    "check: verify the manifest and the staged bundle agree",
+            }),
+        handler: handler(() => {
+            const config = loadPackageBuildConfig();
+            const stageDir = path.join(config.rootDir, config.stageDir);
+            const manifestPath = path.join(stageDir, `${config.artifact}.json`);
+            const bundlePath = path.join(stageDir, config.bundleEntry);
+
+            // Named explicitly rather than left to a missing-file stack trace:
+            // both absences mean "the stage was not built", and a reader who
+            // sees the path knows which step to run.
+            for (const [what, where] of [
+                ["manifest", manifestPath],
+                ["bundle", bundlePath],
+            ]) {
+                if (!fs.existsSync(where)) {
+                    die(
+                        `no staged ${what} at ` +
+                            `${path.relative(config.rootDir, where)} — build ` +
+                            `the stage before checking it.`,
+                    );
+                }
+            }
+
+            const relative = path.relative(config.rootDir, bundlePath);
+            const { findings, declaredAs } = checkBundleLoading({
+                manifest: JSON.parse(fs.readFileSync(manifestPath, "utf8")),
+                source: fs.readFileSync(bundlePath, "utf8"),
+                entry: config.bundleEntry,
+                manifestName: path.relative(config.rootDir, manifestPath),
+            });
+
+            if (reportFindings(findings, { file: relative })) process.exit(1);
+
+            console.log(
+                `package-build: ${config.bundleEntry} is declared under ` +
+                    `"${declaredAs}" and loads as one.`,
+            );
+        }),
+    };
+}
+
 /**
  * `release` — zip the staged package for a GitHub release.
  *
@@ -421,6 +488,7 @@ yargs(hideBin(process.argv))
     .command(assetsCommand())
     .command(manifestCommand())
     .command(langCommand())
+    .command(bundleCommand())
     .command(releaseCommand())
     .command(deployCommand())
     .demandCommand(1, "Name a command.")

package/bin/report.mjs

@@ -0,0 +1,108 @@
+/*
+ * 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
+ */
+
+/**
+ * How the command line reports what a rule found.
+ *
+ * The package's rules are pure: they take source text and return findings,
+ * leaving discovery, I/O and reporting to whoever called them. That is what
+ * makes them testable, but it also means every caller has to decide the same
+ * two things — what a finding looks like once emitted, and what a run's exit
+ * code should be. Before there was a command line, every consumer decided them
+ * separately, and no two agreed.
+ *
+ * This module is where the binary decides them once. It lives under `bin/`
+ * rather than beside the rules deliberately: it is the *caller's* half, not
+ * part of the pure surface, and nothing importing this package as a library
+ * should reach it.
+ *
+ * The emitted form is the toolchain's diagnostic contract —
+ * `file:line:column: severity: message`, the path starting the line, a field
+ * dropped rather than guessed — which `@heroiclands/content-build` already
+ * owns. This module maps findings onto it rather than restating it, so the two
+ * packages cannot drift into two nearly-identical formats.
+ *
+ * @module
+ */
+
+import { emitDiagnostic } from "@heroiclands/content-build/engine/diagnostics";
+
+/**
+ * A finding as the pure rules report one.
+ *
+ * @typedef {object} Finding
+ * @property {string} message                 What is wrong, in one sentence.
+ * @property {"warning"|"error"} [severity]   Defaults to `error`.
+ * @property {number} [line]                  1-based line, when known.
+ * @property {number} [column]                1-based column, when known.
+ */
+
+/**
+ * Turn a rule's findings into diagnostics, attaching the file they are about.
+ *
+ * A rule is handed source text and never learns the path it came from, so the
+ * caller is the only one who can say it — and a finding without a file is one
+ * nothing can navigate to.
+ *
+ * **A field is dropped, never guessed.** A finding that knows no line emits as
+ * `file: severity: message`, because defaulting to `1:1` sends a reader to the
+ * top of the file every time and reads exactly like a real position. A column
+ * without a line is dropped for the same reason: it locates nothing on its own.
+ *
+ * @param {Finding[]} findings - What the rule returned.
+ * @param {object} opts
+ * @param {string} opts.file - Path to the file, relative to the working
+ *   directory, so the emitted line is one an editor or `cc`-style parser can
+ *   open.
+ * @returns {Array<{file: string, line?: number, column?: number,
+ *   severity: "warning"|"error", message: string}>} The diagnostics, in the
+ *   order the rule reported them.
+ */
+export function toDiagnostics(findings, { file }) {
+    return findings.map((finding) => {
+        const hasLine = finding.line !== undefined && finding.line !== null;
+        const hasColumn =
+            finding.column !== undefined && finding.column !== null;
+        return {
+            file,
+            ...(hasLine ? { line: finding.line } : {}),
+            // Only alongside a line: `formatLocator` ignores a lone column, and
+            // carrying it anyway would invite a reader to trust it.
+            ...(hasLine && hasColumn ? { column: finding.column } : {}),
+            severity: finding.severity ?? "error",
+            message: finding.message,
+        };
+    });
+}
+
+/**
+ * Emit a rule's findings and say how many of them fail the run.
+ *
+ * Warnings are emitted and counted separately from the return value, so a
+ * command can report something worth reading without failing a build over it.
+ *
+ * @param {Finding[]} findings - What the rule returned.
+ * @param {object} opts
+ * @param {string} opts.file - Path to the file, relative to the working dir.
+ * @param {(d: object) => void} [opts.emit] - How to emit one diagnostic.
+ *   Injectable so a test can capture the emitted shape without reaching for
+ *   the console; defaults to content-build's `emitDiagnostic`, which writes
+ *   both severities to stderr.
+ * @returns {number} How many diagnostics were errors — the count a command
+ *   turns into its exit code.
+ */
+export function reportFindings(findings, { file, emit = emitDiagnostic }) {
+    const diagnostics = toDiagnostics(findings, { file });
+    for (const diagnostic of diagnostics) emit(diagnostic);
+    return diagnostics.filter((d) => d.severity === "error").length;
+}

package/config.mjs

@@ -69,6 +69,7 @@ const SECTION_KEYS = [
     "lang",
     "deploy",
     "release",
+    "bundle",
 ];
 
 /**
@@ -98,6 +99,7 @@ const CLEAN_KEYS = ["extra"];
 const LANG_KEYS = ["sources", "help"];
 const DEPLOY_KEYS = ["envPrefix"];
 const RELEASE_KEYS = ["artifact"];
+const BUNDLE_KEYS = ["entry"];
 
 /**
  * The artifact name each package kind ships, so no repository states it.
@@ -240,6 +242,8 @@ function normalizeManifest(value) {
  * @property {string} langSources    Glob for the localization files to check.
  * @property {string|null} langHelp  Extra guidance printed after a failure.
  * @property {string} envPrefix      Prefix of the deploy environment variables.
+ * @property {string} bundleEntry   The bundle file Foundry loads, as the
+ *   manifest spells it. Derived from the package id.
  */
 
 /**
@@ -308,6 +312,15 @@ export function resolvePackageBuildConfig(shared) {
     );
     const releaseInput = /** @type {Record<string, unknown>} */ (release);
 
+    const bundle = section.bundle ?? {};
+    if (!isMapping(bundle)) fail("packageBuild.bundle", "must be a mapping");
+    rejectUnknownKeys(
+        /** @type {Record<string, unknown>} */ (bundle),
+        BUNDLE_KEYS,
+        "packageBuild.bundle.",
+    );
+    const bundleInput = /** @type {Record<string, unknown>} */ (bundle);
+
     return Object.freeze({
         rootDir: shared.rootDir,
         // Where the package is assembled before it is zipped or deployed. Every
@@ -375,6 +388,22 @@ export function resolvePackageBuildConfig(shared) {
                     deployInput.envPrefix,
                     "packageBuild.deploy.envPrefix",
                 ),
+        // The file Foundry loads, as the manifest spells it. Named after the
+        // package by convention, and the id is already derived from
+        // package.json `name` — so a repository states this only when its
+        // bundler emits something else.
+        //
+        // Deliberately *not* read back out of the generated manifest: the
+        // check's question is whether the manifest declares this file the way
+        // Foundry needs it, and a value taken from the manifest could never
+        // answer that — it would agree with itself by construction.
+        bundleEntry:
+            bundleInput.entry === undefined ?
+                `${shared.foundryPackage}.mjs`
+            :   requireNonEmptyString(
+                    bundleInput.entry,
+                    "packageBuild.bundle.entry",
+                ),
     });
 }
 

package/index.mjs

@@ -56,6 +56,3 @@ export * as deploy from "./deploy.mjs";
 
 /** Localization files: what a shippable `lang/*.json` must satisfy. */
 export * as lang from "./lang.mjs";
-
-/** Locating a literal inside an arbitrary text file, for positioned findings. */
-export * as text from "./text.mjs";

package/lang.mjs

@@ -45,7 +45,7 @@
  * @module
  */
 
-import { positionOf } from "./text.mjs";
+import { positionOfLiteral } from "@heroiclands/content-build/engine/diagnostics";
 
 /**
  * A single finding, in the fields the shared diagnostic format takes.
@@ -140,7 +140,7 @@ export function validateLangSource(raw) {
      * @param {string} key - The localization key.
      * @returns {{line?: number, column?: number}} Spreadable position fields.
      */
-    const at = (key) => positionOf(raw, `"${key}"`);
+    const at = (key) => positionOfLiteral(raw, `"${key}"`);
 
     for (const [key, value] of Object.entries(json)) {
         if (typeof value !== "string") continue;

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@heroiclands/package-build",
-    "version": "0.3.0",
+    "version": "0.5.0",
     "description": "Shared toolchain for building and shipping a HeroicLands Foundry VTT package \u2014 manifest, localization, staging, bundle, release and deployment.",
     "license": "GPL-3.0-or-later",
     "type": "module",
@@ -35,10 +35,6 @@
             "types": "./types/stage.d.mts",
             "import": "./stage.mjs"
         },
-        "./text": {
-            "types": "./types/text.d.mts",
-            "import": "./text.mjs"
-        },
         "./package.json": "./package.json",
         "./config": {
             "types": "./types/config.d.mts",
@@ -53,7 +49,6 @@
         "manifest.mjs",
         "release.mjs",
         "stage.mjs",
-        "text.mjs",
         "types",
         "CHANGELOG.md",
         "README.md",

package/types/config.d.mts

@@ -22,6 +22,8 @@
  * @property {string} langSources    Glob for the localization files to check.
  * @property {string|null} langHelp  Extra guidance printed after a failure.
  * @property {string} envPrefix      Prefix of the deploy environment variables.
+ * @property {string} bundleEntry   The bundle file Foundry loads, as the
+ *   manifest spells it. Derived from the package id.
  */
 /**
  * Resolve a package-build configuration from an already-loaded shared one.
@@ -135,4 +137,9 @@ export type PackageBuildConfig = {
      * Prefix of the deploy environment variables.
      */
     envPrefix: string;
+    /**
+     * The bundle file Foundry loads, as the
+     * manifest spells it. Derived from the package id.
+     */
+    bundleEntry: string;
 };

package/types/index.d.mts

@@ -4,4 +4,3 @@ export * as stage from "./stage.mjs";
 export * as release from "./release.mjs";
 export * as deploy from "./deploy.mjs";
 export * as lang from "./lang.mjs";
-export * as text from "./text.mjs";

package/text.mjs

@@ -1,74 +0,0 @@
-/*
- * 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) ?? {};
-}

package/types/text.d.mts

@@ -1,51 +0,0 @@
-/**
- * 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: string, needle: string, occurrence?: number): {
-    line: number;
-    column: number;
-} | undefined;
-/**
- * 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: string, needle: string, occurrence?: number): {
-    line?: number;
-    column?: number;
-};