@heroiclands/package-build 17.1.0 → 18.0.0

package/engine/wikilinks.mjs

@@ -86,6 +86,8 @@
 import crypto from "crypto";
 
 import { compendiumUuid, ITEM_PACK, packForType, pageUuid, PACK_BY_TYPE } from "./ids.mjs";
+import { readCanonicalKey } from "./content-address.mjs";
+import { isSystemSegment } from "./systems.mjs";
 import { hasDocEntry, itemDocEntryId } from "./item-docs.mjs";
 import { replaceOutsideCode } from "./code-fences.mjs";
 // The syntax lives in `./wikilink-syntax.mjs`, so the web resolver and this
@@ -149,66 +151,104 @@ export function resolveItemDocType(qualifier, types) {
  * Two separators are accepted, and they are **not** interchangeable in how
  * confidently they mark a target as qualified:
  *
- * - **`type-shortcode`** — the canonical form (#1398). Obsidian reads `/` inside
- *   a wikilink as a *path* and resolves it against the vault's folders, so a
- *   slash-qualified link is a broken link in the editor where the content is now
- *   authored. A hyphen qualifies **only when what precedes it is a known type**:
- *   note names contain hyphens too (`Grukar-ahk`), and a target that is one is
- *   reported as not an address rather than split at an arbitrary place. The
- *   split is at the **first** hyphen, so a shortcode may itself contain one
- *   (`trauma-self-pro` → `trauma` + `self-pro`).
+ * - **`type-shortcode`** and its qualified forms — the canonical spelling
+ *   (#1398). Obsidian reads `/` inside a wikilink as a *path* and resolves it
+ *   against the vault's folders, so a slash-qualified link is a broken link in
+ *   the editor where the content is now authored.
  * - **`type/shortcode`** — the legacy form, still resolved so that a link
  *   written before the vault migrated does not silently die. A slash is
  *   *unconditionally* a qualifier: nothing else uses one, so an unknown type
  *   before it is reported rather than guessed at. The split is at the **last**
  *   slash, as it always was.
  *
- * A leading **package** segment is optional and outermost: `sohl-skill-lang` is
- * `skill-lang` in the `sohl` package. It is read only when `packages` is given
- * and names the segment, and only when the remainder is itself a valid address,
- * so a note called "Grukar-ahk" is not mistaken for one (#1499).
+ * **The grammar is strict, and omission runs left to right** (#59):
+ *
+ * ```text
+ * [[[[<package>-]<system>-]<type>-]<shortcode>]
+ * ```
+ *
+ * So the written forms are exactly the suffixes of the canonical address —
+ * `type-shortcode`, `system-type-shortcode`, `package-system-type-shortcode` —
+ * and **`package-type-shortcode` is not one of them**. A link into another
+ * package must therefore be fully qualified, which is the price of the segment
+ * being positional rather than tagged.
+ *
+ * **Parsing is plain positional counting**, the same rule
+ * {@link readCanonicalKey} follows, and it is sound for the same reason: every
+ * segment is `^[A-Za-z0-9]+$` (`ADDRESS_SEGMENT_PATTERN`, enforced on
+ * shortcodes by `content-lint.mjs` since #1397), so the hyphen is purely a
+ * separator and the count alone determines every field. Verified across the
+ * four content trees: 138,204 authored shortcodes, none carrying a separator.
+ *
+ * That replaced a first-hyphen split which let a shortcode contain a hyphen
+ * (`trauma-self-pro` → `trauma` + `self-pro`). The tolerance predates #1397 and
+ * outlived it; no tree has used it, and keeping it would make a three-segment
+ * target ambiguous between a system and a hyphenated shortcode.
+ *
+ * **`sohl` is both a package and a system**, and positional counting is what
+ * makes that harmless: three segments is `<system>-<type>-<shortcode>` whatever
+ * the first segment could also have named, and four is the full form. Nothing
+ * has to guess which sense was meant.
+ *
+ * **A partial address states what it states, and the rest is not invented.** An
+ * omitted **system** is a *wildcard* — most links target items, which belong to
+ * a system — so the caller matches on the segments supplied and requires
+ * exactly one hit. An omitted **package** is instead *defaulted* to the citing
+ * note's own, so an unqualified link resolves locally and only locally.
  *
  * @param {string} target - The link target, anchor already removed.
  * @param {Set<string>} types - Every type the content tree contains.
  * @param {Set<string>} [packages] - Every package an address may name. Omitted
  *   by callers that resolve within one package, where the form cannot occur.
  * @returns {{type: string, shortcode: string, itemDoc: boolean,
- *   package?: string, reason?: undefined} | {reason: "unknown-type"} | null}
+ *   package?: string, system?: string, reason?: undefined}
+ *   | {reason: "unknown-type"} | null}
  *   The resolved qualifier; a `reason` when the target is definitely qualified
  *   but names no known type; or `null` when it is not an address at all.
  */
 export function readQualifier(target, types, packages) {
-    // A leading **package** segment is the optional outermost qualifier:
-    // `sohl-skill-lang` is `skill-lang` in the `sohl` package. It is stripped
-    // here so everything below reads the same `type`/`shortcode` it always did,
-    // and it is recognised only when what precedes the hyphen is a package this
-    // build knows *and* the remainder is itself a valid address — so a note
-    // named "Sohl-something" is not mistaken for one (#1499).
-    if (packages?.size) {
-        const hyphen = target.indexOf("-");
-        if (hyphen > 0) {
-            const pkg = norm(target.slice(0, hyphen));
-            if (packages.has(pkg)) {
-                const rest = readQualifier(target.slice(hyphen + 1), types);
-                if (rest && !rest.reason) return { ...rest, package: pkg };
-            }
-        }
-    }
-
+    // The slash form is legacy and states neither package nor system, so it is
+    // read first and separately. A slash is unconditionally a qualifier —
+    // nothing else uses one — which is why an unknown type before it is
+    // *reported* rather than read as prose.
     const slash = target.lastIndexOf("/");
     if (slash > 0) {
         const read = readTypeAndCode(target.slice(0, slash), target.slice(slash + 1), types);
-        // A slash means qualified whether or not the type is real.
         return read ?? { reason: "unknown-type" };
     }
 
-    const hyphen = target.indexOf("-");
-    if (hyphen > 0) {
-        // A hyphen qualifies only on a known type; otherwise it is part of a
-        // name, and a name is not an address.
-        return readTypeAndCode(target.slice(0, hyphen), target.slice(hyphen + 1), types);
+    const parts = target.split("-");
+    switch (parts.length) {
+        // `<type>-<shortcode>`
+        case 2:
+            return readTypeAndCode(parts[0], parts[1], types);
+
+        // `<system>-<type>-<shortcode>` — the package defaults to local.
+        case 3: {
+            const system = norm(parts[0]);
+            if (!isSystemSegment(system)) return null;
+            const read = readTypeAndCode(parts[1], parts[2], types);
+            return read && { ...read, system };
+        }
+
+        // `<package>-<system>-<type>-<shortcode>` — the only form that names
+        // another package, and the reason a cross-package link must be fully
+        // qualified.
+        case 4: {
+            const pkg = norm(parts[0]);
+            if (!packages?.has(pkg)) return null;
+            const system = norm(parts[1]);
+            if (!isSystemSegment(system)) return null;
+            const read = readTypeAndCode(parts[2], parts[3], types);
+            return read && { ...read, system, package: pkg };
+        }
+
+        // One segment is a bare name, which is not an address (#180); five or
+        // more is not a hyphenated shortcode but a name that happens to carry
+        // separators, since no segment may contain one.
+        default:
+            return null;
     }
-    return null;
 }
 
 /**
@@ -363,12 +403,14 @@ export function buildWikilinkIndex(docs, packageId, foreign, contentPackage) {
 /**
  * The foreign manifest entry an address names, or `null`.
  *
- * A package-qualified address is one lookup. An unqualified one names no
- * package, so it
- * resolves against whichever foreign package publishes it — and only when
- * exactly one does. Claimed by two, it is genuinely ambiguous and the author
- * writes the qualified form; guessing would make the build depend on which
- * manifest happened to load first.
+ * A target is a **partial** address, matched on the segments it supplies with
+ * the rest wildcarded (#59) — so a package-qualified one is a scan rather than
+ * a single lookup, and may still match one entry per system. An unqualified one
+ * names no package either, so it resolves against whichever foreign package
+ * publishes it — and, in both readings, only when exactly one entry matches.
+ * Claimed by two, it is genuinely ambiguous and the author writes the qualified
+ * form; guessing would make the build depend on which manifest happened to load
+ * first.
  *
  * @param {object} index - From {@link buildWikilinkIndex}.
  * @param {object|null} read - The parsed qualifier, or `null` when the target
@@ -397,15 +439,28 @@ function foreignHits(index, read) {
     if (!read || read.reason || !index.foreign?.size) return [];
     const wanted = norm(read.itemDoc ? `doc${read.type}` : read.type);
     const shortcode = norm(read.shortcode);
-    if (read.package) {
-        const one = index.foreign.get(`${read.package}-${wanted}-${shortcode}`.toLowerCase());
-        return one ? [one] : [];
-    }
+
+    // One filter for every reading, because an address is matched **by the
+    // segments it supplies** and wildcarded on the ones it does not (#59). A
+    // package-qualified target used to take a separate exact-`get` path, which
+    // is what let this function carry its own copy of the key grammar — a
+    // hand-built `${package}-${type}-${shortcode}` and a literal segment count
+    // — and drift from `readCanonicalKey` the moment the grammar gained a
+    // system segment. There is one reader now.
+    //
+    // The system is a wildcard unless the target states one: most authored
+    // links name none, and defaulting it to `none` would exclude every link to
+    // an item, which is the majority — 1,632 of `sohl`'s own resolve into the
+    // items pack. Ambiguity is caught by the caller's single-hit rule rather
+    // than pre-empted by a guess here.
     const hits = [];
-    for (const [key, v] of index.foreign) {
-        const parts = key.split("-");
-        if (parts.length !== 3) continue;
-        if (parts[1] === wanted && parts[2] === shortcode) hits.push(v);
+    for (const [key, entry] of index.foreign) {
+        const parts = readCanonicalKey(key);
+        if (!parts) continue;
+        if (read.package && parts.package !== norm(read.package)) continue;
+        if (read.system && parts.system !== norm(read.system)) continue;
+        if (parts.type !== wanted || parts.shortcode !== shortcode) continue;
+        hits.push(entry);
     }
     return hits;
 }
@@ -640,6 +695,24 @@ export function convertWikilinks(markdown, { type, id, pack, docPack, index }) {
         // and is dropped. Forging a JournalEntryPage id onto a document that
         // can never hold one is what made such links dead-end (#1362); an
         // item's pages are addressed through its `doc<type>` counterpart.
+        // A `#section` the target declares no heading for. Checked here, and
+        // not only by `content-build links`, because this is the build that
+        // *emits* the link: `anchorPageId` will hash any slug into a page id,
+        // so an undeclared one compiles to a `@UUID` that dead-ends for the
+        // reader (#193). A foreign anchor has always been checked this way —
+        // the manifest carries the map — and a local one now is too, from the
+        // anchor set the index carries.
+        if (slug && isJournal && doc.anchors && !doc.anchors.has(slug)) {
+            unresolved.push({
+                link: all,
+                target,
+                offset,
+                reason: "unknown-anchor",
+                anchor: slug,
+                addressed: true,
+            });
+            return unresolvedLink(text || doc.name || target, target);
+        }
         const uuid =
             slug && isJournal ? pageUuid(entryUuid, anchorPageId(entryId, slug)) : entryUuid;
         const link = `@UUID[${uuid}]{${text}}`;

package/engine/yaml-lint.mjs

@@ -0,0 +1,282 @@
+/*
+ * 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
+ */
+
+/**
+ * Lint YAML — a note's frontmatter, and every YAML file in the repository.
+ *
+ * Frontmatter is load-bearing here in a way ordinary prose is not: it carries a
+ * note's type, its shortcode, its address and the system blocks a document is
+ * compiled from. Until this existed nothing checked it *as YAML*. The parse
+ * happened in {@link module:engine/helpers.parseMarkdownFile}, and a failure was
+ * caught, logged at `warn`, and turned into `{frontmatter: null}` — so a note
+ * with a duplicate key did not fail a build, it quietly stopped being a note.
+ * Every pass downstream then saw a file with no frontmatter and skipped it, and
+ * the build reported success.
+ *
+ * @module
+ */
+
+import { execFileSync } from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+
+/** File extensions that carry YAML, either wholly or in a frontmatter fence. */
+export const YAML_GLOBS = Object.freeze(["*.md", "*.yaml", "*.yml"]);
+
+/**
+ * Directories skipped whatever git says, because git does not know about them.
+ *
+ * `.git` is in nobody's `.gitignore`, and a worktree under `.claude/` is a
+ * checkout of this same repository — linting it reports every finding once per
+ * worktree, against paths the author cannot edit from here.
+ */
+const ALWAYS_SKIP = Object.freeze([".git/", ".claude/"]);
+
+/** A markdown file's leading frontmatter fence. Mirrors `parseMarkdownFile`. */
+const FENCE = /^---\n([\s\S]*?)\n---/;
+
+/**
+ * Present a markdown file to ESLint as the YAML it begins with.
+ *
+ * An ESLint *processor* carves virtual files out of a container file — the
+ * mechanism `eslint-plugin-markdown` uses for fenced code blocks. Frontmatter is
+ * the easy case of it: the block is always at the top of the file, so mapping a
+ * finding back to the file it came from is a constant `+1` for the opening
+ * `---`, with no offset table to keep.
+ *
+ * The virtual file is named `0.yaml` so the flat config's `**` + `*.yaml`
+ * patterns select it; ESLint addresses it as `<the note>.md/0.yaml`.
+ *
+ * @type {{meta: object, supportsAutofix: boolean,
+ *   preprocess: (text: string) => Array<{text: string, filename: string}>,
+ *   postprocess: (messages: object[][]) => object[]}}
+ */
+export const frontmatterProcessor = {
+    meta: { name: "package-build/frontmatter", version: "1" },
+    // Every rule applied here is a correctness rule with no fix, and a fix
+    // written back through the processor would have to be re-offset into the
+    // container file. Nothing is gained by claiming support for it.
+    supportsAutofix: false,
+    preprocess(text) {
+        const fence = FENCE.exec(text);
+        return fence ? [{ text: fence[1], filename: "0.yaml" }] : [];
+    },
+    postprocess(messages) {
+        return (messages[0] ?? []).map((message) => ({
+            ...message,
+            line: message.line + 1,
+            ...(message.endLine == null ? {} : { endLine: message.endLine + 1 }),
+        }));
+    },
+};
+
+/**
+ * The shared rule set, as an ESLint flat configuration.
+ *
+ * **Deliberately narrow, for the same reason the markdown and stylesheet rule
+ * sets are** — Prettier already owns YAML's whitespace, quoting and line
+ * breaks, including inside a frontmatter fence, so a rule about any of those
+ * would either duplicate the formatter or fight it. What is left is the class
+ * the formatter cannot see: text that parses to something other than what it
+ * looks like.
+ *
+ * - **A parse error is reported, not swallowed.** A duplicate key, a tab used
+ *   as indentation, a mapping whose items start at different columns: the YAML
+ *   parser detects all three and `parseMarkdownFile` discards all three.
+ * - `no-empty-mapping-value` — `folder:` and `folder: null` parse identically
+ *   and read as opposites: one is a decision, the other is a key somebody began
+ *   and did not finish. YAML cannot tell them apart, so the distinction has to
+ *   be made where the text still exists. A key with a block under it is not
+ *   empty, which is what separates 65 unfinished keys in `sohl-thalorna` from
+ *   the tens of thousands that are ordinary containers.
+ * - `no-irregular-whitespace` — a non-breaking space in a key or an unquoted
+ *   scalar is invisible in every editor and changes the value.
+ * - `no-empty-key`, `no-empty-document` — a fence or a file that parses to
+ *   nothing at all.
+ *
+ * **GitHub workflows are exempt from `no-empty-mapping-value`**, because an
+ * empty value is the language there: `on:` `push:` and `workflow_dispatch:`
+ * carry their meaning by being present, and writing `push: null` to satisfy a
+ * linter would be worse YAML, not better.
+ *
+ * @param {object} plugin - The `eslint-plugin-yml` module.
+ * @returns {object[]} A complete flat config, for `overrideConfig`.
+ */
+export function yamlLintConfig(plugin) {
+    return [
+        ...plugin.configs["flat/recommended"],
+        { files: ["**/*.md"], processor: frontmatterProcessor },
+        {
+            files: ["**/*.yaml", "**/*.yml", "**/*.md/*.yaml"],
+            rules: {
+                "yml/no-empty-mapping-value": "error",
+                "yml/no-irregular-whitespace": "error",
+                "yml/no-empty-key": "error",
+            },
+        },
+        {
+            files: [
+                "**/.github/workflows/*.yml",
+                "**/.github/workflows/*.yaml",
+                "**/action.yml",
+                "**/action.yaml",
+            ],
+            rules: { "yml/no-empty-mapping-value": "off" },
+        },
+    ];
+}
+
+/**
+ * The files to lint: every YAML file git would consider, and no other.
+ *
+ * `--cached --others --exclude-standard` is tracked files plus untracked ones
+ * that are not ignored, which is the same set `gitignore: true` gives the
+ * markdown linter — and it matters more than it sounds. Asking ESLint for
+ * `**\/*.md` in `Song-of-Heroic-Lands-FoundryVTT` offers it 60,792 files, almost
+ * all of them inside `nogit/` and `.claude/worktrees/`; this offers 1,888, in
+ * 20ms. Untracked-but-not-ignored is included so a note gets linted while it is
+ * being written, not only once it has been staged.
+ *
+ * `-z` because git otherwise quotes any path outside ASCII, and these trees are
+ * full of them.
+ *
+ * @param {string} root - Repository root.
+ * @param {readonly string[]} [globs] - Path globs, defaulting to
+ *   {@link YAML_GLOBS}.
+ * @returns {string[]} Repository-relative paths.
+ */
+export function candidateFiles(root, globs = YAML_GLOBS) {
+    let listed;
+    try {
+        listed = execFileSync(
+            "git",
+            ["ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", ...globs],
+            {
+                cwd: root,
+                encoding: "utf8",
+                maxBuffer: 64 * 1024 * 1024,
+                // Not a repository is an ordinary outcome here, not a failure
+                // worth printing: it falls back to the walk below.
+                stdio: ["ignore", "pipe", "ignore"],
+            },
+        );
+    } catch {
+        // Not a git repository, or git is unavailable: fall back to a walk, so
+        // the check still runs somewhere a consumer has unpacked a tarball.
+        return walk(root, globs);
+    }
+    return listed
+        .split("\0")
+        .filter(Boolean)
+        .filter(
+            (file) =>
+                !ALWAYS_SKIP.some((skip) => file.startsWith(skip) || file.includes(`/${skip}`)),
+        );
+}
+
+/**
+ * Enumerate YAML files without git.
+ *
+ * @param {string} root - Directory to walk.
+ * @param {readonly string[]} globs - Path globs, matched on extension only.
+ * @returns {string[]} Repository-relative paths.
+ */
+function walk(root, globs) {
+    const extensions = new Set(globs.map((glob) => path.extname(glob)));
+    /** @type {string[]} */
+    const found = [];
+    /** @param {string} dir - Directory to descend. */
+    const descend = (dir) => {
+        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+            const full = path.join(dir, entry.name);
+            if (entry.isDirectory()) {
+                if (entry.name === "node_modules" || entry.name === "build") continue;
+                if (ALWAYS_SKIP.includes(`${entry.name}/`)) continue;
+                descend(full);
+            } else if (extensions.has(path.extname(entry.name))) {
+                found.push(path.relative(root, full));
+            }
+        }
+    };
+    descend(root);
+    return found;
+}
+
+/**
+ * Lint a repository's YAML against the shared rule set.
+ *
+ * ESLint is run through its Node API with `overrideConfigFile: true`, which
+ * stops it looking for an `eslint.config.js` at all. That is what lets this ship
+ * as a command rather than as a configuration a consumer has to adopt: a
+ * repository needs no ESLint of its own, and one that *has* an ESLint — as
+ * `Song-of-Heroic-Lands-FoundryVTT` does, for `src/` — keeps it untouched and
+ * unconsulted.
+ *
+ * @param {string} root - Repository to lint.
+ * @param {object} [opts]
+ * @param {readonly string[]} [opts.paths] - Globs to lint instead of every
+ *   YAML file git would consider.
+ * @param {object} [opts.plugin] - The `eslint-plugin-yml` module, for tests.
+ * @param {Function} [opts.ESLint] - The `ESLint` class, for tests.
+ * @returns {Promise<{findings: object[], checked: number}>} The findings, and
+ *   how many files were linted.
+ */
+export async function lintYaml(root, opts = {}) {
+    const directory = path.resolve(root);
+    const plugin = opts.plugin ?? (await import("eslint-plugin-yml")).default;
+    const ESLint = opts.ESLint ?? (await import("eslint")).ESLint;
+
+    const files = opts.paths?.length ? [...opts.paths] : candidateFiles(directory);
+    if (!files.length) return { findings: [], checked: 0 };
+
+    const eslint = new ESLint({
+        cwd: directory,
+        overrideConfigFile: true,
+        overrideConfig: yamlLintConfig(plugin),
+        errorOnUnmatchedPattern: false,
+    });
+
+    const results = await eslint.lintFiles(files);
+    /** @type {object[]} */
+    const findings = [];
+    for (const result of results) {
+        for (const message of result.messages)
+            findings.push(toDiagnostic(directory, result, message));
+    }
+    return { findings, checked: results.length };
+}
+
+/**
+ * One ESLint message as a diagnostic.
+ *
+ * A parse error carries no `ruleId` and reports column 0, which is not a
+ * position any compiler-parseable format admits — columns are 1-based. It is
+ * clamped rather than dropped, because the line is right and the line is what
+ * the author needs.
+ *
+ * @param {string} directory - The root `filePath` is resolved against.
+ * @param {object} result - An ESLint `LintResult`.
+ * @param {object} message - One of its messages.
+ * @returns {{file: string, line: number, column: number, severity: string,
+ *   message: string}} The diagnostic.
+ */
+function toDiagnostic(directory, result, message) {
+    const rule = message.ruleId ? `${message.ruleId} ` : "";
+    return {
+        file: path.resolve(directory, result.filePath),
+        line: message.line,
+        column: Math.max(1, message.column ?? 1),
+        severity: message.severity === 1 ? "warning" : "error",
+        message: `${rule}${message.message}`,
+    };
+}