@heroiclands/package-build 22.4.5 → 22.4.7

package/types/engine/site-build.d.mts

@@ -176,7 +176,10 @@ export function tableUniverse(pages: object[]): Map<string, object[]>;
  * about every other page, known only once the whole tree has resolved — see
  * {@link module:engine/related-pages} — so an authored value is dropped the
  * way `aliases` is, and {@link renderPages} writes the derived block once it
- * holds the graph.
+ * holds the graph. `contains`, `held_by` and `holdings` are dropped for the
+ * same reason — see {@link module:engine/holdings}. **So is `map`**: the
+ * file a place page names is the one the build drew beside it — see
+ * {@link module:engine/site-maps} — and a page with no drawing names none.
  *
  * @param {object} page - The page.
  * @param {object} options
@@ -210,10 +213,21 @@ export function pageFrontmatter(page: object, { decorate, webSrc, artSrc }: {
  * `doc` note's `subType` may be spelled the same as another note's `type`, and
  * `doc-gear.md` and `weapongear-gear.md` are distinct.
  *
+ * **A page that carries a file beside itself is a leaf bundle**, `<slug>/index.md`,
+ * because that is the one shape under which Hugo hands a page its own
+ * resources — the map from a place, inlined by the theme through
+ * `.Resources.Get`. The directory is the page, not a section: it holds no
+ * `_index.md`, and the page's stated `url` keeps its address exactly where the
+ * flat file's was.
+ *
  * @param {object} page - The page.
+ * @param {object} [opts]
+ * @param {boolean} [opts.bundle=false] - Whether the page carries a resource.
  * @returns {string} The file, relative to the mount.
  */
-export function pageDestination(page: object): string;
+export function pageDestination(page: object, { bundle }?: {
+    bundle?: boolean | undefined;
+}): string;
 /**
  * Renders and writes every page.
  *
@@ -236,16 +250,25 @@ export function pageDestination(page: object): string;
  * point the resolver answers, and inverted once between them. Nothing is
  * resolved twice.
  *
+ * **A map is written with its page.** The drawing from a place is made before
+ * this render — see {@link module:engine/site-maps} — and handed in keyed by
+ * page URL; the page that owns one is written as a leaf bundle, the file is
+ * copied beside it, and the front matter names it as `map`. Every other page
+ * is written flat, and carries no such key.
+ *
  * @param {object[]} pages - Every page.
  * @param {object} options - Everything the render needs. `homepages` is the
  *   homepage as the index knows it — `{ fm, body, url, title }` — which takes
  *   no part in the render and every part in the graph: a content page links
- *   it by wikilink, and its own markdown links name content pages.
+ *   it by wikilink, and its own markdown links name content pages. `maps` is
+ *   each drawing by the URL of the page that carries it.
  * @returns {{written: number, byKind: Record<string, number>, tableErrors: object[],
  *   wikiErrors: object[], imageErrors: object[],
- *   related: Map<string, import("./related-pages.mjs").Related>}} `related`
+ *   related: Map<string, import("./related-pages.mjs").Related>,
+ *   maps: number}} `related`
  *   is keyed by page URL, and holds the homepage's block beside every content
  *   page's, so the caller can write it on the page this render does not.
+ *   `maps` counts the pages written with one.
  */
 export function renderPages(pages: object[], options: object): {
     written: number;
@@ -254,6 +277,7 @@ export function renderPages(pages: object[], options: object): {
     wikiErrors: object[];
     imageErrors: object[];
     related: Map<string, import("./related-pages.mjs").Related>;
+    maps: number;
 };
 /**
  * Resolves `site.pass` to its bundle.
@@ -281,18 +305,25 @@ export function resolveSitePass(name: string | undefined, options: object): {
  *   {@link module:engine/sql-tables.prepareSqlTables}. A page authoring an
  *   `sql` directive with none prepared is a table error: nothing here runs a
  *   query.
+ * @param {(engine: string) => string|undefined} [options.locate] - How a
+ *   GraphViz engine's binary is found, for the maps; the real lookup by
+ *   default.
  * @returns {{gates: object, stats: object|null, tableErrors: object[],
- *   wikiErrors: object[], imageErrors: object[], manifests: object|null}}
+ *   wikiErrors: object[], imageErrors: object[], mapFindings: object[],
+ *   manifests: object|null}} `mapFindings` is what drawing the maps found —
+ *   warnings, never a reason to fail the build.
  */
-export function buildSite({ config, sqlTables }?: {
+export function buildSite({ config, sqlTables, locate }?: {
     config?: object | undefined;
     sqlTables?: Map<string, object[]> | undefined;
+    locate?: ((engine: string) => string | undefined) | undefined;
 }): {
     gates: object;
     stats: object | null;
     tableErrors: object[];
     wikiErrors: object[];
     imageErrors: object[];
+    mapFindings: object[];
     manifests: object | null;
 };
 export { formatUnaddressableFinding };

package/types/engine/site-maps.d.mts

@@ -0,0 +1,81 @@
+/**
+ * A drawing as the page writer receives it.
+ *
+ * @typedef {object} SiteMap
+ * @property {string} name - The file's name in the page's bundle, and the
+ *   value of the page's `map` key: `from-<shortcode>.svg`.
+ * @property {string} file - Where the drawing is, absolute.
+ */
+/**
+ * A GraphViz SVG rewritten for inlining in an HTML page.
+ *
+ * GraphViz writes a standalone document: an XML declaration, a DOCTYPE naming
+ * the SVG 1.1 DTD by URL, generator comments, a root sized in points beside
+ * its `viewBox`, and links through the `xlink` namespace. Inline in HTML the
+ * prologue is invalid, the DTD reference is the one external reference the
+ * drawing would carry, the fixed size fights the column it sits in, and
+ * `xlink:` is the pre-SVG-2 spelling. So the prologue and the comments go,
+ * the root keeps its `viewBox` and loses `width` and `height`, and
+ * `xlink:href` and `xlink:title` become `href` and `title`, with the
+ * namespace declaration they needed.
+ *
+ * @param {string} svg - The SVG as GraphViz wrote it.
+ * @returns {string} The SVG to inline, starting at `<svg`.
+ */
+export function inlineSvg(svg: string): string;
+/**
+ * Draw the map from every related place of this package.
+ *
+ * @param {object} opts
+ * @param {Array<Record<string, any>>} opts.records - The package's index
+ *   records, as the site build read them.
+ * @param {Map<string, object>} opts.foreignIndex - The fetched indexes the
+ *   site build resolved links against.
+ * @param {object} opts.config - The resolved configuration.
+ * @param {string} opts.base - The site base every page is served under,
+ *   ending in a slash: what every name in a drawing links through.
+ * @param {(engine: string) => string|undefined} [opts.locate] - How the
+ *   engine's binary is found; the real lookup by default.
+ * @returns {{maps: Map<string, SiteMap>, findings: Array<{file: string,
+ *   line?: number, column?: number, severity: "error"|"warning",
+ *   message: string}>}} The drawings, keyed by the URL of the page each
+ *   belongs to, and what the drawing found — one warning naming what to
+ *   install when GraphViz is absent, and a warning for each relation that
+ *   names no place.
+ */
+export function drawSiteMaps({ records, foreignIndex, config, base, locate }: {
+    records: Array<Record<string, any>>;
+    foreignIndex: Map<string, object>;
+    config: object;
+    base: string;
+    locate?: ((engine: string) => string | undefined) | undefined;
+}): {
+    maps: Map<string, SiteMap>;
+    findings: Array<{
+        file: string;
+        line?: number;
+        column?: number;
+        severity: "error" | "warning";
+        message: string;
+    }>;
+};
+/**
+ * Where the site build draws, below the package root.
+ *
+ * @type {string}
+ */
+export const SITE_MAP_DIR: string;
+/**
+ * A drawing as the page writer receives it.
+ */
+export type SiteMap = {
+    /**
+     * - The file's name in the page's bundle, and the
+     * value of the page's `map` key: `from-<shortcode>.svg`.
+     */
+    name: string;
+    /**
+     * - Where the drawing is, absolute.
+     */
+    file: string;
+};