@heroiclands/package-build 8.1.0 → 10.0.0

package/engine/schema-extract.mjs

@@ -150,10 +150,7 @@ export function registryOf(src, name) {
             }
             if (ts.isObjectLiteralExpression(init)) {
                 for (const p of init.properties) {
-                    if (
-                        ts.isPropertyAssignment(p) &&
-                        ts.isIdentifier(p.initializer)
-                    ) {
+                    if (ts.isPropertyAssignment(p) && ts.isIdentifier(p.initializer)) {
                         out.set(propName(p.name), p.initializer.text);
                     }
                 }
@@ -216,10 +213,7 @@ function resolveSpecifier(fromDir, spec, aliases) {
     }
     if (!base) return null;
     for (const ext of EXTENSIONS) {
-        for (const candidate of [
-            `${base}${ext}`,
-            path.join(base, `index${ext}`),
-        ]) {
+        for (const candidate of [`${base}${ext}`, path.join(base, `index${ext}`)]) {
             if (fs.existsSync(candidate)) return candidate;
         }
     }
@@ -243,11 +237,7 @@ function importSourceOf(src, name, aliases) {
         if (!bindings.elements.some((e) => e.name.text === name)) return;
         const spec = node.moduleSpecifier;
         if (!ts.isStringLiteral(spec)) return;
-        found = resolveSpecifier(
-            path.dirname(src.fileName),
-            spec.text,
-            aliases,
-        );
+        found = resolveSpecifier(path.dirname(src.fileName), spec.text, aliases);
     });
     return found;
 }
@@ -286,9 +276,7 @@ function locateClass(fromFile, className, aliases, cache) {
     if (!imported) return null;
     const importedSrc = parse(imported, cache);
     const importedDecl = classDeclIn(importedSrc, className);
-    return importedDecl ?
-            { file: imported, src: importedSrc, decl: importedDecl }
-        :   null;
+    return importedDecl ? { file: imported, src: importedSrc, decl: importedDecl } : null;
 }
 
 /**
@@ -303,8 +291,7 @@ function superClassOf(decl) {
     for (const clause of decl.heritageClauses ?? []) {
         if (clause.token !== ts.SyntaxKind.ExtendsKeyword) continue;
         const [type] = clause.types;
-        if (type && ts.isIdentifier(type.expression))
-            return type.expression.text;
+        if (type && ts.isIdentifier(type.expression)) return type.expression.text;
     }
     return null;
 }
@@ -350,9 +337,8 @@ function literalReturnedBy(src, fnName) {
         if (isTarget) {
             const body =
                 ts.isFunctionDeclaration(node) ? node.body
-                : node.initializer && ts.isArrowFunction(node.initializer) ?
-                    node.initializer.body
-                :   null;
+                : node.initializer && ts.isArrowFunction(node.initializer) ? node.initializer.body
+                : null;
             if (body) literal = returnedLiteral(body);
         }
         ts.forEachChild(node, visit);
@@ -404,14 +390,10 @@ function isObjectAssign(expr) {
  */
 function schemaContributions(src, decl) {
     const method = decl.members.find(
-        (m) =>
-            ts.isMethodDeclaration(m) &&
-            propName(m.name) === "defineSchema" &&
-            m.body,
+        (m) => ts.isMethodDeclaration(m) && propName(m.name) === "defineSchema" && m.body,
     );
     // No `defineSchema()` — the whole schema is the parent's.
-    if (!method)
-        return { literals: [], edges: [{ kind: "super", name: null }] };
+    if (!method) return { literals: [], edges: [{ kind: "super", name: null }] };
 
     const direct = returnedLiteral(method.body);
     if (direct) return { literals: [direct], edges: [] };
@@ -568,12 +550,7 @@ export function fieldsForClass({ file, className, aliases, cache, rootDir }) {
             const importedSrc = parse(from, cache);
             const importedLit = literalReturnedBy(importedSrc, edge.name);
             if (importedLit) {
-                walkLiteral(
-                    { file: from, src: importedSrc },
-                    importedLit,
-                    inherited,
-                    superName,
-                );
+                walkLiteral({ file: from, src: importedSrc }, importedLit, inherited, superName);
             }
             return;
         }
@@ -616,12 +593,7 @@ export function fieldsForClass({ file, className, aliases, cache, rootDir }) {
  * @param {string} opts.version - The package version.
  * @returns {object} The artifact `schema-check.mjs` reads.
  */
-export function buildSchemaArtifact({
-    rootDir,
-    registries,
-    packageId,
-    version,
-}) {
+export function buildSchemaArtifact({ rootDir, registries, packageId, version }) {
     const aliases = pathAliases(rootDir);
     const cache = new Map();
     const documents = {};

package/engine/site-build.mjs

@@ -56,10 +56,7 @@ import { expandContentTables } from "./content-tables.mjs";
 import { buildSiteIndex, wikiContext } from "./site-index.mjs";
 import { frontmatterWikilinks, resolveWebWikilinks } from "./web-wikilinks.mjs";
 import { loadForeignManifests, manifestsComplete } from "./kb-manifest.mjs";
-import {
-    formatUnaddressableFinding,
-    unaddressableForeignPackages,
-} from "./foreign-manifests.mjs";
+import { formatUnaddressableFinding, unaddressableForeignPackages } from "./foreign-manifests.mjs";
 import { deriveBeingInfo, isBeing } from "../sohl/being-info.mjs";
 import { loadPackConfig } from "./pack-config.mjs";
 import { searchableFrontmatter } from "./note-package.mjs";
@@ -192,10 +189,7 @@ export function collectContentPages(contentBase, ctx) {
             // authoring folder, for grouped landings.
             folder: path.basename(path.dirname(file)),
             sec,
-            url:
-                isReadme ?
-                    `${ctx.mount}${sec}/`
-                :   `${ctx.mount}${sec}/${slug}/`,
+            url: isReadme ? `${ctx.mount}${sec}/` : `${ctx.mount}${sec}/${slug}/`,
             isReadme,
         });
     }
@@ -229,12 +223,10 @@ export function collectTreePages(tree, ctx) {
         const rel = path.relative(tree.from, file).replace(/\\/g, "/");
         const base = path.basename(rel);
         const isReadme = base.toLowerCase() === "readme.md";
-        const sec = fm.category ?? tree.section;
+        const sec = fm.subType ?? tree.section;
         const h1 = /^#\s+(.+?)\s*$/m.exec(body);
-        const h1Title =
-            h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
-        const name =
-            fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");
+        const h1Title = h1 ? h1[1].replace(/\{@link\s+[^}]*\}/g, "").trim() : null;
+        const name = fm.name?.full ?? fm.title ?? h1Title ?? path.basename(base, ".md");
         const slug = fm.slug ?? slugify(path.basename(base, ".md"));
         const relNoExt = rel.slice(0, -3).toLowerCase();
         const dir = path.posix.dirname(relNoExt);
@@ -562,9 +554,7 @@ export function pageDestination(page) {
             :   path.join(page.sec, `${page.slug}.md`);
     }
     const rel =
-        page.isReadme ?
-            path.posix.join(path.posix.dirname(page.rel), "_index.md")
-        :   page.rel;
+        page.isReadme ? path.posix.join(path.posix.dirname(page.rel), "_index.md") : page.rel;
     return path.join(page.sec, rel);
 }
 
@@ -640,10 +630,7 @@ export function renderPages(pages, options) {
         const data = pageFrontmatter(page, { readmeSections, decorate });
         const dest = path.join(outRoot, pageDestination(page));
         fs.mkdirSync(path.dirname(dest), { recursive: true });
-        fs.writeFileSync(
-            dest,
-            matter.stringify(protectCode(body, resolve), data),
-        );
+        fs.writeFileSync(dest, matter.stringify(protectCode(body, resolve), data));
         byKind[page.kind] = (byKind[page.kind] ?? 0) + 1;
     }
 
@@ -676,10 +663,7 @@ export function renderPages(pages, options) {
  * @param {object} options - `{ sections, landing, sectionTitle }`.
  * @returns {number} How many landings were written.
  */
-export function writeSectionLandings(
-    outRoot,
-    { sections = {}, landing, sectionTitle },
-) {
+export function writeSectionLandings(outRoot, { sections = {}, landing, sectionTitle }) {
     let written = 0;
 
     // The mount's own landing carries a `type` of its own. Hugo's template
@@ -689,10 +673,7 @@ export function writeSectionLandings(
     // template out of the path where it could be inherited.
     if (landing) {
         fs.mkdirSync(outRoot, { recursive: true });
-        fs.writeFileSync(
-            path.join(outRoot, "_index.md"),
-            matter.stringify("", landing),
-        );
+        fs.writeFileSync(path.join(outRoot, "_index.md"), matter.stringify("", landing));
         written += 1;
     }
 
@@ -713,10 +694,7 @@ export function writeSectionLandings(
         if (!entry.isDirectory()) continue;
         const index = path.join(outRoot, entry.name, "_index.md");
         if (fs.existsSync(index)) continue;
-        fs.writeFileSync(
-            index,
-            matter.stringify("", { title: sectionTitle(entry.name) }),
-        );
+        fs.writeFileSync(index, matter.stringify("", { title: sectionTitle(entry.name) }));
         written += 1;
     }
     return written;
@@ -859,19 +837,16 @@ export function buildSite({ config, outRoot } = {}) {
     const outBase = resolveOutputRoot(resolved.rootDir, site.out);
     const out =
         outRoot ? path.resolve(outRoot)
-        : publishesContent ?
-            path.join(outBase, scheme.prefix.replace(/\/$/, ""))
+        : publishesContent ? path.join(outBase, scheme.prefix.replace(/\/$/, ""))
             // Homepage-only has no content mount, so the package's root *is*
             // the output root and `--out` redirects the whole of it.
-        :   outBase;
+        : outBase;
     // The homepage publishes at `/<contentPackage>/`, which is the package's
     // own root — one level above the content mount, and the same directory in
     // homepage-only mode.
     const homeRoot = publishesContent ? outBase : out;
 
-    const packages = new Set(
-        site.packages.length ? site.packages : [resolved.contentPackage],
-    );
+    const packages = new Set(site.packages.length ? site.packages : [resolved.contentPackage]);
 
     const ctx = {
         packages,

package/engine/site-index.mjs

@@ -54,6 +54,9 @@ import path from "node:path";
 import { canonicalKey, readCanonicalKey } from "./kb-manifest.mjs";
 import { hasDocEntry } from "./item-docs.mjs";
 import { contentPackage } from "./content-package.mjs";
+// The alias namespace: what a page may be called, and what happens when two
+// pages of one type claim one name (#131).
+import { aliasesOf, indexAliases } from "./alias-index.mjs";
 
 /**
  * One page the site will publish, as the index needs to see it.
@@ -152,10 +155,7 @@ function mergeForeign(index, foreignIndex) {
         const parts = readCanonicalKey(key);
         if (!parts) continue;
         const shortKey = `${parts.type}/${parts.shortcode}`;
-        if (
-            short.has(shortKey) &&
-            short.get(shortKey).package !== value.package
-        ) {
+        if (short.has(shortKey) && short.get(shortKey).package !== value.package) {
             ambiguous.add(shortKey);
         } else {
             short.set(shortKey, value);
@@ -183,11 +183,17 @@ function mergeForeign(index, foreignIndex) {
 export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
     const index = new Map();
     const ambiguous = new Set();
-    const typeAlias = new Map();
-    const typeCollide = new Set();
+    /** One entry per page, fed to {@link indexAliases} in a pass of its own. */
+    const aliasEntries = [];
     const contentTypes = new Set();
     const sections = new Set();
     const refIndex = new Map();
+    // Every package an address may name: this build's own, plus every one a
+    // vendored manifest speaks for. Without it `readQualifier` cannot see the
+    // leading package segment of a canonical address, and `kethira-place-x`
+    // reads as the unknown type `kethira` (#131).
+    const ownPackage = contentPackage();
+    const packages = new Set(ownPackage ? [ownPackage] : []);
 
     // `section/slug` is unique by construction; the rest are fallbacks.
     for (const e of entries) {
@@ -206,6 +212,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
     // without it the link reads as prose and silently loses its href.
     for (const value of foreignIndex.values()) {
         if (value.type) contentTypes.add(value.type);
+        if (value.package) packages.add(value.package);
     }
 
     // Merged *before* the local type-scoped pass below, so a local page always
@@ -242,10 +249,8 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             // The page's package is the configured one — the site collection
             // resolves it and records it as `pkg`. Never read out of
             // frontmatter: `package:` is retired (#56).
-            index.set(
-                canonicalKey(e.pkg ?? contentPackage(), type, shortcode),
-                value,
-            );
+            index.set(canonicalKey(e.pkg ?? ownPackage, type, shortcode), value);
+            if (e.pkg) packages.add(e.pkg);
             // In Foundry an item and its documentation are two documents, so
             // `skill/wpnc` and `docskill/wpnc` are two UUIDs (#1362). Here the
             // item note renders as one page which *is* its documentation, so
@@ -259,33 +264,38 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
             }
         }
 
-        const aliases = [
-            ...(Array.isArray(e.fm.aliases) ? e.fm.aliases : []),
-            ...(Array.isArray(e.fm.name?.aliases) ? e.fm.name.aliases : []),
-            e.name,
-            path.basename(e.base, ".md").replace(/_/g, " "),
-        ].filter((a) => typeof a === "string" && a);
-
-        for (const alias of aliases) {
-            const key = `${type}|${alias}`.toLowerCase();
-            if (typeCollide.has(key)) continue;
-            const cur = typeAlias.get(key);
-            if (cur && cur.url !== value.url) {
-                typeAlias.delete(key);
-                typeCollide.add(key);
-            } else if (!cur) {
-                typeAlias.set(key, value);
-            }
-        }
+        // The alias sources are the shared ones — `aliases`, `name.aliases`
+        // and `name.full`, and deliberately **not** the filename (#131) — plus
+        // this page's display name, which is what `name.full` becomes on the
+        // site and is carried here already resolved.
+        aliasEntries.push({
+            type,
+            aliases: [...aliasesOf(e.fm), e.name],
+            value,
+        });
     }
 
+    // Built in one pass at the end, by the shared rule, so a collision is a
+    // reportable fact rather than a silently deleted key. Two pages of one
+    // type sharing an alias resolve to neither, and `aliasCollisions` names
+    // every claimant — the citing page is innocent (#13, #131).
+    const {
+        byKey: typeAlias,
+        collisions: aliasCollisions,
+        claims: aliasClaims,
+    } = indexAliases(aliasEntries, { same: (a, b) => a.url === b.url });
+    const typeCollide = new Set(aliasCollisions.map((c) => c.key));
+
     return {
         index,
         ambiguous,
         typeAlias,
         typeCollide,
+        aliasCollisions,
+        aliasClaims,
         contentTypes,
         sections,
+        packages,
         refIndex,
         conflicts,
     };
@@ -315,13 +325,7 @@ export function buildSiteIndex(entries, { foreignIndex = new Map() } = {}) {
  */
 export function wikiContext(
     built,
-    {
-        src,
-        type = null,
-        errors,
-        foreignIndex = new Map(),
-        manifestsComplete = true,
-    },
+    { src, type = null, errors, foreignIndex = new Map(), manifestsComplete = true },
 ) {
     return {
         index: built.index,
@@ -332,6 +336,7 @@ export function wikiContext(
         typeAlias: built.typeAlias,
         typeCollide: built.typeCollide,
         contentTypes: built.contentTypes,
+        packages: built.packages,
         type,
         errors,
         src,