@heroiclands/package-build 23.1.0 → 23.2.0

package/CHANGELOG.md

@@ -1,5 +1,76 @@
 # @heroiclands/package-build
 
+## 23.2.0
+
+### Minor Changes
+
+**Books**
+
+- `pdf:` declares its books in a `books:` list; a configuration that still writes `pdf.title` or `pdf.document` fails. To move, put `title`, `subtitle`, `document` and `front` into one `pdf.books` entry with an `id`; `fonts`, `iconFonts`, `binary` and `out` stay directly under `pdf:`.
+- `package-build pdf` builds every declared book, and `--book <id>` builds one. Each book's PDF is named from its `out` stem (default `<package>-<id>`) and the version; write `out: <package>` to keep a single book's file name.
+
+**Authors**
+
+- Authors are listed once, in a top-level `authors` list, each with an optional role; the Foundry manifest's authors and the site's byline come from it. Move `packageBuild.manifest.authors` up to `authors`; the manifest block refuses it.
+
+**Cultures**
+
+- A setting guide must name the culture it introduces in `data.culture`. Places, affiliations and every kind of lore may name theirs; other `doc` notes may not, and a culture note may state it only as itself.
+
+**Closed note fields**
+
+- `icon` is accepted only on beings, Items, macros and bundles; a document, map, lore, place or scenario that writes it is refused at the key. An empty `icon`, `tokenIcon` or `banner` is an error at its line.
+- A `data.banner` naming no image is an error at its line, and `data.affiliations` written as a list is an error at its line.
+- A note or a being's `items:` entry with an undeclared `type` is refused at its `type:` line, including `character`, `creature`, `armor`, `concoction`, `projectile` and the map types `battlemap`, `localmap` and `regionalmap`.
+- A `data:` property written at the top level, or in a `sohl:` or `hm3:` block, is an error at its own line; `archetype`, `relation`, `birthday`, a being's `stations`, and top-level `draft`, `aliases`, `section`, `traits` and `folder` are unrecognized keys.
+- Address shortcodes must be lowercase; a reference that spells one with capitals is an error.
+- Undeclared configuration keys, such as `packs[].folders` and `site.trees`, are refused as unrecognized options, and `package-build content-format notes` is not a command.
+
+### Patch Changes
+
+**Books**
+
+- A run reports every printable note no book selects, as a warning by default; `pdf.coverage` makes it an error or silences it, and `pdf.unprinted` names notes that belong in no book.
+- A note several books select prints in each, and the summary names its home book, the first in the list; a cross-reference to a note in another book names that book and its page.
+- Each book's index lists its own notes.
+- A section whose queries select nothing is left out of the book; a book that selects nothing at all is an error.
+- A book can open with a full-page cover image under its title, and its title page lists the authors, the copyright and the licence.
+- `package-build pdf --list-assets` prints the output path of each declared book as JSON, without building anything.
+
+**Cultures**
+
+- A place takes the culture of the places it sits within, and an affiliation that of the bodies it answers to; a polity with neither takes that of its seat and the places it governs. Content tables, book queries and place and affiliation pages use that inherited culture.
+- A note whose parents belong to different cultures is an error until it names its own.
+
+**Pages and maps**
+
+- A page declines its hero image with `data.banner: none`, and a `data.banner` image resolves to the picture it names on homepages and content pages alike.
+- A map note can name its thumbnail with `data.thumbnail`, an image Address, and the compiled Scene shows that picture in Foundry's Scene lists without changing the map's background art.
+
+**Beings**
+
+- A membership in `data.affiliations` can list the societies it is held in with `societies`; on SoHL, the first society named becomes the membership's society on the character sheet.
+- Compiled actors and items keep their default artwork under the HM3 system's asset layout.
+- `package-build lint` resolves a being's embedded `model:` addresses against a `recommends` system that declares `itemCatalog: true`, as the compile does.
+
+**Dependencies**
+
+- A dependency whose cached index comes from an older package-build fails naming that dependency and the fix: update it, then run `package-build deps fetch`.
+
+**Foundry test containers and deployment**
+
+- An e2e run seeds its test world as the container's user and launches it, even after Foundry has repaired a database in it; when the world does not activate, the hint names the stage, so `package-build container <stage> logs` can be pasted as written.
+- A container pinned to an exact Foundry build runs that build's own image, such as `felddy/foundryvtt:14.359`, and with the build cached and a licence present it starts without signing in to foundryvtt.com.
+- A deployment removes its previous package tree even when Foundry's container owns the files in it, and sweeps away the `<id>.old-<pid>` trees earlier deployments left; a tree that still cannot be removed is a warning naming the command that removes it.
+
+## 23.1.1
+
+### Patch Changes
+
+`package-build yaml` accepts an empty trigger such as `workflow_dispatch:` in a Gitea workflow under `.gitea/workflows/`, as it already does under `.github/workflows/`.
+
+Rebuilding a release of the same commit produces an identical `module.zip` or `system.zip`, so a rebuilt archive can be compared with the one already published. Setting `SOURCE_DATE_EPOCH` stamps the archive's files with that time.
+
 ## 23.1.0
 
 ### Minor Changes

package/bin/content-commands.mjs

@@ -24,7 +24,6 @@
  *   npx package-build lint [root] [--no-references]
  *   npx package-build content-format schema --schema <system>=<path>
  *   npx package-build content-format fields [--fields <system>]
- *   npx package-build content-format notes [root] [--strict]
  *   npx package-build links [root] [--manifests <dir>]
  *   npx package-build format [paths..] [--write]
  *   npx package-build markdown [paths..] [--fix]
@@ -46,7 +45,8 @@ import prefix from "loglevel-plugin-prefix";
 import { compilePacks, cleanPacks, unpackPacks } from "../engine/compendiums.mjs";
 import { compilesFoundryDocuments, publishesContentPages } from "../content-config.mjs";
 import { loadPackConfig, packConfigPath } from "../engine/pack-config.mjs";
-import { buildPdf } from "../engine/pdf-build.mjs";
+import { buildPdf, listBookAssets } from "../engine/pdf-build.mjs";
+import { summaryLines } from "../engine/pdf-coverage.mjs";
 import {
     fetchAllCatalogs,
     fetchCatalogFromPath,
@@ -79,11 +79,7 @@ import {
     systemBlocksFor,
 } from "../engine/frontmatter-lint.mjs";
 import { loadContentFormat } from "../engine/content-format.mjs";
-import {
-    checkDeclaredFields,
-    checkSchemaTargets,
-    measureCorpus,
-} from "../engine/content-format-check.mjs";
+import { checkDeclaredFields, checkSchemaTargets } from "../engine/content-format-check.mjs";
 import {
     compareFields,
     resolveSchemaArtifact,
@@ -106,14 +102,7 @@ import { NOTE_VOCABULARY } from "../engine/note-vocabulary.mjs";
 import { checkFormatting, checkPrettierConventions, lintMarkdown } from "../engine/prose-lint.mjs";
 import { lintProse, scoreProseTree } from "../engine/readability-lint.mjs";
 import { loadPackageBuildConfig } from "../config.mjs";
-import {
-    authoredFrontmatter,
-    emitContentIndex,
-    indexRecordsFor,
-    isAssetRecord,
-    isNoteRecord,
-    noteFile,
-} from "../engine/content-index.mjs";
+import { emitContentIndex, indexRecordsFor, isAssetRecord } from "../engine/content-index.mjs";
 import {
     buildSite,
     gatesFailed,
@@ -123,11 +112,7 @@ import { auditLinks, buildLinkIndex, walkReachability } from "../engine/content-
 import { prepareTreeSqlTables } from "../engine/sql-tables.mjs";
 // The one place a link finding is worded, shared with both builds.
 import { linkFindingMessage } from "../engine/wikilink-syntax.mjs";
-import {
-    emitDiagnostic,
-    positionInFrontmatter,
-    positionOfLiteral,
-} from "../engine/diagnostics.mjs";
+import { emitDiagnostic, positionOfLiteral } from "../engine/diagnostics.mjs";
 import { reportFindings } from "./report.mjs";
 import {
     readItemAddresses,
@@ -199,8 +184,8 @@ function reportFailure(err) {
 /**
  * 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 —
+ * Used only to turn a link finding into a position. A path that does not
+ * resolve — 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.
  *
@@ -637,7 +622,6 @@ function docsCommand() {
  *   naming system's published `schema.json`. A failure means the specification
  *   and the system disagree, which is a defect in one of the two.
  * - `fields` compares declared field mappings with compiler declarations.
- * - `notes` measures authored notes against the declared vocabulary.
  *
  * The shipped contract is `engine/content-format.yaml`; guide layout does not
  * participate in validation.
@@ -648,12 +632,11 @@ function docsCommand() {
 function contentFormatCommand() {
     return {
         command: "content-format <action>",
-        describe: "Check the content format specification against schemas and notes",
+        describe: "Check the content format specification against schemas and field declarations",
         builder: (yargs) =>
             yargs
                 .command(contentFormatSchemaCommand())
                 .command(contentFormatFieldsCommand())
-                .command(contentFormatNotesCommand())
                 .demandCommand(1, "Name an action.")
                 .strict(),
         handler: () => {},
@@ -865,95 +848,6 @@ function contentFormatFieldsCommand() {
     };
 }
 
-/**
- * `content-format notes` — a content tree, against the declared vocabulary.
- *
- * **A report, not a gate.** Every authored note predates the format, so a
- * failing check would be red in every repository from the day it lands and
- * would stay red for the length of the migration — which is a check nobody
- * can act on. `--strict` raises the findings to errors, turned on slice by
- * slice as each class of finding reaches zero.
- *
- * @returns {object} The yargs command module.
- */
-function contentFormatNotesCommand() {
-    return {
-        command: "notes [root]",
-        describe: "Measure a content tree against the vocabulary the format declares (a report)",
-        builder: (yargs) => {
-            yargs.positional("root", {
-                describe: "Content tree to measure. Defaults to the configured contentBase.",
-                type: "string",
-            });
-            yargs.option("spec", {
-                describe:
-                    "The format contract to read. Defaults to the engine/content-format.yaml this package ships.",
-                type: "string",
-            });
-            yargs.option("strict", {
-                describe:
-                    "Fail on the findings instead of reporting them. Turned on per slice, as each class reaches zero.",
-                type: "boolean",
-                default: false,
-            });
-        },
-        handler: (argv) => {
-            try {
-                const config = loadPackConfig();
-                const root = argv.root ?? config.paths.content;
-                const format = specFrom(argv);
-
-                // The corpus from the index, like every other check.
-                // A report measuring the tree against the declared vocabulary
-                // has to be looking at the same tree the compile will, or its
-                // counts describe a corpus nobody builds.
-                const corpusProblems = [];
-                const records = indexRecordsFor({
-                    contentBase: root,
-                    config,
-                    skipDirectories: config.skipDirectories,
-                    problems: corpusProblems,
-                });
-                for (const problem of corpusProblems) emitDiagnostic(problem);
-                if (corpusProblems.length) process.exitCode = 1;
-
-                const notes = [];
-                for (const record of records) {
-                    // A documentation journal is a document this tree emits,
-                    // not a note in it, and has no authored frontmatter to
-                    // measure.
-                    if (!isNoteRecord(record) || typeof record.type !== "string") continue;
-                    const absPath = noteFile(root, record);
-                    notes.push({
-                        file: absPath,
-                        // What the author wrote, never the keys the index
-                        // derived — this measures a note against a vocabulary,
-                        // and `address:` is in no vocabulary.
-                        fm: authoredFrontmatter(record),
-                        raw: fs.readFileSync(absPath, "utf8"),
-                    });
-                }
-
-                const { findings, byClass } = measureCorpus(notes, format, {
-                    strict: argv.strict,
-                });
-                for (const finding of findings) emitDiagnostic(finding);
-
-                const counts = Object.entries(byClass).sort(([a], [b]) => (a < b ? -1 : 1));
-                for (const [cls, count] of counts) log.info(`${cls}: ${count}`);
-                log.info(
-                    `${findings.length} finding(s) across ${notes.length} note(s) ` +
-                        `measured against ${format.file}.`,
-                );
-                if (argv.strict && findings.length) process.exitCode = 1;
-            } catch (err) {
-                reportFailure(err);
-                process.exitCode = 1;
-            }
-        },
-    };
-}
-
 /**
  * `package-build lint` — check a content tree's addresses.
  *
@@ -999,11 +893,13 @@ function lintCommand() {
                 // not take every other finding in the tree with it, and the
                 // reader needs a line to open, not a stack.
                 const corpusProblems = [];
+                const parsed = new Map();
                 const records = indexRecordsFor({
                     contentBase: root,
                     config,
                     skipDirectories: config.skipDirectories,
                     problems: corpusProblems,
+                    parsed,
                 });
                 for (const problem of corpusProblems) emitDiagnostic(problem);
                 // An error whatever the command's own strictness: the note is
@@ -1029,6 +925,7 @@ function lintCommand() {
                     sqlTables: await prepareTreeSqlTables(root, {
                         config,
                         records,
+                        parsed,
                         skipDirectories: config.skipDirectories,
                     }),
                 });
@@ -1142,9 +1039,8 @@ function lintCommand() {
                         builders: fieldSpecs,
                         artifact: schema.artifact,
                         // A schema is keyed by document subtype and a field
-                        // declaration by note type. Those were one string until
-                        // Three are renamed, and joining them by name
-                        // after that would drop `armorgear`'s findings without
+                        // declaration by note type, and the two can differ, so
+                        // joining them by name would drop findings without
                         // saying so — the seam exists for exactly this.
                         subtypeOf: (type) => schemaSubtypeOf(config.stats?.systemId, type),
                     });
@@ -1265,13 +1161,8 @@ function lintCommand() {
                     ...generatedArt,
                     ...artSizes,
                 ];
-                // Only an **error** fails the run. Every finding was an error
-                // by then, so this changes nothing on its own —
-                // but a field retired in favour of another is reported while
-                // both spellings still compile, and failing a build over a note
-                // that produces the correct document would red a tree that has
-                // done nothing wrong. `reportFindings` already draws exactly
-                // that line, so the rule is the shared one rather than a second
+                // Only an **error** fails the run. `reportFindings` draws that
+                // line, so the rule is the shared one rather than a second
                 // copy here. Each finding names its own file.
                 const errors = reportFindings(findings, {});
                 if (errors) {
@@ -1377,8 +1268,8 @@ function formatCommand() {
                     );
                     // `--write` collects findings too — a file Prettier cannot
                     // parse, or one that will not format to a fixpoint — and
-                    // used to discard them, so a run that had left files
-                    // unformatted still reported success and exited 0.
+                    // a run that leaves files unformatted must not report
+                    // success.
                     for (const finding of findings) emitDiagnostic(finding);
                     if (findings.length) {
                         log.error(
@@ -1482,11 +1373,13 @@ function linksCommand() {
                 // Enumerated once and shared, as in `lint`, and a note
                 // it cannot record is reported rather than thrown.
                 const corpusProblems = [];
+                const parsed = new Map();
                 const records = indexRecordsFor({
                     contentBase,
                     config,
                     ...scope,
                     problems: corpusProblems,
+                    parsed,
                 });
                 for (const problem of corpusProblems) emitDiagnostic(problem);
                 // An error whatever the command's own strictness: the note is
@@ -1500,6 +1393,7 @@ function linksCommand() {
                     sqlTables: await prepareTreeSqlTables(contentBase, {
                         config,
                         records,
+                        parsed,
                         ...scope,
                     }),
                 });
@@ -1690,9 +1584,10 @@ function contentIndexCommand() {
 }
 
 /**
- * `package-build pdf` — build the book the content tree publishes as.
+ * `package-build pdf` — build the books the content tree publishes as.
  *
- * The third surface, beside `package compile` and `site`. It takes the same
+ * The third surface, beside `package compile` and `site`. It builds every book
+ * `pdf.books` declares, or the one `--book <id>` names, and takes the same
  * `--out` override the site command does, and reports what it found in the same
  * `file:line:column: severity: message` shape every other pass here uses — so
  * one editor, one CI annotator and one `grep` read all three.
@@ -1707,17 +1602,27 @@ function contentIndexCommand() {
 function pdfCommand() {
     return {
         command: "pdf",
-        describe: "Build the content tree as a PDF",
+        describe: "Build the content tree as one PDF per declared book",
         builder: (yargs) => {
             yargs
+                .option("book", {
+                    describe: "Build only the book with this `id`. Every declared book by default.",
+                    type: "string",
+                })
                 .option("out", {
-                    describe: "Write the book here instead of the configured `pdf.out`.",
+                    describe: "Write the books here instead of the configured `pdf.out`.",
                     type: "string",
                 })
                 .option("book-version", {
                     describe: "Stamp this version on the title page and in the file name.",
                     type: "string",
                 })
+                .option("list-assets", {
+                    describe:
+                        "Print each book's output path as JSON, in configuration order, and build nothing.",
+                    type: "boolean",
+                    default: false,
+                })
                 // Declared positively so yargs derives `--no-compile` from it;
                 // an option literally named `no-compile` is rejected as unknown
                 // when it is actually passed.
@@ -1729,7 +1634,16 @@ function pdfCommand() {
         },
         handler: async (argv) => {
             try {
+                if (argv.listAssets) {
+                    const assets = listBookAssets({
+                        ...(argv.out ? { out: argv.out } : {}),
+                        ...(argv.bookVersion ? { version: String(argv.bookVersion) } : {}),
+                    });
+                    console.log(JSON.stringify(assets, null, 2));
+                    return;
+                }
                 const result = await buildPdf({
+                    ...(argv.book !== undefined ? { book: String(argv.book) } : {}),
                     ...(argv.out ? { out: argv.out } : {}),
                     ...(argv.bookVersion ? { version: String(argv.bookVersion) } : {}),
                     compile: argv.compile !== false,
@@ -1746,28 +1660,30 @@ function pdfCommand() {
                     log.info(`${report.file}: ${report.message}`);
                 }
 
-                if (!result.built) {
-                    // A reason is a deliberate no-op — the fence, an absent
-                    // block, an absent tree. No reason means the findings above
-                    // say what went wrong, and those decide the exit code.
-                    if (result.reason) {
-                        log.info(`No book built: ${result.reason}`);
-                        return;
-                    }
-                    process.exitCode = 1;
+                // A reason is a deliberate no-op — the fence, an absent block,
+                // an absent tree. No reason means the findings above say what
+                // went wrong, and those decide the exit code.
+                if (result.reason) {
+                    log.info(`No book built: ${result.reason}`);
                     return;
                 }
 
-                const { stats } = result;
-                log.info(
-                    `${stats.notes} entr(ies) and ${stats.prose} prose file(s) across ` +
-                        `${stats.sections} section(s)` +
-                        (stats.repeated ?
-                            `, ${stats.repeated} of them printed more than once`
-                        :   ""),
-                );
-                log.info(`Typst source: ${result.typ}`);
-                if (result.pdf) log.info(`Book: ${result.pdf}`);
+                for (const book of result.books) {
+                    const { stats } = book;
+                    log.info(
+                        `${book.id}: ${stats.notes} entr(ies) and ${stats.prose} prose ` +
+                            `file(s) across ${stats.sections} section(s)` +
+                            (stats.repeated ?
+                                `, ${stats.repeated} of them printed more than once`
+                            :   ""),
+                    );
+                    log.info(`${book.id}: Typst source: ${book.typ}`);
+                    if (book.pdf) log.info(`${book.id}: Book: ${book.pdf}`);
+                }
+                if (result.summary) {
+                    for (const line of summaryLines(result.summary)) log.info(line);
+                }
+                if (!result.built) process.exitCode = 1;
                 if (errors) process.exitCode = 1;
             } catch (err) {
                 reportFailure(err);
@@ -2178,11 +2094,13 @@ function reachabilityCommand() {
                 const dir = String(argv.dir).replace(/\/+$/, "");
                 const scope = { skipDirectories: config.skipDirectories };
                 const corpusProblems = [];
+                const parsed = new Map();
                 const records = indexRecordsFor({
                     contentBase,
                     config,
                     ...scope,
                     problems: corpusProblems,
+                    parsed,
                 });
                 for (const problem of corpusProblems) emitDiagnostic(problem);
                 // An error whatever the command's own strictness: the note is
@@ -2196,6 +2114,7 @@ function reachabilityCommand() {
                     sqlTables: await prepareTreeSqlTables(contentBase, {
                         config,
                         records,
+                        parsed,
                         ...scope,
                     }),
                 });

package/bin/package-build.mjs

@@ -87,7 +87,7 @@ import { hideBin } from "yargs/helpers";
 
 import { loadPackageBuildConfig } from "../config.mjs";
 import { checkForeignAssetBindings } from "../engine/asset-bindings.mjs";
-import { formatDiagnostic } from "../engine/diagnostics.mjs";
+import { emitDiagnostic, formatDiagnostic } from "../engine/diagnostics.mjs";
 import { writeSiteRoot } from "../engine/site-root.mjs";
 import { DEPLOY_ROOT } from "../engine/site-config.mjs";
 import { compilesFoundryDocuments } from "../content-config.mjs";
@@ -117,8 +117,15 @@ import { findHardcodedText, findTemplateSyntaxErrors } from "../templates.mjs";
 import { checkBundleLoading } from "../bundle.mjs";
 import { packRelease } from "../release.mjs";
 import { writeManifest } from "../manifest.mjs";
-import { deployStage } from "../deploy.mjs";
-import { CONTAINER_ACTIONS, containerAction } from "../container.mjs";
+import { deployStage, resolveStage } from "../deploy.mjs";
+import {
+    CONTAINER_ACTIONS,
+    containerAction,
+    containerRemovalCommand,
+    containerTreeRemover,
+    dataEnvVar,
+    resolveContainer,
+} from "../container.mjs";
 import { E2E_MODES, e2eFast, e2eRun, e2eSweep, seedTestWorld } from "../e2e.mjs";
 import { reportFindings } from "./report.mjs";
 import { formatGenerated } from "../engine/format-generated.mjs";
@@ -214,8 +221,16 @@ function initCommand() {
             const root = path.resolve(args.directory ?? process.cwd());
             if (args.check) {
                 const findings = checkProject(root);
-                for (const { file, message } of findings) {
-                    console.error(`${path.join(root, file)}: error: ${message}`);
+                for (const { file, line, column, message } of findings) {
+                    console.error(
+                        formatDiagnostic({
+                            file: path.join(root, file),
+                            line,
+                            column,
+                            severity: "error",
+                            message,
+                        }),
+                    );
                 }
                 if (findings.length) process.exitCode = 1;
                 else console.log(`package-build: ${root} is ready to build.`);
@@ -1440,11 +1455,19 @@ function releaseCommand() {
             // book that would not set is a problem to fix rather than a reason
             // to have published nothing.
             for (const finding of result.pdfFindings ?? []) {
-                console.error(`${finding.file ?? "book"}: ${finding.severity}: ${finding.message}`);
+                console.error(
+                    formatDiagnostic({
+                        ...finding,
+                        ...(finding.file ?
+                            { file: path.relative(process.cwd(), finding.file) }
+                        :   {}),
+                    }),
+                );
             }
-            if (result.pdf) {
-                console.log(`📕 Book: ${path.relative(config.rootDir, result.pdf)}`);
-            } else if (result.pdfSkipped) {
+            for (const pdf of result.pdfs ?? []) {
+                console.log(`📕 Book: ${path.relative(config.rootDir, pdf)}`);
+            }
+            if (!result.pdfs?.length && result.pdfSkipped) {
                 console.log(`   No book: ${result.pdfSkipped}`);
             }
         }),
@@ -1475,15 +1498,38 @@ function deployCommand() {
 
             await loadEnvironment(config);
 
-            const { stage } = await deployStage({
+            // The container is resolved only once the host user is refused a
+            // removal, so a deploy that meets no refusal needs no container.
+            const containerFor = () =>
+                resolveContainer({ stage: resolveStage(args.stage), config });
+            const { stage, leftovers, remote } = await deployStage({
                 stage: args.stage,
                 source: path.join(config.rootDir, config.stageDir),
                 packageKind: config.packageKind,
                 packageId: config.packageId,
                 prefix: config.envPrefix,
                 log: (message) => console.log(message),
+                removeTree: (tree, where) =>
+                    containerTreeRemover({ container: containerFor() })(tree, where),
             });
             console.log(`Deployed stage '${stage}' successfully.`);
+            for (const leftover of leftovers) {
+                const remedy =
+                    remote ?
+                        "remove it on the host as the user that owns its files"
+                    :   `remove it with \`${containerRemovalCommand({
+                            image: containerFor().image,
+                            dataRoot: process.env[dataEnvVar(stage)].trim(),
+                            tree: leftover.path,
+                        })}\``;
+                emitDiagnostic({
+                    file: leftover.path,
+                    severity: "warning",
+                    message:
+                        `the new package is installed, but its previous tree could ` +
+                        `not be removed (${leftover.reason}); ${remedy}`,
+                });
+            }
         }),
     };
 }