@heroiclands/package-build 25.1.2 → 25.2.0

package/engine/culture-reach.mjs

@@ -38,6 +38,7 @@ import { isAddressTuple, parseAddress, renderAddress } from "./address.mjs";
 import { AddressLink } from "./address-values.mjs";
 import { positionOfFrontmatterPath } from "./diagnostics.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
+import { languageNotesByCode } from "./note-language.mjs";
 import { parseWordClass, WORD_CLASS_BASES } from "./word-classes.mjs";
 import { glossSenses, LANGUAGE_SUBTYPE } from "./word-terms.mjs";
 
@@ -159,13 +160,21 @@ function languageWords(notes, index) {
  * @returns {import("./glossary-language.mjs").GlossaryLanguageReader}
  */
 function readerOf(index, note) {
+    let notes = languageNotes.get(index);
+    if (!notes) {
+        notes = languageNotesByCode(index.notes ?? [], (each) => ownKey(each, index));
+        languageNotes.set(index, notes);
+    }
     return {
         keyOf: (value, type) => addressKeyOf(value, index, type),
-        lookup: (key) => index.addressHit?.(key),
+        noteOf: (code) => notes.get(code),
         self: ownKey(note, index),
     };
 }
 
+/** Each link index's language notes by code, read once. */
+const languageNotes = new WeakMap();
+
 /**
  * The language a glossary entry on a note resolves to.
  *

package/engine/diagnostics.mjs

@@ -160,7 +160,8 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
     const upTo = String(body ?? "").slice(0, Math.max(0, offset));
     const nl = upTo.lastIndexOf("\n");
     const scannedLine = upTo.length === 0 ? 0 : upTo.split("\n").length - 1;
-    const column = upTo.length - nl; // 1-based: offset - (nl + 1) + 1
+    // A first-use mark the expansion wrote is no authored character.
+    const column = upTo.slice(nl + 1).replace(/[\uFDD0\uFDD1]/g, "").length + 1;
 
     const mapped = lineMap?.[scannedLine];
     const sourceLine = mapped ? mapped.line : scannedLine;
@@ -201,7 +202,7 @@ export function positionInBody(body, offset, { bodyLine = 1, bodyColumn = 1, lin
  * @param {string} raw - The file's full contents, frontmatter included.
  * @param {string} key - The top-level frontmatter key.
  * @param {string} [value] - When given, prefer the occurrence whose line also
- *   carries this text. A list-valued key (`aliases`) is reported at the entry
+ *   carries this text. A list-valued key (`tags`) is reported at the entry
  *   that is wrong, not at the key that introduces it.
  * @param {object} [options] - Options.
  * @param {boolean} [options.topLevel=false] - Require the key at column 1, so

package/engine/dictionary-rows.mjs

@@ -53,6 +53,7 @@ export { pluralOf, pluralByRule } from "./word-inflections.mjs";
 import { createHash } from "node:crypto";
 import { parseAddress, renderAddress } from "./address.mjs";
 import { glossaryLanguage } from "./glossary-language.mjs";
+import { languageNotesByCode } from "./note-language.mjs";
 import { isNoteRecord } from "./index-records.mjs";
 import { parseWordClass, WORD_CLASS_BASES } from "./word-classes.mjs";
 import { citationLookup, isLanguageRecord, lineageChain, pieceGlosses } from "./word-rows.mjs";
@@ -229,9 +230,10 @@ export function dictionaryAndTermRows(records, all = records) {
     const ref = (value, pkg, type) => refKey(value, pkg, type, types);
     /** An Address a row may cite: not a note of this package the audience does not see. */
     const citable = (key) => visible.has(key) || !byKey.has(key);
+    const languageNotes = languageNotesByCode(byKey.values(), noteKey);
     const reader = {
         keyOf: (value) => (typeof value === "string" && value ? value : undefined),
-        lookup: (key) => byKey.get(key),
+        noteOf: (code) => languageNotes.get(code),
     };
 
     // ── Languages ────────────────────────────────────────────────────────────

package/engine/encoding-lexicon.mjs

@@ -22,6 +22,7 @@ import { isLanguageRecord, lineageChain, noteAddressOf } from "./word-rows.mjs";
 import { derivedForms, foldWord } from "./word-forms.mjs";
 import { WRITTEN_ENDINGS, RESERVED_TONGUE } from "./language-terms.mjs";
 import { LANGUAGE_SUBTYPE, glossText } from "./word-terms.mjs";
+import { ENGLISH_GROUP } from "./language-names.mjs";
 import { writingsOf } from "./language-writings.mjs";
 import { encodeText, validateSource, EncodingError } from "./encoding.mjs";
 import { encodeWithLanguage } from "./encoding-language.mjs";
@@ -642,7 +643,10 @@ export function checkEncodingLexicon(note, ctx) {
         ...new Map(
             [...(ctx.encodings?.values() ?? [])].map((encoding) => [encoding.name, encoding]),
         ).values(),
-    ].filter((encoding) => aliases.has(encoding.language));
+    ]
+        .filter((encoding) => aliases.has(encoding.language))
+        // A codes-only script accepts no letter, so the roman forms are not written in it.
+        .filter((encoding) => [...encoding.accepted].some((char) => /\p{L}/u.test(char)));
     if (!encodings.length) return [];
     const forms = [],
         data = note.fm.data ?? {};
@@ -653,6 +657,7 @@ export function checkEncodingLexicon(note, ctx) {
         add(word?.form, ["words", i, "form"]);
         listOf(word?.variants).forEach((form, j) => add(form, ["words", i, "variants", j]));
     });
+    // `en` holds English names, which no encoding of the tongue sees.
     const names = (value, keys) => {
         if (Array.isArray(value))
             value.forEach((item, i) =>
@@ -660,7 +665,12 @@ export function checkEncodingLexicon(note, ctx) {
             );
         else if (isMap(value))
             for (const [key, item] of Object.entries(value))
-                if (key !== "pattern" && key !== "metadata") names(item, [...keys, key]);
+                if (
+                    key !== "pattern" &&
+                    key !== "metadata" &&
+                    !(keys.length === 1 && key === ENGLISH_GROUP)
+                )
+                    names(item, [...keys, key]);
     };
     names(data.names, ["names"]);
     listOf(data.elements).forEach((element, i) => {

package/engine/first-use.mjs

@@ -11,16 +11,60 @@
  * SPDX-License-Identifier: GPL-3.0-or-later
  */
 
+/**
+ * **A name's first use.** Each name a page marks is keyed, and the first use
+ * of each key in the page's prose is bold when the page renders. Bold an author
+ * writes is the author's choice.
+ *
+ * The key of a use is, in order:
+ *
+ * 1. a name wikilink's address (`[[being-tomr|Tom]]{.name}`);
+ * 2. a `.name` span's `ref`: an address (`ref=being-tomr`) or a page-local key
+ *    (`ref="#jane"`);
+ * 3. otherwise the span's label, case folded, with its `lang` (`en` when it
+ *    states none).
+ *
+ * Only body prose counts: paragraphs, list items, quotations and footnotes.
+ * Headings, tables, captions, the title line of a named block, raw HTML, code,
+ * verse and the sections generated from frontmatter neither take the bold nor
+ * count as a use, and neither does a name inside a run that states `lang`,
+ * `font` or `enc`. A name already inside authored strong text counts as its
+ * key's first use and takes no second bold.
+ *
+ * {@link boldFirstUses} runs once, in the expansion every target shares, and
+ * marks each first use with {@link FIRST_USE_OPEN} and {@link FIRST_USE_CLOSE};
+ * {@link firstUsePlugin} turns the marks into strong text in every renderer.
+ * {@link createFirstUseChecker} is the lint over the same uses.
+ *
+ * @module
+ */
+
 import { unified } from "unified";
 import remarkParse from "remark-parse";
 import remarkFrontmatter from "remark-frontmatter";
 import remarkGfm from "remark-gfm";
 import MarkdownIt from "markdown-it";
+import { readQualifier } from "./address.mjs";
+import { scanBlocks } from "./content-blocks.mjs";
+import { scanFigures } from "./content-figures.mjs";
+import { RUN_KEYS } from "./content-scripts.mjs";
 import { scanSpans, spanMarkdownPlugin } from "./content-spans.mjs";
 import { inlineText, rebaseNameSpans } from "./name-markup.mjs";
-import { createNameCatalog, nameForms as forms, normalizeName as normalize } from "./names.mjs";
+import { isLocalRef, readNameRef } from "./name-refs.mjs";
+import { createNameCatalog, normalizeName as normalize } from "./names.mjs";
 import { WIKILINK, parseWikilink } from "./wikilink-syntax.mjs";
 
+/**
+ * Opens a first use in expanded markdown: a Unicode noncharacter, which no
+ * authored text, font or encoding uses.
+ */
+export const FIRST_USE_OPEN = "\uFDD0";
+
+/** Closes a first use in expanded markdown. */
+export const FIRST_USE_CLOSE = "\uFDD1";
+
+const MARKS = /[\uFDD0\uFDD1]/g;
+
 const parser = unified().use(remarkParse).use(remarkFrontmatter).use(remarkGfm);
 const labelParser = new MarkdownIt({ html: true }).use(spanMarkdownPlugin);
 const linkRule = labelParser.inline.ruler.getRules("").find((rule) => rule.name === "link");
@@ -81,7 +125,6 @@ function readLabel(text, env = {}) {
     }
     return { text: inlineText(tokens), links };
 }
-const labelText = (text, env) => readLabel(text, env).text;
 
 /** The kind a span's `data-type` supplies; an invalid value is refused by the span check. */
 function spanKind(span) {
@@ -122,11 +165,16 @@ const overlaps = (values, value) => {
     return range && range.end > value.start;
 };
 
-/** Explicit inline occurrences and structural exclusions at original source offsets. */
+/**
+ * Explicit inline occurrences, authored strong text and structural exclusions
+ * at original source offsets.
+ */
 function prose(source, capturedNames) {
     const links = [],
+        paragraphs = [],
         regions = [],
         excluded = [],
+        strong = [],
         html = [];
     const masked = source
         .replace(/!\[\[[^\]\n]+\]\]|\{\{[^}\n]+\}\}/g, (text, start) => {
@@ -137,7 +185,12 @@ function prose(source, capturedNames) {
             let escapes = 0;
             while (source[start - escapes - 1] === "\\") escapes++;
             if (escapes % 2) return text;
-            links.push({ ...parseWikilink(inner), start, end: start + text.length, wiki: true });
+            links.push({
+                ...parseWikilink(inner, text),
+                start,
+                end: start + text.length,
+                wiki: true,
+            });
             return "x".repeat(text.length);
         });
     const tree = parser.parse(masked);
@@ -151,6 +204,7 @@ function prose(source, capturedNames) {
         else if (["strong", "emphasis", "delete", "link", "linkReference"].includes(node.type)) {
             if (["link", "linkReference"].includes(node.type) && source[start] === "[")
                 links.push({ start, end, labelled: true });
+            if (node.type === "strong") strong.push({ start, end });
             for (const child of node.children ?? []) inline(child);
         }
     };
@@ -162,7 +216,9 @@ function prose(source, capturedNames) {
             };
         else if (node.type === "html") html.push(node);
         else if (node.type === "paragraph") {
-            regions.push({ start: node.position.start.offset, end: node.position.end.offset });
+            const range = { start: node.position.start.offset, end: node.position.end.offset };
+            regions.push(range);
+            paragraphs.push(range);
             for (const child of node.children ?? []) inline(child);
         } else if (
             ["root", "blockquote", "list", "listItem", "footnoteDefinition"].includes(node.type)
@@ -214,7 +270,8 @@ function prose(source, capturedNames) {
     for (const entry of stack)
         if (entry.excluded) excluded.push({ start: entry.start, end: source.length });
     const allowed = ranges(regions),
-        literal = ranges(excluded);
+        literal = ranges(excluded),
+        prosaic = ranges(paragraphs);
     const eligible = (value) => contains(allowed, value) && !overlaps(literal, value);
     const actualLinks = links.filter(eligible).flatMap((link) => {
         if (link.wiki) return [link];
@@ -230,12 +287,229 @@ function prose(source, capturedNames) {
     const linked = ranges(authoredLinks);
     const marked = (capturedNames ?? scanSpans(source).names)
         .filter((span) => eligible(span) && !contains(linked, span))
-        .map((span) => ({ ...span, label: span.visible, nameKind: spanKind(span) }));
-    return { marked, links: authoredLinks };
+        .map((span) => ({
+            ...span,
+            label: span.visible,
+            nameKind: spanKind(span),
+            ref: readNameRef(span),
+        }));
+    return {
+        marked,
+        links: authoredLinks,
+        strong,
+        inParagraph: (value) => contains(prosaic, value),
+    };
+}
+
+/** Whether a wikilink marks a name: it carries the `.name` class. */
+const isNameLink = (link) => Boolean(link.wiki && link.attributes?.classes?.includes("name"));
+
+/**
+ * The addresses a page's names are read against: the tree's types and
+ * packages, and the package an address that names none belongs to.
+ *
+ * @typedef {object} NameVocabulary
+ * @property {Set<string>} [types] - Every type an address may name.
+ * @property {Set<string>} [packages] - Every package an address may name.
+ * @property {Set<string>} [noIndexPackages] - Packages with no content index.
+ * @property {string} [contentPackage] - The package the page belongs to.
+ */
+
+/**
+ * The key of a note address: its package, type and shortcode, so every
+ * spelling of one note, and each of its systems' documents, is one key. An
+ * address the vocabulary cannot read is keyed as written.
+ */
+function addressKey(address, { types, packages, noIndexPackages, contentPackage } = {}) {
+    const read =
+        types ? readQualifier(address, types, packages ?? new Set(), noIndexPackages) : null;
+    if (!read || read.reason) return `note:${address}`;
+    return `note:${read.package ?? contentPackage ?? ""}-${read.type}-${read.shortcode}`;
+}
+
+/** The key a span's use is counted under. */
+function spanKey(span, vocabulary) {
+    if (span.ref)
+        return isLocalRef(span.ref) ? `local:${span.ref}` : addressKey(span.ref, vocabulary);
+    const lang = span.attrs?.find(([key]) => key === "lang")?.[1] || "en";
+    return `label:${lang}:${normalize(span.label)}`;
+}
+
+/** The key a name wikilink's use is counted under: its address. */
+const linkKey = (link, vocabulary) =>
+    link.target ? addressKey(link.target, vocabulary) : `anchor:#${link.anchor}`;
+
+/** The 0-based line of each offset, by a sorted list of line starts. */
+function lineOf(starts, offset) {
+    let lo = 0,
+        hi = starts.length;
+    while (lo + 1 < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (starts[mid] <= offset) lo = mid;
+        else hi = mid;
+    }
+    return lo;
+}
+
+/**
+ * A use of a name in a page's prose.
+ *
+ * @typedef {object} NameUse
+ * @property {number} start - Inclusive UTF-16 offset of the use.
+ * @property {number} end - Exclusive UTF-16 offset after it, attributes included.
+ * @property {string} key - What the use is counted under.
+ * @property {boolean} emphasised - It sits inside authored strong text.
+ */
+
+/**
+ * Every use of a name in a body's prose, in source order.
+ *
+ * @param {string} markdown - A body, as authored or expanded.
+ * @param {NameVocabulary} [vocabulary] - What its addresses are read against.
+ * @returns {NameUse[]} The uses that count toward a first use.
+ */
+export function nameUses(markdown, vocabulary) {
+    const source = String(markdown ?? "");
+    // Every use carries the class, so a body without it is read no further.
+    if (!source.includes(".name")) return [];
+    const spans = scanSpans(source);
+    const { marked, links, strong, inParagraph } = prose(source, spans.names);
+    const starts = [0];
+    for (let i = 0; i < source.length; i++) if (source[i] === "\n") starts.push(i + 1);
+    // A caption and a named block's opening and closing lines are not prose.
+    const skipped = new Set();
+    for (const figure of scanFigures(source).figures)
+        for (let line = figure.captionStart; line < figure.captionEnd; line++) skipped.add(line);
+    const blocks = scanBlocks(source).blocks;
+    for (const one of blocks) skipped.add(one.start).add(one.end);
+    // A name inside a run that states a language, font or encoding is that
+    // run's text, never the page's prose.
+    const hasRunKey = (keys) => RUN_KEYS.some((key) => Object.hasOwn(keys, key));
+    const runLines = blocks
+        .filter((one) => hasRunKey(one.attributes ?? {}))
+        .map((one) => ({ start: one.start, end: one.end }));
+    const runSpans = spans.spans.filter((span) => hasRunKey(Object.fromEntries(span.attrs)));
+    const inRun = (use) =>
+        runSpans.some(
+            (span) =>
+                span.start <= use.start &&
+                span.end >= use.end &&
+                (span.start !== use.start || span.end !== use.end),
+        ) ||
+        runLines.some(
+            (range) =>
+                lineOf(starts, use.start) > range.start && lineOf(starts, use.start) < range.end,
+        );
+    const emphasised = (use) =>
+        strong.some((range) => range.start <= use.start && range.end >= use.end);
+    return [
+        ...links.filter(isNameLink).map((link) => ({ ...link, key: linkKey(link, vocabulary) })),
+        ...marked.map((span) => ({ ...span, key: spanKey(span, vocabulary) })),
+    ]
+        .filter((use) => inParagraph(use) && !skipped.has(lineOf(starts, use.start)) && !inRun(use))
+        .sort((a, b) => a.start - b.start)
+        .map((use) => ({
+            start: use.start,
+            end: use.end,
+            key: use.key,
+            emphasised: emphasised(use),
+        }));
+}
+
+/**
+ * Mark the first use of each name in a body's prose as bold.
+ *
+ * Each first use is wrapped in {@link FIRST_USE_OPEN} and
+ * {@link FIRST_USE_CLOSE}, which {@link firstUsePlugin} renders as strong
+ * text. A first use already inside authored strong text is left as it is.
+ *
+ * @param {string} markdown - A body's prose, with its generated sections split
+ *   off and its wikilinks not yet resolved.
+ * @param {NameVocabulary} [vocabulary] - What its addresses are read against.
+ * @returns {string} The same markdown with each first use marked.
+ */
+export function boldFirstUses(markdown, vocabulary) {
+    const source = String(markdown ?? "");
+    const seen = new Set(),
+        firsts = [];
+    for (const use of nameUses(source, vocabulary)) {
+        if (seen.has(use.key)) continue;
+        seen.add(use.key);
+        if (!use.emphasised) firsts.push(use);
+    }
+    let out = source;
+    for (const use of firsts.reverse())
+        out =
+            out.slice(0, use.start) +
+            FIRST_USE_OPEN +
+            out.slice(use.start, use.end) +
+            FIRST_USE_CLOSE +
+            out.slice(use.end);
+    return out;
 }
 
 /**
- * Prepare indexed names once, then check only explicit occurrences without reading files.
+ * Render the first-use marks {@link boldFirstUses} wrote as strong text.
+ *
+ * A mark in inline text opens or closes a `strong`; a mark anywhere else, as in
+ * raw HTML or code, is dropped, so no mark reaches a reader.
+ *
+ * @param {import("markdown-it")} md - Markdown parser to extend.
+ */
+export function firstUsePlugin(md) {
+    md.core.ruler.push("first_use", (state) => {
+        const Token = state.Token;
+        const strip = (token) => {
+            if (token.content?.includes(FIRST_USE_OPEN) || token.content?.includes(FIRST_USE_CLOSE))
+                token.content = token.content.replace(MARKS, "");
+        };
+        for (const token of state.tokens) {
+            if (token.type !== "inline") {
+                strip(token);
+                continue;
+            }
+            if (!token.children) continue;
+            const children = [];
+            for (const child of token.children) {
+                if (child.type !== "text" || !MARKS.test(child.content)) {
+                    MARKS.lastIndex = 0;
+                    strip(child);
+                    children.push(child);
+                    continue;
+                }
+                MARKS.lastIndex = 0;
+                for (const part of child.content.split(/([﷐﷑])/)) {
+                    if (part === FIRST_USE_OPEN || part === FIRST_USE_CLOSE) {
+                        const open = part === FIRST_USE_OPEN;
+                        const mark = new Token(
+                            open ? "strong_open" : "strong_close",
+                            "strong",
+                            open ? 1 : -1,
+                        );
+                        mark.level = child.level;
+                        children.push(mark);
+                    } else if (part) {
+                        const text = new Token("text", "", 0);
+                        text.content = part;
+                        text.level = child.level;
+                        children.push(text);
+                    }
+                }
+            }
+            token.children = children;
+        }
+    });
+}
+
+/**
+ * Prepare indexed names once, then check each note's marked names without
+ * reading files.
+ *
+ * One rule, a warning at the occurrence:
+ *
+ * - `unlinked-name`: a `.name` span with no `ref` names an indexed note, which
+ *   a link or a `ref` ties to its note.
+ *
  * @param {{records: readonly object[], index: object,
  *   catalog?: import("./names.mjs").NameCatalog,
  *   parsed?: Map<string, {raw: string, body: string, bodyLine?: number, bodyColumn?: number}>,
@@ -250,7 +524,7 @@ export function createFirstUseChecker({
     syntax,
     catalog = createNameCatalog({ records, index }),
 }) {
-    const { recognize: recognized, resolve } = catalog;
+    const { recognize } = catalog;
     return ({ file, raw }) => {
         const authored = parsed?.get(file);
         const capturedNames =
@@ -260,41 +534,7 @@ export function createFirstUseChecker({
                     { raw, bodyLine: authored.bodyLine, bodyColumn: authored.bodyColumn },
                 )
             :   undefined;
-        const { marked, links } = prose(raw, capturedNames);
-        const events = [
-            ...marked.map((span) => ({ ...span, kind: "marked" })),
-            ...links.map((link) => {
-                const target = link.wiki ? resolve(link.target) : undefined;
-                return {
-                    ...link,
-                    kind: "link",
-                    preferred: target,
-                    label:
-                        link.labelled ?
-                            link.wiki ?
-                                labelText(link.display || target?.full || "")
-                            :   link.display
-                        :   undefined,
-                };
-            }),
-        ].filter((event) => typeof event.label === "string" && normalize(event.label));
-        const unknown = new Map();
-        for (const event of [...events].sort(
-            (a, b) => a.label.length - b.label.length || a.label.localeCompare(b.label),
-        )) {
-            if (
-                recognized(event.label, event.preferred, event.nameKind) ||
-                unknown.has(normalize(event.label))
-            )
-                continue;
-            const entry = {
-                key: "name:" + normalize(event.label),
-                full: event.label,
-                fullUse: true,
-            };
-            for (const spelling of forms(event.label))
-                if (!unknown.has(spelling)) unknown.set(spelling, entry);
-        }
+        const { marked } = prose(raw, capturedNames);
         const findings = new Map();
         const add = (offset, rule, message) => {
             if (!findings.has(offset)) findings.set(offset, { rules: [], messages: [] });
@@ -304,56 +544,30 @@ export function createFirstUseChecker({
                 finding.messages.push(message);
             }
         };
-        const used = new Set(),
-            fullUsed = new Set();
-        for (const event of events.sort((a, b) => a.start - b.start)) {
-            const entry =
-                recognized(event.label, event.preferred, event.nameKind) ??
-                unknown.get(normalize(event.label));
-            if (event.kind === "marked" && entry.indexed) {
-                const destinations = (entry.candidates ?? [entry])
-                    .map((target) => target.key)
-                    .sort()
-                    .join(" or ");
-                add(
-                    event.start,
-                    "unlinked-name",
-                    `“${event.label}” names “${entry.full}”; use a link to “${destinations}”`,
-                );
-            }
-            if (used.has(entry.key))
-                add(
-                    event.start,
-                    "repeated-name",
-                    `“${entry.full}” is linked or marked more than once`,
-                );
-            // A resolved wikilink identifies its note, so its label may be any natural form.
-            const introduces = entry.fullUse || event.preferred !== undefined;
-            if (!introduces && !fullUsed.has(entry.key))
-                add(
-                    event.start,
-                    "short-before-full",
-                    `“${event.label}” appears before the full name “${entry.full}”`,
-                );
-            used.add(entry.key);
-            if (introduces) fullUsed.add(entry.key);
+        for (const span of marked) {
+            if (span.ref || !normalize(span.label)) continue;
+            const entry = recognize(span.label, undefined, span.nameKind);
+            if (!entry?.indexed) continue;
+            const destinations = (entry.candidates ?? [entry])
+                .map((target) => target.key)
+                .sort()
+                .join(" or ");
+            add(
+                span.start,
+                "unlinked-name",
+                `“${span.label}” names “${entry.full}”; use a link to “${destinations}”, or tie it with ref=`,
+            );
         }
         const lineStarts = [0];
         for (let i = 0; i < raw.length; i++) if (raw[i] === "\n") lineStarts.push(i + 1);
         return [...findings]
             .sort(([a], [b]) => a - b)
             .map(([offset, finding]) => {
-                let lo = 0,
-                    hi = lineStarts.length;
-                while (lo + 1 < hi) {
-                    const mid = (lo + hi) >>> 1;
-                    if (lineStarts[mid] <= offset) lo = mid;
-                    else hi = mid;
-                }
+                const line = lineOf(lineStarts, offset);
                 return {
                     file,
-                    line: lo + 1,
-                    column: offset - lineStarts[lo] + 1,
+                    line: line + 1,
+                    column: offset - lineStarts[line] + 1,
                     severity: "warning",
                     rules: finding.rules,
                     message: `first-use/${finding.rules.join("+")}: ${finding.messages.join("; ")}`,