@navbook/cli 0.3.0 → 0.5.0

package/dist/install/hook.js.map

@@ -1 +1 @@
-{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../src/install/hook.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EACL,SAAS,EACT,UAAU,EACV,SAAS,EACT,YAAY,EACZ,MAAM,EACN,QAAQ,EACR,aAAa,GACd,MAAM,SAAS,CAAC;AACjB,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAEzC,MAAM,CAAC,MAAM,YAAY,GAAG,mBAAmB,CAAC;AAChD,MAAM,CAAC,MAAM,UAAU,GAAG,mBAAmB,CAAC;AAC9C,MAAM,CAAC,MAAM,SAAS,GAAG,YAAY,CAAC;AAEtC,MAAM,OAAO,GAAG,WAAW,CAAC;AAE5B,MAAM,IAAI,GAAG,GAAG,YAAY;;;;;;;;;;EAU1B,UAAU,EAAE,CAAC;AAEf,MAAM,UAAU,QAAQ,CAAC,QAAgB;IACvC,OAAO,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,SAAS,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,QAAQ,CAAC,YAAY,CAAC,CAAC;AAC/E,CAAC;AAED,wEAAwE;AACxE,MAAM,UAAU,WAAW,CAAC,QAAgB;IAC1C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,SAAS,CAAC,OAAO,CAAC,IAAI,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IAEpE,IAAI,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO;IAC5C,MAAM,OAAO,GACX,QAAQ,CAAC,IAAI,EAAE,KAAK,EAAE;QACpB,CAAC,CAAC,GAAG,OAAO,KAAK,IAAI,IAAI;QACzB,CAAC,CAAC,GAAG,QAAQ,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC;IACrD,aAAa,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,CAAC,CAAC;IACrC,SAAS,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;AACzB,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,aAAa,CAAC,QAAgB;IAC5C,MAAM,IAAI,GAAG,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAChC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC;QAAE,OAAO;IAC9B,MAAM,QAAQ,GAAG,YAAY,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;IAC5C,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,YAAY,CAAC;QAAE,OAAO;IAE7C,MAAM,QAAQ,GAAG,QAAQ;SACtB,KAAK,CAAC,IAAI,CAAC;SACX,MAAM,CACL,CAAC,KAAK,EAAE,IAAI,EAAE,EAAE;QACd,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,YAAY;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC9E,IAAI,IAAI,CAAC,IAAI,EAAE,KAAK,UAAU;YAAE,OAAO,EAAE,KAAK,EAAE,KAAK,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;QAC7E,IAAI,CAAC,KAAK,CAAC,MAAM;YAAE,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;QAC1C,OAAO,KAAK,CAAC;IACf,CAAC,EACD,EAAE,KAAK,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,CAC7B;SACA,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEpB,MAAM,SAAS,GAAG,QAAQ,CAAC,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC;IACvD,IAAI,SAAS,KAAK,EAAE,EAAE,CAAC;QACrB,MAAM,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAC9B,OAAO;IACT,CAAC;IACD,aAAa,CAAC,IAAI,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,IAAI,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;IAC5F,SAAS,CAAC,IAAI,EAAE,QAAQ,CAAC,IAAI,CAAC,CAAC,IAAI,GAAG,KAAK,CAAC,CAAC;AAC/C,CAAC"}
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../../src/install/hook.ts"],"names":[],"mappings":"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"}

package/dist/main.d.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * `nav` entry point.
+ */
+import { type ExitCode } from "./errors.ts";
+export interface RunOptions {
+    argv?: string[];
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    stdout?: NodeJS.WriteStream;
+    stderr?: NodeJS.WriteStream;
+}
+/**
+ * Run the CLI and return its exit code. Never throws for expected failures.
+ *
+ * Asynchronous because a plugin's code is imported when one of its commands
+ * runs (spec 04 §4.3), and `import()` is a promise. Nothing else about the
+ * CLI became async: every built-in verb is still synchronous from end to end,
+ * and a run with no plugins awaits nothing that was not already resolved.
+ */
+export declare function run(opts?: RunOptions): Promise<ExitCode>;

package/dist/main.js

@@ -7,31 +7,135 @@ import { WorkspaceError } from "@navbook/core";
 import { CommanderError } from "commander";
 import { makeContext } from "./context.js";
 import { NavError } from "./errors.js";
-import { buildProgram } from "./program.js";
-/** Run the CLI and return its exit code. Never throws for expected failures. */
-export function run(opts = {}) {
+import { hintUndeclared } from "./plugins/hint.js";
+import { missingLine, resolvePlugins, skippedLine, } from "./plugins/resolve.js";
+import { PluginRuntime } from "./plugins/runtime.js";
+import { BUILTIN_NOUNS, buildProgram } from "./program.js";
+/** The reading of a repository there was none of, used when discovery failed. */
+const NO_DECLARATION = {
+    plugins: new Map(),
+    declared: false,
+    problems: [],
+};
+/**
+ * Run the CLI and return its exit code. Never throws for expected failures.
+ *
+ * Asynchronous because a plugin's code is imported when one of its commands
+ * runs (spec 04 §4.3), and `import()` is a promise. Nothing else about the
+ * CLI became async: every built-in verb is still synchronous from end to end,
+ * and a run with no plugins awaits nothing that was not already resolved.
+ */
+export async function run(opts = {}) {
     const argv = opts.argv ?? process.argv.slice(2);
     const stdout = opts.stdout ?? process.stdout;
     const stderr = opts.stderr ?? process.stderr;
+    const env = opts.env ?? process.env;
+    // Built once and memoised. `ext` is filled in below, before any command
+    // runs, when and only when the words typed call for it.
     let ctx = null;
-    const getCtx = () => {
-        ctx ??= makeContext({ cwd: opts.cwd, env: opts.env, stdout, stderr });
+    let ext;
+    // A second context, for the commands that work outside a repository (the
+    // plugin store's verbs), which a missing repository must not fail. Kept
+    // apart so a command that does need one still gets the complaint.
+    let looseCtx = null;
+    const getCtx = (want = {}) => {
+        if (want.requireRepo === false) {
+            looseCtx ??= makeContext({
+                cwd: opts.cwd,
+                env: opts.env,
+                stdout,
+                stderr,
+                requireRepo: false,
+            });
+            return looseCtx;
+        }
+        ctx ??= makeContext({ cwd: opts.cwd, env: opts.env, stdout, stderr, ...(ext ? { ext } : {}) });
         return ctx;
     };
-    const program = buildProgram(getCtx);
+    let plugins;
+    try {
+        plugins = loadPluginRuntime(getCtx, env, stderr);
+    }
+    catch (error) {
+        return report(error, stderr);
+    }
+    // The one place plugin code may be imported before parsing, and only because
+    // the tree cannot be read without it: a registered directory would otherwise
+    // parse as an uninterpreted path and a registered key as raw YAML. Decided
+    // from the manifests, so a run that needs none pays nothing (spec 04 §4.3).
+    if (plugins.needsCoreFor(argv)) {
+        try {
+            ext = await plugins.coreExtensions(getCtx());
+            // Drop any context built while resolving, so nothing that reads the tree
+            // can have been handed one without the extensions.
+            ctx = null;
+        }
+        catch (error) {
+            return report(error, stderr);
+        }
+    }
+    const program = buildProgram(getCtx, plugins);
     program.exitOverride();
     program.configureOutput({
         writeOut: (text) => stdout.write(text),
         writeErr: (text) => stderr.write(text),
     });
     try {
-        program.parse(argv, { from: "user" });
+        await program.parseAsync(argv, { from: "user" });
         return 0;
     }
     catch (error) {
         return report(error, stderr);
     }
 }
+/**
+ * Resolve what plugins this invocation has, and say what is missing.
+ *
+ * Reading the declaration needs a repository, and plenty of commands work
+ * without one (`nav id`, `nav --help`, `nav init`). A context that cannot be
+ * built is therefore not an error here: it means there is no declaration to
+ * read, and whichever command runs next will complain about the missing
+ * repository in its own words if it needs one.
+ */
+function loadPluginRuntime(getCtx, env, stderr) {
+    let resolved;
+    try {
+        resolved = resolvePlugins(getCtx(), env);
+    }
+    catch {
+        resolved = { active: [], missing: [], skipped: [], declaration: NO_DECLARATION };
+    }
+    const runtime = new PluginRuntime(resolved, BUILTIN_NOUNS);
+    // Said once per run, before anything is parsed, so the reason a command is
+    // missing is on screen above the complaint that it is missing.
+    for (const line of runtime.notices)
+        stderr.write(`${line}\n`);
+    for (const { name, reason } of resolved.skipped)
+        stderr.write(`${skippedLine(name, reason)}\n`);
+    for (const name of resolved.missing) {
+        stderr.write(`${missingLine(name, navDirOf(getCtx))}\n`);
+    }
+    // Said here rather than per command: whatever runs next, the reason `nav` is
+    // ignoring a directory belongs above its output, not buried in it.
+    try {
+        const ctx = getCtx();
+        if (ctx.hasNavbook) {
+            hintUndeclared(ctx, resolved.declaration, resolved.active.flatMap((plugin) => plugin.manifest.format?.root ?? []));
+        }
+    }
+    catch {
+        // No repository: there is no tree to have namespaces in.
+    }
+    return runtime;
+}
+function navDirOf(getCtx) {
+    try {
+        return getCtx().navDir;
+    }
+    catch {
+        return ".navbook";
+    }
+}
 function report(error, stderr) {
     if (error instanceof CommanderError) {
         // Commander already wrote help or the version string.
@@ -93,6 +197,6 @@ function invokedDirectly() {
 if (invokedDirectly()) {
     exitQuietlyOnClosedPipe(process.stdout);
     exitQuietlyOnClosedPipe(process.stderr);
-    process.exitCode = run();
+    process.exitCode = await run();
 }
 //# sourceMappingURL=main.js.map

package/dist/main.js.map

@@ -1 +1 @@
-{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"main.js","sourceRoot":"","sources":["../src/main.ts"],"names":[],"mappings":"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"}

package/dist/plugins/commands.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Building Commander commands out of manifests — spec 04 §4.3.
+ *
+ * Every command a plugin adds is built from its declaration, with no plugin
+ * code loaded. That is what makes `nav --help` and shell completion work
+ * without paying for an import, and it is what the manifest's shapes exist to
+ * make possible. The plugin's own module is imported inside the action, the
+ * moment somebody actually runs the command.
+ *
+ * A name that collides with a built-in noun, or with one an earlier plugin
+ * took, is refused and the plugin skipped, because a word that means different
+ * things depending on load order is worse than one that means nothing.
+ */
+import type { CommandSpec, OptionSpec, VerbContribution } from "@navbook/core";
+import { Command } from "commander";
+import type { Ctx } from "../context.ts";
+import type { LoadedPlugin } from "./resolve.ts";
+/** Everything the CLI needs to know about one plugin's declared commands. */
+export interface PluginCommands {
+    /** Top-level nouns, by name, with the plugin that declared each. */
+    nouns: Map<string, {
+        plugin: LoadedPlugin;
+        spec: CommandSpec;
+    }>;
+    /** Contributions to existing verbs, keyed by the verb as typed. */
+    contributions: Map<string, {
+        plugin: LoadedPlugin;
+        spec: VerbContribution;
+    }[]>;
+    /** Plugins dropped for a collision, by name, so callers need not parse a message. */
+    skipped: Set<string>;
+    /** One line per plugin skipped, for stderr. */
+    problems: string[];
+}
+/**
+ * Sort out which plugin owns what, refusing collisions.
+ *
+ * `taken` is the built-in noun vocabulary. A plugin colliding with one of
+ * those loses outright; two plugins colliding with each other are resolved by
+ * which was resolved first, and the loser is named.
+ */
+export declare function collectCommands(plugins: readonly LoadedPlugin[], taken: readonly string[]): PluginCommands;
+/** How a plugin command's action is run once its module is loaded. */
+export type RunCommand = (plugin: LoadedPlugin, path: string, args: string[], opts: Record<string, unknown>) => Promise<void>;
+/** Build one plugin noun into a Commander command tree. */
+export declare function buildPluginCommand(plugin: LoadedPlugin, spec: CommandSpec, getCtx: () => Ctx, run: RunCommand): Command;
+/** Apply one declared option to a command. */
+export declare function applyOption(command: Command, spec: OptionSpec): void;
+/**
+ * Why a declared option cannot be applied, or null when it can.
+ *
+ * Two different rules, because two different namespaces are at stake.
+ *
+ * On a plugin's **own** command the plugin owns every flag, so a short one is
+ * its business: `nav feature open -m "…"` reads exactly as `nav issue open -m
+ * "…"` does, and denying it would make a plugin's commands feel like
+ * second-class ones for no gain.
+ *
+ * On a **contribution** to a built-in verb the namespace is shared, and short
+ * flags are the scarce part of it — `-m`, `-y`, `-n` already mean things
+ * across the whole CLI. A plugin taking one there would be discovered by
+ * whoever installed two plugins rather than by whoever wrote the second, so
+ * they are refused outright rather than raced for.
+ *
+ * A long flag that is already taken is refused either way, and checked before
+ * Commander sees it: `.option()` throws on a duplicate, which would take the
+ * whole CLI down over one plugin's manifest.
+ */
+export declare function optionCollision(command: Command, spec: OptionSpec, where?: "own" | "contribution"): string | null;

package/dist/plugins/commands.js

@@ -0,0 +1,148 @@
+/**
+ * Building Commander commands out of manifests — spec 04 §4.3.
+ *
+ * Every command a plugin adds is built from its declaration, with no plugin
+ * code loaded. That is what makes `nav --help` and shell completion work
+ * without paying for an import, and it is what the manifest's shapes exist to
+ * make possible. The plugin's own module is imported inside the action, the
+ * moment somebody actually runs the command.
+ *
+ * A name that collides with a built-in noun, or with one an earlier plugin
+ * took, is refused and the plugin skipped, because a word that means different
+ * things depending on load order is worse than one that means nothing.
+ */
+import { Command, Option } from "commander";
+import { finiteNumber, wholeNumber } from "../args.js";
+/**
+ * Sort out which plugin owns what, refusing collisions.
+ *
+ * `taken` is the built-in noun vocabulary. A plugin colliding with one of
+ * those loses outright; two plugins colliding with each other are resolved by
+ * which was resolved first, and the loser is named.
+ */
+export function collectCommands(plugins, taken) {
+    const nouns = new Map();
+    const contributions = new Map();
+    const skipped = new Set();
+    const problems = [];
+    const builtin = new Set(taken);
+    for (const plugin of plugins) {
+        const declared = plugin.manifest.cli;
+        if (declared === undefined)
+            continue;
+        const clash = (declared.commands ?? []).find((spec) => builtin.has(spec.name) || nouns.has(spec.name));
+        if (clash !== undefined) {
+            const owner = builtin.has(clash.name)
+                ? "a built-in command"
+                : `plugin ${nouns.get(clash.name)?.plugin.name}`;
+            problems.push(`nav: plugin ${plugin.name} skipped: '${clash.name}' is already ${owner} (spec 04 §4.3)`);
+            skipped.add(plugin.name);
+            continue;
+        }
+        for (const spec of declared.commands ?? [])
+            nouns.set(spec.name, { plugin, spec });
+        for (const spec of declared.contributions ?? []) {
+            const existing = contributions.get(spec.on) ?? [];
+            existing.push({ plugin, spec });
+            contributions.set(spec.on, existing);
+        }
+    }
+    return { nouns, contributions, skipped, problems };
+}
+/** Build one plugin noun into a Commander command tree. */
+export function buildPluginCommand(plugin, spec, getCtx, run) {
+    return buildCommand(plugin, spec, spec.name, getCtx, run);
+}
+function buildCommand(plugin, spec, path, getCtx, run) {
+    const command = new Command(spec.name).description(spec.description);
+    // A group — a noun with verbs under it — has no action of its own, and
+    // Commander's implicit `help` verb is dropped for the reason the built-in
+    // nouns drop it: it prints exactly what `--help` prints.
+    if (spec.commands?.length) {
+        command.helpCommand(false);
+        for (const child of spec.commands) {
+            command.addCommand(buildCommand(plugin, child, `${path} ${child.name}`, getCtx, run));
+        }
+        return command;
+    }
+    for (const argument of spec.arguments ?? [])
+        command.argument(...argumentOf(argument));
+    for (const option of spec.options ?? [])
+        applyOption(command, option);
+    command.action(async (...received) => {
+        // Commander hands the action its positional arguments, then the parsed
+        // options, then the command itself. The declared arguments say how many
+        // positionals there are, so the split needs no guessing.
+        const count = spec.arguments?.length ?? 0;
+        const args = received.slice(0, count);
+        const opts = (received[count] ?? {});
+        // Touch the context before loading the plugin: a command run outside a
+        // repository should say so in the CLI's own words rather than in whatever
+        // the plugin says when it finds no tree.
+        getCtx();
+        await run(plugin, path, args, opts);
+    });
+    return command;
+}
+/** A declared argument, in the `[name]` / `<name...>` shape Commander parses. */
+function argumentOf(spec) {
+    const dots = spec.variadic === true ? "..." : "";
+    const name = spec.optional === true ? `[${spec.name}${dots}]` : `<${spec.name}${dots}>`;
+    return [name, spec.description ?? ""];
+}
+/** Apply one declared option to a command. */
+export function applyOption(command, spec) {
+    const option = new Option(spec.flags, spec.description);
+    if (spec.repeatable === true) {
+        option.argParser((value, previous = []) => [...previous, value]);
+        option.default([]);
+    }
+    else if (spec.parse === "int") {
+        // The parsers the built-in options use, so a plugin's count is refused
+        // where the built-in ones are: `parseInt` read `2.5` as 2 and `3abc` as 3,
+        // and `Number` reads `0x10` and `1e1` and rounds past 2^53 (#kw143sq9).
+        option.argParser(wholeNumber(null));
+    }
+    else if (spec.parse === "number") {
+        option.argParser(finiteNumber);
+    }
+    if (spec.default !== undefined)
+        option.default(spec.default);
+    command.addOption(option);
+}
+/**
+ * Why a declared option cannot be applied, or null when it can.
+ *
+ * Two different rules, because two different namespaces are at stake.
+ *
+ * On a plugin's **own** command the plugin owns every flag, so a short one is
+ * its business: `nav feature open -m "…"` reads exactly as `nav issue open -m
+ * "…"` does, and denying it would make a plugin's commands feel like
+ * second-class ones for no gain.
+ *
+ * On a **contribution** to a built-in verb the namespace is shared, and short
+ * flags are the scarce part of it — `-m`, `-y`, `-n` already mean things
+ * across the whole CLI. A plugin taking one there would be discovered by
+ * whoever installed two plugins rather than by whoever wrote the second, so
+ * they are refused outright rather than raced for.
+ *
+ * A long flag that is already taken is refused either way, and checked before
+ * Commander sees it: `.option()` throws on a duplicate, which would take the
+ * whole CLI down over one plugin's manifest.
+ */
+export function optionCollision(command, spec, where = "contribution") {
+    const flags = spec.flags.split(/[ ,|]+/).filter((part) => part.startsWith("-"));
+    if (where === "contribution") {
+        const short = flags.find((flag) => /^-[^-]/.test(flag));
+        if (short !== undefined) {
+            return `'${short}' is a short flag, which a plugin may not add to a built-in verb`;
+        }
+    }
+    for (const flag of flags) {
+        if (command.options.some((existing) => existing.long === flag || existing.short === flag)) {
+            return `'${flag}' is already an option of '${command.name()}'`;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=commands.js.map

package/dist/plugins/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","sourceRoot":"","sources":["../../src/plugins/commands.ts"],"names":[],"mappings":"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"}

package/dist/plugins/hint.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Saying that a tree holds data this `nav` cannot read.
+ *
+ * Spec 02 §2.12 requires a tool to preserve an extension namespace it does not
+ * understand, and allows it to say the namespace is undeclared. Saying so is
+ * the whole value of the declaration to somebody who has just cloned: the
+ * files are there, `nav` is ignoring them, and nothing else on screen would
+ * explain why.
+ *
+ * One line, on stderr, and never an error. The tree is conforming; this `nav`
+ * simply has less of it than the repository expects.
+ */
+import type { PluginDeclarationReading } from "@navbook/core";
+import type { Ctx } from "../context.ts";
+/**
+ * Say once that the tree holds namespaces nothing here reads.
+ *
+ * `loaded` is the directories a plugin claimed, which are read rather than
+ * ignored and so are not worth a word. `declaration` is what the marker says:
+ * a namespace whose plugin is declared but missing has already been reported
+ * by name, and saying it twice helps nobody.
+ */
+export declare function hintUndeclared(ctx: Ctx, declaration: PluginDeclarationReading, loaded: readonly string[]): void;

package/dist/plugins/hint.js

@@ -0,0 +1,65 @@
+/**
+ * Saying that a tree holds data this `nav` cannot read.
+ *
+ * Spec 02 §2.12 requires a tool to preserve an extension namespace it does not
+ * understand, and allows it to say the namespace is undeclared. Saying so is
+ * the whole value of the declaration to somebody who has just cloned: the
+ * files are there, `nav` is ignoring them, and nothing else on screen would
+ * explain why.
+ *
+ * One line, on stderr, and never an error. The tree is conforming; this `nav`
+ * simply has less of it than the repository expects.
+ */
+import { readdirSync } from "node:fs";
+/** Names this format defines at the top of the root; never a namespace. */
+const FORMAT_NAMES = new Set(["issues", "prs", "archive", "sync", "navbook.json"]);
+/**
+ * Namespaces this project knows the plugin for, so the hint can name it.
+ *
+ * Only the grandfathered pair is listed, and deliberately: a namespace whose
+ * plugin nobody here knows about gets the generic line below, which is the
+ * honest thing to say about a directory some other project's plugin wrote.
+ */
+const KNOWN = {
+    specs: "@navbook/plugin-kb",
+};
+/**
+ * Directories at the top of the root that this format does not define.
+ *
+ * One `readdir` rather than a parse of the tree: the caller has usually just
+ * read the whole repository, and reading it a second time to find out what the
+ * first read ignored would cost more than the hint is worth.
+ */
+function namespaceDirs(navRoot) {
+    try {
+        return readdirSync(navRoot, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory() && !FORMAT_NAMES.has(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Say once that the tree holds namespaces nothing here reads.
+ *
+ * `loaded` is the directories a plugin claimed, which are read rather than
+ * ignored and so are not worth a word. `declaration` is what the marker says:
+ * a namespace whose plugin is declared but missing has already been reported
+ * by name, and saying it twice helps nobody.
+ */
+export function hintUndeclared(ctx, declaration, loaded) {
+    const claimed = new Set(loaded);
+    for (const name of namespaceDirs(ctx.navRoot)) {
+        if (claimed.has(name))
+            continue;
+        const plugin = KNOWN[name];
+        if (plugin !== undefined && declaration.plugins.has(plugin))
+            continue;
+        ctx.stderr.write(plugin === undefined
+            ? `nav: ${ctx.navDir}/${name}/ is not a shape this nav reads; it is preserved untouched (spec 02 §2.12)\n`
+            : `nav: ${ctx.navDir}/${name}/ belongs to ${plugin}, which ${ctx.navDir}/navbook.json does not declare; add it and run 'nav plugin install'\n`);
+    }
+}
+//# sourceMappingURL=hint.js.map

package/dist/plugins/hint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hint.js","sourceRoot":"","sources":["../../src/plugins/hint.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAItC,2EAA2E;AAC3E,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,CAAC,QAAQ,EAAE,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,cAAc,CAAC,CAAC,CAAC;AAEnF;;;;;;GAMG;AACH,MAAM,KAAK,GAA2B;IACpC,KAAK,EAAE,oBAAoB;CAC5B,CAAC;AAEF;;;;;;GAMG;AACH,SAAS,aAAa,CAAC,OAAe;IACpC,IAAI,CAAC;QACH,OAAO,WAAW,CAAC,OAAO,EAAE,EAAE,aAAa,EAAE,IAAI,EAAE,CAAC;aACjD,MAAM,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,WAAW,EAAE,IAAI,CAAC,YAAY,CAAC,GAAG,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;aACvE,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,CAAC;aAC1B,IAAI,EAAE,CAAC;IACZ,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,EAAE,CAAC;IACZ,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,cAAc,CAC5B,GAAQ,EACR,WAAqC,EACrC,MAAyB;IAEzB,MAAM,OAAO,GAAG,IAAI,GAAG,CAAC,MAAM,CAAC,CAAC;IAChC,KAAK,MAAM,IAAI,IAAI,aAAa,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC9C,IAAI,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC;YAAE,SAAS;QAChC,MAAM,MAAM,GAAG,KAAK,CAAC,IAAI,CAAC,CAAC;QAC3B,IAAI,MAAM,KAAK,SAAS,IAAI,WAAW,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC;YAAE,SAAS;QACtE,GAAG,CAAC,MAAM,CAAC,KAAK,CACd,MAAM,KAAK,SAAS;YAClB,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,IAAI,8EAA8E;YAC1G,CAAC,CAAC,QAAQ,GAAG,CAAC,MAAM,IAAI,IAAI,gBAAgB,MAAM,WAAW,GAAG,CAAC,MAAM,uEAAuE,CACjJ,CAAC;IACJ,CAAC;AACH,CAAC"}