@heroiclands/package-build 10.0.1 → 11.1.0

package/bin/content-build.mjs

@@ -72,6 +72,10 @@ import {
 import { renderItemFieldReference } from "../engine/field-reference.mjs";
 import { lintContentTree } from "../engine/content-lint.mjs";
 import { lintFrontmatter } from "../engine/frontmatter-lint.mjs";
+// The sections this repository declares — the open set a `README` landing's
+// `subType` names (#197). Read from the resolved configuration the site build
+// renders those landings from, so neither can name a section the other does not.
+import { declaredSections } from "../content-config.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
 import {
     checkDeclaredFields,
@@ -103,6 +107,8 @@ import {
     formatUnaddressableFinding as formatUnaddressable,
 } from "../engine/site-build.mjs";
 import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-links.mjs";
+// The one place a link finding is worded, shared with both builds (#184).
+import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
 import {
     emitDiagnostic,
     positionInFrontmatter,
@@ -189,6 +195,26 @@ function reportFailure(err) {
     else log.error(message);
 }
 
+/**
+ * A note's source text, or `""` when it cannot be read.
+ *
+ * Used only to turn a link finding into a position. A path that no longer
+ * resolves — a page a build generated, a tree walked from somewhere else —
+ * yields `""`, and {@link positionOfLiteral} then reports nothing, so the
+ * diagnostic drops the line and column rather than guessing them.
+ *
+ * @param {string|undefined} file - Absolute path to the note.
+ * @returns {string} The file's contents, or `""`.
+ */
+function readRawNote(file) {
+    if (!file) return "";
+    try {
+        return fs.readFileSync(file, "utf8");
+    } catch {
+        return "";
+    }
+}
+
 /**
  * The declaration sets this package ships, addressable by system id.
  *
@@ -714,6 +740,22 @@ function lintCommand() {
                     // decides which vocabulary a tree is held to.
                     vocabulary: NOTE_VOCABULARY,
                     references: argv.references,
+                    // How this repository addresses a section landing, and the
+                    // sections that can exist — the open vocabulary a
+                    // `README`'s `subType` is read against (#197, #200).
+                    // Passed in for the same reason the schemas are: the
+                    // linter checks a note against what it is handed.
+                    //
+                    // The types come from the **specification**, not from
+                    // `schemas`: a landing's `subType` is an address, and a
+                    // type the format declares is a section whether or not
+                    // this build carries a schema to check its notes' fields
+                    // with. Reading `schemas` here would refuse `Lore/README.md`
+                    // for a reason that is not about addresses, and report one
+                    // gap twice in two vocabularies.
+                    landing: config.publish.address.landing,
+                    types: [...loadContentFormat().types.keys()],
+                    sections: declaredSections(config),
                 });
 
                 // What the builders emit, against what the receiving system
@@ -1022,8 +1064,7 @@ function linksCommand() {
                 const {
                     deadAnchors,
                     deadAddresses,
-                    deadAliases,
-                    aliasCollisions,
+                    unlabelledLinks,
                     frontmatterLinks,
                     homepageLinks,
                     usedManifest,
@@ -1039,62 +1080,19 @@ function linksCommand() {
                             `heading in ${d.dest.rel} declares`,
                     });
                 }
-                // The pipe says the author meant an address (#131), so all
-                // three of these are errors — but they read differently
-                // because the corrections differ.
-                for (const d of deadAddresses) {
+                // Every link is an address (#180) and every address must
+                // resolve (#184), so all of these are errors — but they read
+                // differently because the corrections differ. The wording comes
+                // from the shared table, so the checker cannot describe a
+                // defect differently from the build that also refuses it.
+                for (const d of [...deadAddresses, ...unlabelledLinks]) {
                     emitDiagnostic({
                         file: d.note.file,
                         ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
                         severity: "error",
-                        message:
-                            d.reason === "not-an-address" ?
-                                `"${d.target}" is written as an address — the ` +
-                                `"|" says so — but it is not one; write ` +
-                                `[[type-shortcode|Text]], or drop the "|" to ` +
-                                `name it as an alias within this note's type`
-                            : d.reason === "unknown-type" ?
-                                `address [[${d.target}]] names no known ` + `content type`
-                            :   `dead address [[${d.target}]] — no document ` + `has that identity`,
-                    });
-                }
-                // An alias that names nothing may be a worldbuilding
-                // placeholder — a long-standing convention in the setting
-                // trees — so it is reported and does not fail the build. The
-                // ambiguous case is the collision below, reported at its
-                // claimants rather than here.
-                for (const d of deadAliases) {
-                    emitDiagnostic({
-                        file: d.note.file,
-                        ...positionOfLiteral(d.note.raw, d.text, d.occurrence),
-                        severity: "warning",
-                        message:
-                            d.ambiguous ?
-                                `alias [[${d.target}]] is claimed by ` +
-                                `${d.claimants.length} ${d.note.type} notes, ` +
-                                `so it names none of them; address the ` +
-                                `intended one as [[type-shortcode|Text]]`
-                            :   `unresolved alias [[${d.target}]] — no ` +
-                                `${d.note.type} note claims that name`,
+                        message: linkFindingMessage(d),
                     });
                 }
-                // Reported once per claimant, at the claimant, because the
-                // note that merely cites an ambiguous alias is innocent (#13).
-                for (const c of aliasCollisions) {
-                    const others = c.claimants.map((n) => n.rel).join(", ");
-                    for (const claimant of c.claimants) {
-                        emitDiagnostic({
-                            file: claimant.file,
-                            ...positionInFrontmatter(claimant.raw, "aliases", c.alias),
-                            severity: "error",
-                            message:
-                                `alias "${c.alias}" is claimed by ` +
-                                `${c.claimants.length} ${c.type} notes ` +
-                                `(${others}), so [[${c.alias}]] names none of ` +
-                                `them; rename all but one`,
-                        });
-                    }
-                }
                 for (const f of frontmatterLinks) {
                     emitDiagnostic({
                         file: f.note.file,
@@ -1119,12 +1117,10 @@ function linksCommand() {
                     });
                 }
 
-                // Warnings are reported and do not fail: a dead alias may be a
-                // note not yet written, which is the placeholder convention.
                 const failures =
                     deadAnchors.length +
                     deadAddresses.length +
-                    aliasCollisions.reduce((n, c) => n + c.claimants.length, 0) +
+                    unlabelledLinks.length +
                     frontmatterLinks.length +
                     homepageLinks.length;
                 if (failures) {
@@ -1132,21 +1128,14 @@ function linksCommand() {
                     process.exitCode = 1;
                 } else {
                     log.info(
-                        `${index.notes.length} notes: every anchor link lands ` +
-                            `and every address resolves ` +
-                            `(${usedManifest.size} cross-package reference(s) ` +
-                            `via manifest), no alias claimed twice, no ` +
+                        `${index.notes.length} notes: every link is a labelled ` +
+                            `address, every anchor link lands and every ` +
+                            `address resolves (${usedManifest.size} ` +
+                            `cross-package reference(s) via manifest), no ` +
                             `wikilink in frontmatter, every homepage address ` +
                             `resolvable.`,
                     );
                 }
-                if (deadAliases.length) {
-                    log.warn(
-                        `${deadAliases.length} unresolved alias(es) — a bare ` +
-                            `[[Name]] naming no note may be a placeholder, so ` +
-                            `these are reported rather than failed.`,
-                    );
-                }
             } catch (err) {
                 reportFailure(err);
                 process.exitCode = 1;
@@ -1275,16 +1264,13 @@ function siteCommand() {
                             `page verbatim, and reaches the reader as brackets`,
                     });
                 }
-                for (const f of gates.slugErrors) {
+                for (const f of gates.addressErrors) {
                     emitDiagnostic({
                         file: f.file,
                         severity: "error",
                         message: `cannot derive a URL: ${f.reason}`,
                     });
                 }
-                for (const c of gates.collisions) {
-                    log.error(`${c.url} claimed by ${c.sources.join(", ")}`);
-                }
                 for (const s of gates.staleManifests) {
                     emitDiagnostic({
                         file: path.join(loadPackConfig().paths.manifests, `${s.package}.json`),
@@ -1310,8 +1296,21 @@ function siteCommand() {
                 for (const e of result.tableErrors) {
                     log.error(`bad content table: ${e.reason}  (${e.source})`);
                 }
+                // Reported the way the pack build reports the very same
+                // finding: `file:line:column: error: message`, path first, and
+                // the message from the shared table (#184). It used to be a
+                // `log.error` whose timestamp prefix sat where a parser reads
+                // the path from, and whose text named a `reason` code rather
+                // than saying what to do — so one authored link produced a
+                // machine-readable diagnostic from one build and prose from
+                // another.
                 for (const e of result.wikiErrors) {
-                    log.error(`bad wikilink [[${e.target}]]: ${e.reason}  (${e.file})`);
+                    emitDiagnostic({
+                        file: e.file,
+                        ...positionOfLiteral(readRawNote(e.file), e.link, e.occurrence),
+                        severity: "error",
+                        message: linkFindingMessage(e),
+                    });
                 }
                 if (result.tableErrors.length || result.wikiErrors.length) {
                     process.exitCode = 1;
@@ -1319,11 +1318,16 @@ function siteCommand() {
                 }
 
                 if (result.manifests && !result.manifests.complete) {
+                    // Not a softening any more (#184): an address into one of
+                    // these packages fails like any other that resolves
+                    // nowhere. The warning names them so an author meeting that
+                    // failure knows the fix may be to vendor a manifest rather
+                    // than to correct a shortcode.
                     log.warn(
-                        `cross-package address checking is OFF — no manifest ` +
-                            `for ${result.manifests.missing.join(", ")}. ` +
-                            `Unresolved addresses are tolerated until every ` +
-                            `package publishes one.`,
+                        `no link manifest vendored for ` +
+                            `${result.manifests.missing.join(", ")} — an ` +
+                            `address into one of those packages resolves ` +
+                            `nowhere and fails the build.`,
                     );
                 }
 

package/content-config.mjs

@@ -210,6 +210,34 @@ export function publishesContentPages(config) {
     return config.publish.site === "content";
 }
 
+/**
+ * Every URL section this repository names, in declaration order (#197).
+ *
+ * A section is *declared* by describing it: `site.sections` for one whose
+ * landing this build generates, `site.readmeSections` for one whose landing is
+ * a `README`. Between them they are the open set of addresses a repository
+ * says it publishes under — which is what a `README` landing's `subType` names,
+ * since `sectionOf` reads that field as the section rather than as a genre.
+ *
+ * Read from the same two maps the site build renders each landing from, so the
+ * set a note is checked against and the set a landing is written from cannot
+ * come to disagree. A repository that describes no section declares none, and
+ * the answer is empty rather than a guess assembled from the tree.
+ *
+ * @param {{site: {sections: object, readmeSections: object}}} config - A
+ *   resolved configuration.
+ * @returns {readonly string[]} The section names, deduplicated.
+ */
+export function declaredSections(config) {
+    const site = config?.site ?? {};
+    return Object.freeze([
+        ...new Set([
+            ...Object.keys(site.sections ?? {}),
+            ...Object.keys(site.readmeSections ?? {}),
+        ]),
+    ]);
+}
+
 /**
  * @typedef {"systems" | "modules"} PackageKind
  */

package/docs/content-format.md

@@ -74,8 +74,8 @@ silently become a theme parameter, which is exactly why these cannot live
 together.
 
 **Tags are open, except the ones that classify.** `tags:` shares the top level's
-openness: a tag naming a theme, a region or a working state — `underworld`,
-`byzaria`, `draft` — is the author's own and this build has no opinion about it.
+openness: a tag naming a theme or a region — `underworld`,
+`byzaria`, `riverlands` — is the author's own and this build has no opinion about it.
 A tag that classifies the subject is different, because something queries it. A
 settlement tagged `village` appears in the list of villages and an untagged one
 does not, so `vilage` does not merely look wrong: it removes the note from an
@@ -91,6 +91,17 @@ is declared, so a near miss is a finding that names what you probably meant.
 | **being station**   | `being`                | `tradesfolk`, `common-folk`, `soldiery`, `administration`, `clergy`, `mages`, `underworld`, `dependents`, `guilded`, `unguilded`                                                                                                                                                                                     |
 | **state**           | any                    | `draft`                                                                                                                                                                                                                                                                                                              |
 
+**`draft` is the one tag either build reads.** A note tagged `draft` exists so a
+link into it is not dead, and a link into it renders marked — as
+`<span class="sohl-draft-link" title="Draft — not yet written">…</span>` in a
+compiled journal and on the website alike, with the appearance supplied by the
+consuming system's stylesheet or the site theme. **Nothing else changes**: the
+note compiles, validates, publishes and resolves exactly as any other, and it
+stays in the packs, in the link manifest and on the site. That is what separates
+the tag from the retired `draft:` field, whose whole effect was to move a note
+from published to unresolvable without saying so — and which is refused, by name,
+if you write it.
+
 **The group's scope is what makes the check work.** A group names the types it
 applies to, and a place's kinds are only ever checked on a place. Without that
 the rule is wrong on every note it touches: `azravan` on a faith, `barter` on an
@@ -235,49 +246,78 @@ resolution with nothing to say so.
 `type/shortcode` with a slash is the legacy form, still resolved so links written
 before the vault migrated do not silently die. A slash is _unconditionally_ an
 address separator — pipe or no pipe — so an unknown type before one is an error
-rather than a fallback to the alias index.
+rather than something to guess at.
 
-#### The pipe decides how a target resolves
+#### Every link is an address, and every link carries a label
 
-There are two namespaces, and the pipe says which one to consult:
+There is one namespace, and the pipe is required:
 
 | written              | resolved as | displays                   |
 | -------------------- | ----------- | -------------------------- |
-| `[[Alias]]`          | an alias    | the alias, as written      |
 | `[[WikiLink\|]]`     | an address  | the target note's own name |
 | `[[WikiLink\|Text]]` | an address  | `Text`                     |
-
-**No pipe means look this up in the alias index. A pipe means parse this as an
-address.** The two never compete, and neither falls back to the other: a failure
-in one namespace is a dead link, not an invitation to try the other.
-
-That is what makes positional parsing safe. Note names contain hyphens —
-`Grukar-ahk` is a name, not a `Grukar` of type `ahk` — and under a
-resolve-by-shape rule the reader would have to consult the type vocabulary before
-it dared split. Under the pipe rule it never faces the question: an unpiped
-target is taken whole, hyphens and all, and only a piped target is ever split.
-
-The empty label is not an oversight and not a way of writing no label. It says
-_address this target, and show whatever it calls itself_ — so a note renamed later
-takes its new name at every citation with no link edited. Omitting the pipe says
-something else entirely: the phrase in the brackets is the alias, and the alias is
-also what the reader sees.
-
-So the two are worth keeping distinct even though both display a name: one is a
-promise to follow the target, the other is a phrase the author chose.
-
-#### An alias resolves only within its own type
-
-A bare `[[awareness]]` in a `skill` note finds the `skill` whose alias is
-`awareness` — not an `affliction` that happens to share the name. The alias index
-is keyed by `(source note's type, alias)`, so the same word may be an alias in
-several types without colliding.
-
-Two notes of the **same** type claiming one alias is an error, and the report
-names the claimants rather than the note that merely cited them. An ambiguous
-alias never resolves to whichever was indexed first.
-
-#### In frontmatter, a link is a bare address — never an alias
+| `[[Name]]`           | nothing     | a finding                  |
+
+**A link written without a label addresses nothing** (#180), and the correction
+is always the same: write `[[type-shortcode|Text]]`.
+
+The bare form used to name an **alias** — a note's own display name, or one of
+the names it listed in `aliases:` — looked up within the citing note's type. It
+was measured before it was retired, and the namespace was empty in practice:
+across 8,305 wikilinks in three content trees, **not one** bare link resolved to
+a note. What the index behind it did do was fold every note's `name.full` into
+itself, so two notes of one type could not share a display name — a rules page
+and a user-guide page both called "Gear" were a build failure whose every
+available fix moved a published URL (#179).
+
+The top-level `aliases:` that fed it is **retired** and refused. The nested
+`name.aliases:` is **not**: it is reserved for a use that does not exist yet, so
+it is permitted and read by nothing — no index, no resolver, no lint rule, no
+derived address. A note carrying one behaves exactly as one without it.
+
+Requiring the label is also what makes positional parsing safe. Note names
+contain hyphens — `Grukar-ahk` is a name, not a `Grukar` of type `ahk` — so a
+target that does not parse as an address is reported as one that does not, rather
+than split at an arbitrary place or quietly looked up somewhere else.
+
+The **empty** label is not a way of writing no label. It says _address this
+target, and show whatever it calls itself_ — so a note renamed later takes its new
+name at every citation with no link edited. `[[x|]]` is labelled; `[[x]]` is not.
+
+The link part may still be an anchor: `[[#slug|Text]]` addresses a section of the
+page it is written on. It is the label that is required, not a target.
+
+#### Every address resolves, and every build says so the same way
+
+An address that names no note **fails the build** (#184) — in the link checker,
+in the pack compilers and in the site build alike.
+
+It was a warning in the checker and, in the site build, nothing at all while any
+linkable package had no vendored manifest. The reasoning was that `[[Sunless
+Vault]]` might be a placeholder for a note somebody meant to write. That was a
+property of the **bare** form, which is retired, and the intent behind it has a
+real spelling now: a note tagged `draft` exists, resolves, compiles and
+publishes, and a link to it renders visibly marked (#183). So an address landing
+nowhere is a typo or an omission, and both want fixing.
+
+There are six ways a link can fail, and each is one **error** with one message
+wherever it is met:
+
+| finding          | what it means                                  | the fix                                   |
+| ---------------- | ---------------------------------------------- | ----------------------------------------- |
+| `unlabelled`     | no `\|`, so the link addresses nothing         | write `[[type-shortcode\|Text]]`          |
+| `not-an-address` | labelled, but the target is not an address     | write the address, not the name           |
+| `unknown-type`   | qualified, but names no type this build knows  | correct the type segment                  |
+| `unresolved`     | parses as an address; nothing publishes it     | fix the shortcode, or vendor the manifest |
+| `ambiguous`      | more than one package publishes the short form | write `[[package-type-shortcode\|Text]]`  |
+| `unknown-anchor` | the address resolves; the `#section` does not  | correct the anchor                        |
+
+The vocabulary and the messages live in one module (`engine/wikilink-syntax.mjs`)
+precisely because an author meets whichever build ran first. Three resolvers read
+one authored link; they must not describe the same mistake in three ways, and
+they must never disagree about whether it is a mistake at all.
+
+#### In frontmatter, a link is a bare address
 
 A `WikiLink` **field** takes the address with no brackets:
 
@@ -292,17 +332,10 @@ not `[[hexhodai]]`. The field is declared as a `WikiLink`, so the schema already
 knows the value is an address and reads it as one; brackets would be punctuation
 the reader has to strip before it can do anything.
 
-**Aliases are not permitted here.** A frontmatter value is always parsed by the
-address grammar above, so a single-segment value such as `hexhodai` is a
-_shortcode_, not an alias — the same spelling means different things in a
-frontmatter field and in body prose, and this is the rule that says which.
-
-The reason is that frontmatter is structure rather than prose. An alias is an
-authorial convenience for writing a sentence that reads well; a field value is a
-reference something else will compile against, and it should say exactly what it
-points at. There is also nowhere to put the pipe: the distinction body text draws
-with punctuation has no equivalent in a YAML scalar, so the region as a whole
-picks one namespace and keeps it.
+A frontmatter value is parsed by the address grammar above, so a single-segment
+value such as `hexhodai` is a _shortcode_. Frontmatter is structure rather than
+prose: a field value is a reference something else will compile against, and it
+should say exactly what it points at.
 
 **The field supplies the type.** Every `WikiLink` field declares the note type it
 targets — `seat` a `place`, `parents` an `affiliation`, `stations` a `lore` — so
@@ -339,15 +372,10 @@ So the ladder has one rung where the field helps and three where it only checks:
 a bare shortcode takes its type from the declaration, and every longer form
 states the type itself and is verified against it.
 
-This also settles the alias question on its own. Aliases resolve within the
-_source_ note's type, and a field almost always points at a different type — a
-being's `stations` are `lore` notes — so an alias in a field would be looked up
-in the wrong namespace even where one existed to find.
-
 This is enforced rather than merely preferred: the build walks every frontmatter
-value, reports each bracketed link it finds, each value that resolves only as an
-alias, and each value whose qualification contradicts its field. A successful run says so — _no wikilink in frontmatter_ is part
-of what `content-build links` reports when it passes.
+value, reports each bracketed link it finds, and reports each value whose
+qualification contradicts its field. A successful run says so — _no wikilink in
+frontmatter_ is part of what `content-build links` reports when it passes.
 
 Brackets belong in prose, where a link sits inside a sentence and needs marking
 off from the words around it. A frontmatter value has nothing to be marked off
@@ -355,21 +383,16 @@ from.
 
 #### Not yet implemented
 
-Two rules in this section are settled but unbuilt, and describe the target rather
+One rule in this section is settled but unbuilt, and describes the target rather
 than current behaviour:
 
 - **The `<system>` segment.** `readQualifier` reads package, type and shortcode;
   there is no system segment. A four-segment target today parses as
   `package-type-shortcode` with a hyphenated shortcode, or fails.
-- **The pipe rule.** Today the pipe affects only the _label_: resolution runs the
-  same either way, trying the address first and falling back to the alias — so a
-  target is read by shape rather than by punctuation, and an author cannot say
-  which of the two they meant.
-
-The corpus is close to the rule already. Of 12,056 links, 10,413 are
-`[[type-shortcode|Label]]`, which is correct as written. Two authored links use
-an unpiped multi-segment target, and 69 use a pipe with a note name where an
-address belongs; those are the migration.
+  The corpus is close to the rule already. Of 12,056 links, 10,413 are
+  `[[type-shortcode|Label]]`, which is correct as written. Two authored links use
+  an unpiped multi-segment target, and 69 use a pipe with a note name where an
+  address belongs; those are the migration.
 
 ### What a note produces
 

package/engine/base-compiler.mjs

@@ -77,7 +77,7 @@ import {
 } from "./helpers.mjs";
 import { emitDiagnostic } from "./diagnostics.mjs";
 import { assertNoDeclaredPackage } from "./note-package.mjs";
-import { assertNoDraftField } from "./retired-fields.mjs";
+import { assertNoAliasesField, assertNoDraftField } from "./retired-fields.mjs";
 import { assertTypeNotRetired, packForType } from "./ids.mjs";
 import { carriesSystemBlock } from "./system-block.mjs";
 import { checkAuthoredSystemData, checkEmittedSystemData } from "./schema-check.mjs";
@@ -770,6 +770,11 @@ export class BasePackCompiler {
             // - `draft:` (#69): it excluded the note from the packs, the
             //   manifest and the site, and no checker reported the links that
             //   left dangling.
+            // - `aliases:` (#180): it fed the alias index, which the bare
+            //   `[[Alias]]` form was looked up in; the form is retired, so the
+            //   list has no reader left. The nested `name.aliases` is a
+            //   different field and is **not** refused — it is reserved, and
+            //   deliberately neither read nor validated.
             //
             // Both are reported and counted — never skipped, which is how a
             // tree naming a package nothing answers to used to compile zero
@@ -778,6 +783,7 @@ export class BasePackCompiler {
             try {
                 assertNoDeclaredPackage(fm, { absPath });
                 assertNoDraftField(fm, { absPath });
+                assertNoAliasesField(fm, { absPath });
             } catch (err) {
                 stats.declined++;
                 this.errorCount++;