@heroiclands/package-build 10.0.0 → 11.0.0

package/engine/note-vocabulary.mjs

@@ -206,6 +206,21 @@ const CHARGES = Object.freeze([
  * fishing village is a `village` that is `fishing`, and the single-valued field
  * this replaced had to spell it `Fishing Village` as a value of its own.
  */
+/**
+ * The declared tag that marks a note as **unfinished** (#183).
+ *
+ * Named once and referenced from the declaration below, because a second
+ * spelling is how the two come apart: rename the tag in `DECLARED_TAGS` and a
+ * private copy elsewhere keeps matching the old word, silently.
+ *
+ * It is a **presentation** fact and nothing more. A draft note compiles,
+ * validates, publishes and resolves like any other; only a link *into* it
+ * renders marked. What it emphatically is not is the retired `draft:` field,
+ * whose entire effect was to move a note from published to unresolvable — see
+ * {@link draftRetiredMessage}.
+ */
+export const DRAFT_TAG = "draft";
+
 export const DECLARED_TAGS = Object.freeze({
     /** What a place *is*. */
     placeKind: Object.freeze({
@@ -287,7 +302,7 @@ export const DECLARED_TAGS = Object.freeze({
         ]),
     }),
     /** A note's working state, which any note may carry. */
-    state: Object.freeze({ types: null, tags: Object.freeze(["draft"]) }),
+    state: Object.freeze({ types: null, tags: Object.freeze([DRAFT_TAG]) }),
 });
 
 /**
@@ -302,6 +317,48 @@ export function declaredTags(type, groups = DECLARED_TAGS) {
     return Object.freeze(applies.flatMap((g) => g.tags));
 }
 
+/**
+ * Whether a note carries a given tag, however the author wrote it.
+ *
+ * `tags:` is authored by hand and Obsidian is permissive about it: a single tag
+ * may be a scalar rather than a list, a value may carry the leading `#` it is
+ * written with in prose, and case and surrounding space are not significant.
+ * The spelling of the tag *itself* still is — a near miss is a near miss, and
+ * the frontmatter lint is what reports it; nothing here guesses.
+ *
+ * Reads `tags` and, as Dataview does, `tag` — the singular spelling Obsidian
+ * also accepts.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @param {string} tag - The tag to look for, in its declared spelling.
+ * @returns {boolean} Whether the note carries it.
+ */
+export function hasTag(fm, tag) {
+    const raw = fm?.tags ?? fm?.tag;
+    if (raw == null) return false;
+    const wanted = String(tag).toLowerCase();
+    for (const entry of Array.isArray(raw) ? raw : [raw]) {
+        if (typeof entry !== "string") continue;
+        if (entry.trim().replace(/^#/, "").toLowerCase() === wanted) return true;
+    }
+    return false;
+}
+
+/**
+ * Whether a note is tagged as an unfinished **draft** (#183).
+ *
+ * The one reader of {@link DRAFT_TAG}, so both builds ask the same question of
+ * the same field. Presentation only: a draft note is in the packs, in the
+ * manifest and on the site exactly as any other, and this decides nothing but
+ * whether a link into it renders marked.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the note carries the `draft` tag.
+ */
+export function isDraftNote(fm) {
+    return hasTag(fm, DRAFT_TAG);
+}
+
 export const NOTE_VOCABULARY = Object.freeze({
     /* ----- actors --------------------------------------------------- */
 

package/engine/retired-fields.mjs

@@ -22,8 +22,9 @@
  * says what to write instead rather than which value to correct.
  *
  * `package:` is retired the same way and is refused from `note-package.mjs`,
- * where the concept it belonged to still lives. `draft:` has no such home —
- * there is no surviving concept it was part of — so it is refused here.
+ * where the concept it belonged to still lives. `draft:` and the top-level
+ * `aliases:` have no such home — there is no surviving concept either was part
+ * of — so they are refused here.
  *
  * **What `draft:` did (#69).** It excluded a note from the compiled packs, from
  * the link manifest and from a consuming site build. Nothing reported the
@@ -34,6 +35,20 @@
  * *unresolvable*, silently — and it also suppressed real build failures, since
  * a note the compilers never reached could not fail on the defects it carried.
  *
+ * **What `aliases:` did (#180).** It fed the alias index, which is what a bare
+ * `[[Alias]]` was looked up in. That form resolved to nothing anywhere in the
+ * corpus, while the collision rule guarding it folded in every note's
+ * `name.full` and so decided what a note could be named (#179). The form and
+ * the index are retired together, leaving the field with no reader at all.
+ *
+ * **`name.aliases` fed the same index and is nonetheless kept.** It is
+ * **reserved** — held for a use that does not exist yet — so it is the one
+ * field here that is neither retired nor read. Nothing consults it: no index,
+ * no resolver, no lint rule, no emitter. A note carrying one compiles,
+ * resolves and emits exactly as if it were absent, and `tests/name-aliases-
+ * reserved.test.ts` pins that equivalence so a future reader cannot be added
+ * by accident.
+ *
  * **A field retired in favour of another is a third case (#142).** `draft:` and
  * `package:` were retired outright: nothing replaced them, so no value made
  * writing one right and refusal was the only honest answer. A *renamed* field
@@ -73,8 +88,9 @@ export function draftRetiredMessage(file) {
         ". It excluded the note from the compiled packs, the link manifest " +
         "and the site, and no checker reported the exclusion, so every " +
         "wikilink into it read as a link to a note that does not exist. To " +
-        "mark a note as unfinished, tag it `#draft` instead: the build " +
-        "ignores tags, and a `FROM #draft` query still finds it"
+        "mark a note as unfinished, tag it `#draft` instead: the note still " +
+        "compiles and publishes, a link into it renders marked, and a " +
+        "`FROM #draft` query still finds it"
     );
 }
 
@@ -109,6 +125,97 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
     throw err;
 }
 
+/**
+ * What a note declaring a top-level `aliases:` is told, in one place.
+ *
+ * Shared by the compile-time refusal and the frontmatter lint, because an
+ * author meets whichever of the two runs first and they should read the same.
+ * It says what the field fed and what to write instead, rather than which value
+ * to correct: no value makes declaring it right.
+ *
+ * **What it did (#180).** It was the authored half of the alias index — the
+ * namespace a bare `[[Alias]]` was looked up in. Across the three content trees
+ * not one bare link resolved through it, while the collision rule that kept it
+ * unambiguous folded in every note's `name.full` and so dictated what a note
+ * could be named (#179). The form is retired, so the list has no reader.
+ *
+ * **`name.aliases` is a different field and is not retired.** It fed the same
+ * index, but unlike the top-level list it is being kept — reserved, unread,
+ * and deliberately unmentioned by this message, which would otherwise tell an
+ * author to delete a field they are allowed to write. See
+ * {@link assertNoAliasesField}.
+ *
+ * @param {string} [file] - The note's path, named in the message. Omit it where
+ *   the caller emits through a diagnostic, whose locator already starts the
+ *   line — repeating it prints the path twice.
+ * @returns {string} The message, unpunctuated at the end as a finding is.
+ */
+export function aliasesRetiredMessage(file) {
+    return (
+        "`aliases:` is a retired frontmatter field — delete it" +
+        (file ? ` — ${file}` : "") +
+        ". It listed names the bare `[[Alias]]` form could cite, and that " +
+        "form is retired: every wikilink is now an address, written " +
+        "`[[type-shortcode|Text]]`. Nothing else ever read the list"
+    );
+}
+
+/**
+ * Refuse a note that declares a top-level `aliases:`.
+ *
+ * Presence is the whole test. `aliases: []` is as retired as a populated one —
+ * it reads as "this note claims no other names", a statement about a namespace
+ * that no longer exists.
+ *
+ * **The nested `name.aliases` is deliberately not refused.** Both spellings fed
+ * the retired alias index, and both lost their reader with it, but only the
+ * top-level one is retired: `name.aliases` is **reserved**, held for a use that
+ * does not exist yet. So it is neither refused nor read — no index consults it,
+ * no rule validates its contents, nothing derives from it, and nothing emits
+ * it. It rides in the note as inert data, and a note carrying one compiles,
+ * resolves and emits exactly as if it were absent.
+ *
+ * That distinction is the reason this checks `Object.hasOwn(fm, "aliases")`
+ * rather than resolving a dotted key: the top-level field is the whole subject,
+ * and reaching into `name` at all is the thing being avoided.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter, or nothing when it
+ *   could not be parsed.
+ * @param {object} [options] - Options.
+ * @param {string} [options.file] - The note's path, named in the message. Omit
+ *   it where the caller emits through a diagnostic, which puts the locator at
+ *   the start of the line already — repeating it prints the path twice.
+ * @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.
+ * @returns {void}
+ * @throws {Error} When the note declares a top-level `aliases`.
+ */
+export function assertNoAliasesField(fm, { file, absPath } = {}) {
+    if (!declaresRetiredAliasesField(fm)) return;
+
+    const err = new Error(`${aliasesRetiredMessage(file)}.`);
+    // Anchored at column 1: a permitted `name.aliases` writes the same key,
+    // indented, and a finding about the retired top-level field must never
+    // open on it.
+    const position = locateFrontmatterKey(absPath, "aliases", undefined, { topLevel: true });
+    if (position) err.position = position;
+    throw err;
+}
+
+/**
+ * Whether a note declares the retired top-level `aliases:`.
+ *
+ * A nested `name.aliases` is **not** this field and never answers true here —
+ * see {@link assertNoAliasesField} for why the two part company.
+ *
+ * @param {object|null|undefined} fm - Parsed frontmatter.
+ * @returns {boolean} Whether the retired field is declared.
+ */
+export function declaresRetiredAliasesField(fm) {
+    return Boolean(fm) && typeof fm === "object" && Object.hasOwn(fm, "aliases");
+}
+
 /**
  * A frontmatter key's position in a note's file, or nothing.
  *
@@ -121,11 +228,15 @@ export function assertNoDraftField(fm, { file, absPath } = {}) {
  * @param {string} [value] - When given, prefer the occurrence whose line also
  *   carries this text — so a finding about one entry of a block opens on that
  *   entry rather than on the key that introduces it.
+ * @param {object} [options] - Options, forwarded to
+ *   {@link positionInFrontmatter}.
+ * @param {boolean} [options.topLevel=false] - Require the key at column 1, so
+ *   an identically named nested key cannot answer for it.
  * @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, key, value = undefined) {
+export function locateFrontmatterKey(absPath, key, value = undefined, { topLevel = false } = {}) {
     if (!absPath) return undefined;
     let raw;
     try {
@@ -133,7 +244,7 @@ export function locateFrontmatterKey(absPath, key, value = undefined) {
     } catch {
         return undefined;
     }
-    const at = positionInFrontmatter(raw, key, value);
+    const at = positionInFrontmatter(raw, key, value, { topLevel });
     return at.line === undefined ? undefined : at;
 }