@heroiclands/package-build 22.4.2 → 22.4.3

package/types/engine/changelog-lint.d.mts

@@ -1,11 +1,89 @@
+/**
+ * Where a character offset in `text` falls, as a 1-based line and column.
+ *
+ * @param {string} text - The text the offset indexes into.
+ * @param {number} index - 0-based character offset.
+ * @returns {{line: number, column: number}}
+ */
+export function lineColOf(text: string, index: number): {
+    line: number;
+    column: number;
+};
+/**
+ * Every code region in `text`, as a set of 1-based line numbers it spans.
+ *
+ * Block-level only (`spans: false`): an inline code span does not remove a
+ * whole line from consideration, only the characters it covers, which the
+ * text-scanning rules mask separately.
+ *
+ * @param {string} text - The section text.
+ * @returns {Set<number>} Lines that fall inside a fenced or indented block.
+ */
+export function codeLineSet(text: string): Set<number>;
+/**
+ * Every top-level bullet, as its own contiguous run of lines.
+ *
+ * A bullet's continuation — a wrapped line, a second paragraph, a nested
+ * elaboration — is indented under it and belongs to it; a line back at
+ * column 0 that is not itself a bullet (a bold subsection label, ordinary
+ * prose) closes it.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @returns {Array<{startLine: number, text: string}>}
+ */
+export function topLevelBullets(text: string, codeLines: Set<number>): Array<{
+    startLine: number;
+    text: string;
+}>;
+/**
+ * Every top-level block of release prose — one rendered changeset entry, or
+ * one unlabelled paragraph standing in for one.
+ *
+ * `@heroiclands/package-build/changelog` (`changelog.cjs`) writes a
+ * changeset's whole summary as one block, verbatim, so a block here holds
+ * together the same way that summary is authored: a bold label opening a
+ * line at column 0 (`**Compendiums**`) starts a new block, and — unlike
+ * {@link topLevelBullets}, where a bullet marker *is* the top-level
+ * construct — a `-` bullet at column 0 belongs to whatever block is
+ * already open, since a label's bullets sit unindented directly under it.
+ * Any other column-0 line (plain prose with no label, a bullet with no
+ * block open yet) starts the one "lead" block (`label: null`) a changeset
+ * with no category writes — the case `changelog group` sorts first and
+ * `check` never flags. Nested detail — a wrapped line, a bullet's own
+ * continuation — stays indented and belongs to whatever it follows.
+ * `changelog group` folds same-label blocks together; `check` warns when a
+ * block's label is not in the declared vocabulary.
+ *
+ * @param {string} text - Section text.
+ * @param {Set<number>} codeLines - Lines inside a code region, from
+ *   {@link codeLineSet}.
+ * @param {Set<number>} [scaffoldLines] - Generated heading lines that close
+ *   whatever block is open without starting one, from
+ *   {@link scaffoldLineSet} — empty for a caller that already isolated one
+ *   `### <Bump> Changes` body, since no heading falls inside it.
+ * @returns {Array<{startLine: number, label: string|null, text: string}>}
+ */
+export function topLevelBlocks(text: string, codeLines: Set<number>, scaffoldLines?: Set<number>): Array<{
+    startLine: number;
+    label: string | null;
+    text: string;
+}>;
 /**
  * Lint one pending changeset (`.changeset/*.md`).
  *
  * @param {string} text - The file's full contents, frontmatter included.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintChangesetText(text: string): {
+export function lintChangesetText(text: string, { labels }?: {
+    labels?: readonly string[] | null | undefined;
+}): {
     findings: Array<{
         line: number;
         column?: number;
@@ -17,10 +95,16 @@ export function lintChangesetText(text: string): {
  * Lint the first `## <version>` release section of a `CHANGELOG.md`.
  *
  * @param {string} text - The changelog's full contents.
+ * @param {object} [opts]
+ * @param {readonly string[]|null} [opts.labels] - `changelog.labels`, in
+ *   display order, or `null`/absent when the repository declares none —
+ *   {@link checkUnknownLabels} checks nothing in that case.
  * @returns {{findings: Array<{line?: number, column?: number,
  *   severity: "error"|"warning", message: string}>}}
  */
-export function lintReleaseText(text: string): {
+export function lintReleaseText(text: string, { labels }?: {
+    labels?: readonly string[] | null | undefined;
+}): {
     findings: Array<{
         line?: number;
         column?: number;
@@ -28,6 +112,27 @@ export function lintReleaseText(text: string): {
         message: string;
     }>;
 };
+/**
+ * The first `## <version>` release section of a changelog, as raw character
+ * offsets rather than {@link extractReleaseSection}'s line-joined copy.
+ *
+ * `extractReleaseSection` rebuilds its `body` by joining a slice of
+ * `text.split("\n")`, which is fine for reporting a line number but drops
+ * the exact byte the next `## ` heading sits after — a caller rewriting the
+ * file in place, such as `changelog group`, needs `text.slice(start, end)`
+ * to be the section verbatim, so it can splice a replacement back in without
+ * guessing at the whitespace on either side.
+ *
+ * @param {string} text - The changelog's full contents.
+ * @returns {{start: number, end: number}|null} `null` when no `## ` heading
+ *   is present. `text.slice(start, end)` is the section, byte-exact,
+ *   including whatever separates it from the next `## ` heading or the end
+ *   of the file.
+ */
+export function releaseSectionRange(text: string): {
+    start: number;
+    end: number;
+} | null;
 /**
  * The finding one rule reports, before its line is mapped into the caller's
  * file.