@heroiclands/package-build 23.7.1 → 23.8.0

package/types/engine/diagnostics.d.mts

@@ -150,12 +150,14 @@ export function positionInFrontmatter(raw: string, key: string, value?: string,
  *   {@link positionInFrontmatter}.
  * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
  *   an identically named nested key cannot answer for it.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @returns {{line?: number, column?: number}|undefined} Spreadable position
  *   fields, dropped rather than guessed when the file cannot be read or the key
  *   cannot be found — as `formatDiagnostic` requires.
  */
-export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel }?: {
+export function locateFrontmatterKey(absPath: string | undefined, key: string, value?: string, { topLevel, raw }?: {
     topLevel?: boolean | undefined;
+    raw?: string | undefined;
 }): {
     line?: number;
     column?: number;
@@ -195,11 +197,10 @@ export function positionOfLiteral(text: string, needle: string, occurrence?: num
  * first occurrence is routinely not the one the finding is about — which is the
  * one thing the located form exists to prevent.
  *
- * A path resolves the exact node instead. The document is re-parsed here rather
- * than threaded from the loader because the loader returns plain data: `yaml`
- * discards ranges once a document is materialised, and carrying a parallel
- * position tree through configuration resolution would be a second
- * representation of the same file to keep in step.
+ * A path resolves the exact node. The most recently located text retains its
+ * document and line counter, so several findings in one note share a parse.
+ * A different text replaces that entry, including an edited copy of the same
+ * file. The loader returns plain data without source ranges.
  *
  * Every failure — unparseable text, an `.mjs` configuration, a path that
  * resolves to nothing — yields `{}`, so a caller spreads the result and the

package/types/engine/helpers.d.mts

@@ -19,17 +19,18 @@ export function renderFoundryMarkdown(body: string, figures?: Array<{
 /**
  * Parses a markdown file with YAML frontmatter.
  *
- * Returns `{ frontmatter, body, description, bodyLine, bodyColumn }` where
+ * Returns `{ frontmatter, body, description, bodyLine, bodyColumn, raw }` where
  * `body` is the trimmed raw markdown after the frontmatter block, and
- * `description` is `body` rendered to HTML. `bodyLine` / `bodyColumn` are the
+ * `description` is `body` rendered to HTML. The full source is retained as
+ * `raw` for diagnostic locations. `bodyLine` / `bodyColumn` are the
  * 1-based **file** position of the body's first character, which is what turns
  * an offset within `body` into a position a diagnostic can name — see
  * {@link positionInBody}. If the file has no frontmatter block, returns
- * `{ frontmatter: null, body: "", description: "" }` with a warn log, and no
+ * `{ frontmatter: null, body: "", description: "", raw }` and no
  * position: there is no body to have one.
  * @param {string} filePath - Markdown file to read.
  * @param {{addressContext?: object}} [opts] - Address defaults for decoded fields.
- * @returns {{frontmatter: object|null, body: string, description: string,
+ * @returns {{frontmatter: object|null, body: string, description: string, raw: string,
  *   bodyLine?: number, bodyColumn?: number, parseError?: {message: string,
  *   line?: number, column?: number}}} Parsed note and body position.
  */
@@ -39,6 +40,7 @@ export function parseMarkdownFile(filePath: string, { addressContext }?: {
     frontmatter: object | null;
     body: string;
     description: string;
+    raw: string;
     bodyLine?: number;
     bodyColumn?: number;
     parseError?: {
@@ -118,6 +120,7 @@ export function walkMarkdownTree(rootDir: string, { skipDirectories, addressCont
     frontmatter: object | null;
     body: string;
     description: string;
+    raw: string;
     bodyLine?: number;
     bodyColumn?: number;
     parseError?: {

package/types/engine/markdownlint-run.d.mts

@@ -9,8 +9,9 @@
  *   `config`, `ignores`, `gitignore` and `globs`.
  * @param {boolean} [params.fix=false] - Repair what markdownlint can, then
  *   report what remains.
- * @returns {Promise<{results: object[]}>} markdownlint results, each with its
+ * @returns {Promise<{results: object[], markup: object[]}>} markdownlint results, each with its
  *   `fileName` relative to `directory`, ordered by file, line and rule.
+ *   `markup` carries block syntax diagnostics with absolute filenames.
  * @throws {MarkdownConfigError} A configuration file the contract refuses.
  */
 export function runMarkdownlint(params: {
@@ -20,6 +21,7 @@ export function runMarkdownlint(params: {
     fix?: boolean | undefined;
 }): Promise<{
     results: object[];
+    markup: object[];
 }>;
 /** Keys an options file may declare at the repository root. */
 export const ROOT_OPTION_KEYS: readonly string[];

package/types/engine/markup-validation.d.mts

@@ -0,0 +1,14 @@
+/**
+ * Validate authored block syntax with positions in the original file.
+ * Frontmatter is masked so literal YAML values cannot become body markup.
+ * @param {string} source - Complete Markdown source, optionally with frontmatter.
+ * @param {string} file - Diagnostic filename.
+ * @returns {Array<{file: string, line: number, column: number, severity: string, message: string}>} Syntax errors.
+ */
+export function markupFindings(source: string, file: string): Array<{
+    file: string;
+    line: number;
+    column: number;
+    severity: string;
+    message: string;
+}>;

package/types/engine/note-addresses.d.mts

@@ -71,12 +71,21 @@ export const STRUCTURED_ADDRESSES: readonly ({
     noteType: string;
     path: (string | string[] | undefined)[];
     shape: string;
+} | {
+    path: string[];
+    shape: string;
+    lenient: boolean;
+    type?: undefined;
+    accepts?: undefined;
+    system?: undefined;
+    noteType?: undefined;
 } | {
     path: string[];
     shape: string;
     type: string;
     accepts: string[];
     system: string;
+    lenient?: undefined;
     noteType?: undefined;
 } | {
     noteType: string;
@@ -84,6 +93,7 @@ export const STRUCTURED_ADDRESSES: readonly ({
     shape: string;
     type: string;
     accepts: string[];
+    lenient?: undefined;
     system?: undefined;
 })[];
 export { AddressEntries, encodeAddresses, cloneAddressState, publishAddresses, readPublishedAddresses, flattenPublishedAddresses } from "./address-values.mjs";

package/types/engine/note-claims.d.mts

@@ -120,11 +120,17 @@ export function noteTypeVocabulary(sources?: ClaimSources): ReadonlySet<string>;
  * @param {object} [opts] - Options.
  * @param {readonly object[]} [opts.records] - The corpus, derived once by the
  *   compile and handed in — required, for the reason above.
+ * @param {Map<string, {body: string, raw: string}>} [opts.parsed] - Already parsed
+ *   notes, keyed by file, for body checks and finding positions.
  * @returns {Array<{file: string, line?: number, column?: number,
  *   severity: "error", message: string, type: string}>} One finding per note.
  */
-export function unclaimedNoteFindings(config?: object, sources?: ClaimSources, { records }?: {
+export function unclaimedNoteFindings(config?: object, sources?: ClaimSources, { records, parsed }?: {
     records?: readonly object[] | undefined;
+    parsed?: Map<string, {
+        body: string;
+        raw: string;
+    }> | undefined;
 }): Array<{
     file: string;
     line?: number;

package/types/engine/note-package.d.mts

@@ -21,13 +21,15 @@ export function searchableFrontmatter(fm: object | null | undefined, configured?
  * @param {string} [options.absPath] - The note's file on disk, read only on the
  *   failing path to locate the offending line and column. The position rides on
  *   the thrown error as `position`, for a caller that emits a diagnostic.
+ * @param {string} [options.raw] - Source text already read by the caller.
  * @param {string} [options.configured] - The package this build compiles.
  *   Defaults to the configured `contentPackage`.
  * @returns {void}
  * @throws {Error} When the note declares the field.
  */
-export function assertNoDeclaredPackage(fm: object | null | undefined, { file, absPath, configured }?: {
+export function assertNoDeclaredPackage(fm: object | null | undefined, { file, absPath, configured, raw }?: {
     file?: string | undefined;
     absPath?: string | undefined;
+    raw?: string | undefined;
     configured?: string | undefined;
 }): void;

package/types/engine/note-vocabulary.d.mts

@@ -476,6 +476,7 @@ export type DataFieldSpec = {
      */
     check?: ((note: object, opts: {
         index?: object;
+        addressContext?: object;
     }) => object[]) | undefined;
     /**
      * - The

package/types/engine/related-pages.d.mts

@@ -14,10 +14,11 @@
  *   the source page's URL and the target page's.
  * @param {ReadonlyMap<string, RelatedEntry>} entries - Every page of this
  *   site, keyed by URL.
+ * @param {ReadonlyMap<string, RelatedEntry[]>} [deliberate] Authored references, including foreign destinations.
  * @returns {Map<string, Related>} URL → the page's `related` block, both lists
  *   sorted, for every page with at least one entry in either.
  */
-export function relatedPages(edges: Iterable<readonly [string, string]>, entries: ReadonlyMap<string, RelatedEntry>): Map<string, Related>;
+export function relatedPages(edges: Iterable<readonly [string, string]>, entries: ReadonlyMap<string, RelatedEntry>, deliberate?: ReadonlyMap<string, RelatedEntry[]>): Map<string, Related>;
 /**
  * The pages a homepage's body links to, as URLs.
  *
@@ -50,6 +51,10 @@ export type RelatedEntry = {
      * site-root-relative form the page states for itself.
      */
     url: string;
+    /**
+     * Why the author recommends this page.
+     */
+    gloss?: string | undefined;
     /**
      * The note's `type`, which the theme groups by.
      */
@@ -59,6 +64,10 @@ export type RelatedEntry = {
  * The `related` block one page publishes.
  */
 export type Related = {
+    /**
+     * Deliberate references in authored order.
+     */
+    seeAlso?: RelatedEntry[] | undefined;
     /**
      * Pages that link to this one.
      */

package/types/engine/see-also.d.mts

@@ -0,0 +1,55 @@
+/**
+ * Validate note references, refusing unresolved, repeated and self destinations.
+ * @param {object} note - The authored note, including its raw source.
+ * @param {object} [options] - The local and declared dependency context.
+ * @param {object} [options.index] - The local and declared dependency index.
+ * @param {string} [options.index.contentPackage] - The package owning the note.
+ * @param {Set<string>} [options.index.types] - The indexed note types.
+ * @param {Set<string>} [options.index.packages] - The indexed packages.
+ * @param {(key: string) => {url?: string, uuid?: string, file?: string}|undefined}
+ *   [options.index.addressHit] - Resolve a canonical Address to its destination.
+ * @param {import("./address.mjs").AddressDefaults} [options.addressContext]
+ *   - The Address defaults and vocabularies at the authored reference.
+ * @returns {object[]} Findings located at the offending address.
+ */
+export function checkSeeAlso(note: object, { index, addressContext }?: {
+    index?: {
+        contentPackage?: string | undefined;
+        types?: Set<string> | undefined;
+        packages?: Set<string> | undefined;
+        addressHit?: ((key: string) => {
+            url?: string;
+            uuid?: string;
+            file?: string;
+        } | undefined) | undefined;
+    } | undefined;
+    addressContext?: import("./address.mjs").AddressDefaults | undefined;
+}): object[];
+/**
+ * Resolve deliberate references in authored order using the surface's index.
+ * @param {object} fm - The note frontmatter.
+ * @param {(address: unknown) => object|undefined} resolve - The surface's reference resolver.
+ * @returns {object[]} Display names, destinations and optional glosses.
+ */
+export function seeAlsoEntries(fm: object, resolve: (address: unknown) => object | undefined): object[];
+/**
+ * A generated section; an empty list emits nothing.
+ * @param {object[]} entries - Resolved references in authored order.
+ * @param {(entry: object) => string} link - The medium's link markup.
+ * @param {number} [level=2] - Heading level; a journal uses one for a separate page.
+ * @returns {string} Markdown for the section.
+ */
+export function seeAlsoMarkdown(entries: object[], link: (entry: object) => string, level?: number): string;
+/**
+ * A reference rendered as an ordinary Markdown link for the book pipeline.
+ * @param {object} entry - A resolved name and URL.
+ * @returns {string} Markdown.
+ */
+export function seeAlsoWebLink(entry: object): string;
+/**
+ * Deliberate site connections for a set of pages, including dependency pages.
+ * @param {object[]} pages - Pages carrying frontmatter and their published URL.
+ * @param {(address: unknown) => object|undefined} resolve - The site's reference resolver.
+ * @returns {Map<string, import("./related-pages.mjs").RelatedEntry[]>} Entries keyed by source URL.
+ */
+export function seeAlsoPages(pages: object[], resolve: (address: unknown) => object | undefined): Map<string, import("./related-pages.mjs").RelatedEntry[]>;

package/types/engine/sql-tables.d.mts

@@ -139,8 +139,9 @@ export function renderSqlTable(result: {
  * its own table and not the whole build's report.
  *
  * @param {object} db - From {@link openNotesDatabase}.
- * @param {Array<{source: string, markdown: string}>} sources - The bodies to
- *   scan.
+ * @param {Array<{source: string, markdown: string, frontmatter?: object, authoredSqlBlocks?: number}>} sources -
+ *   The bodies to scan. `joinGeneratedSections` records the number of authored
+ *   fences; following generated event fences need no stub comparison.
  * @param {object} [opts]
  * @param {(ref: string) => boolean} [opts.linkable] - Passed to
  *   {@link renderSqlTable}.
@@ -163,6 +164,8 @@ export function renderSqlTable(result: {
 export function prepareSqlTables(db: object, sources: Array<{
     source: string;
     markdown: string;
+    frontmatter?: object;
+    authoredSqlBlocks?: number;
 }>, { linkable, records, pageLanguage }?: {
     linkable?: ((ref: string) => boolean) | undefined;
     pageLanguage?: ((source: string, frontmatter?: object) => string | undefined) | undefined;
@@ -216,7 +219,7 @@ export function generatedSectionsFor(db: object | undefined, records: object[],
  *
  * @param {{sections: Map<string, string>, views: Set<string>}} generated -
  *   From {@link generatedSectionsFor}.
- * @param {Array<{source: string, markdown: string, frontmatter?: object}>} sources -
+ * @param {Array<{source: string, markdown: string, frontmatter?: object, authoredSqlBlocks?: number}>} sources -
  *   The bodies to answer, extended in place.
  * @param {Map<string, {body: string, frontmatter: object|null}>} [parsed] -
  *   Notes already parsed, keyed by file; a note absent from it is read.
@@ -229,6 +232,7 @@ export function joinGeneratedSections(generated: {
     source: string;
     markdown: string;
     frontmatter?: object;
+    authoredSqlBlocks?: number;
 }>, parsed?: Map<string, {
     body: string;
     frontmatter: object | null;