@heroiclands/package-build 20.0.0 → 20.2.0

package/types/engine/pack-config.d.mts

@@ -14,6 +14,41 @@
  *   {@link CONFIG_FILENAMES}.
  */
 export function findConfigFile(from: string): string | undefined;
+/**
+ * Which configuration file a build launched here should read, and what each
+ * walk found.
+ *
+ * Kept separate from {@link loadPackConfig} because the *choice* is worth being
+ * able to ask about without loading anything: the two walks disagreeing is the
+ * observable form of #364, and a caller that wants to report it — or a test
+ * that wants to describe it — should not have to reproduce the resolution and
+ * risk disagreeing with the loader about it. It performs I/O, and is named for
+ * it, like the {@link findConfigFile} it calls twice.
+ *
+ * `PACKAGE_BUILD_CONFIG` is deliberately not consulted here. An explicit name
+ * is not a search result: {@link loadPackConfig} short-circuits on it before it
+ * ever asks, so there is no walk to report and nothing to disagree with.
+ *
+ * @param {object} [from] - Where to walk up from; both default to the real
+ *   thing, and are parameters only so a caller can describe a tree it is not
+ *   standing in.
+ * @param {string} [from.cwd] - The directory the build was launched in.
+ * @param {string} [from.moduleDir] - The directory this module sits in.
+ * @returns {{path: string|undefined, fromCwd: string|undefined, fromModule: string|undefined}}
+ *   The file to read, and each walk's own answer — the same file in an ordinary
+ *   build, different ones in a worktree resolving the toolchain out of its
+ *   parent checkout.
+ * @throws {Error} As {@link findConfigFile}, when one directory holds more than
+ *   one configuration.
+ */
+export function resolveConfigFile({ cwd, moduleDir }?: {
+    cwd?: string | undefined;
+    moduleDir?: string | undefined;
+}): {
+    path: string | undefined;
+    fromCwd: string | undefined;
+    fromModule: string | undefined;
+};
 /**
  * Attach the position of the key a configuration error names.
  *

package/types/engine/prose-config.d.mts

@@ -9,6 +9,47 @@
  *   `overrides`: passing that inline is what silently did nothing (#76).
  */
 export function sharedPrettierOptionsFor(file: string): object;
+/**
+ * Where a resolved Prettier configuration disagrees with the shared one.
+ *
+ * The runner resolves each file's options as *either* the consumer's own config
+ * or {@link sharedPrettierOptionsFor}, never a merge. That is what bare Prettier
+ * does and it is the contract — but it means the conventions this package exists
+ * to publish hold by convention alone, and they lapse in two opposite directions
+ * (#133). A consumer that declares any config of its own gets whatever that
+ * config says: spread {@link PRETTIER_BASE} without the markdown override and
+ * every note reindents at 4, the reindentation the override was added to prevent
+ * (#76); write a partial `.prettierrc` such as `{"tabWidth": 2}` and
+ * `printWidth`, `trailingComma`, `experimentalTernaries` and the rest fall back
+ * to Prettier's own defaults. A consumer that declares *nothing* formats one way
+ * under this command and another under a bare `npx prettier`.
+ *
+ * This is the comparison that makes either absence visible. It is a **report,
+ * not a merge**: what a consumer declared still wins, and a deliberate local
+ * choice stays possible — it stops being silent, and nothing here fails a build
+ * over it.
+ *
+ * Every shared value is a primitive, so `!==` is the whole comparison. An option
+ * holding an object would need a deeper one, and the shared set has none —
+ * `overrides` is not compared, because `resolveConfig` has already applied and
+ * removed it by the time a configuration reaches this.
+ *
+ * @param {object|null|undefined} resolved - What `prettier.resolveConfig`
+ *   returned for `file`, with the consumer's own `overrides` already applied.
+ *   `null` — no configuration at all — reports every shared key as absent.
+ * @param {string} file - Path the options were resolved for. Decides whether
+ *   {@link PRETTIER_MARKDOWN} is part of what is expected.
+ * @returns {Array<{key: string, shared: unknown, local: unknown}>} One entry per
+ *   shared key the resolved configuration does not carry the value of, in the
+ *   order {@link PRETTIER_BASE} declares them. `local` is `undefined` where the
+ *   key is absent entirely, which is not the same finding as a key set to
+ *   something else and is reported differently.
+ */
+export function sharedPrettierDivergence(resolved: object | null | undefined, file: string): Array<{
+    key: string;
+    shared: unknown;
+    local: unknown;
+}>;
 /**
  * The prose conventions every content repository writes to — one Prettier
  * configuration and one markdownlint rule set, declared here so a note

package/types/engine/prose-lint.d.mts

@@ -35,6 +35,42 @@ export function checkFormatting(root: string, opts?: {
     checked: number;
     written: string[];
 }>;
+/**
+ * Report where a repository's own Prettier configuration parts from the shared
+ * one — or that it has none at all (#133).
+ *
+ * **Warnings, every one of them.** A consumer's config wins by design and this
+ * does not change that; it only refuses to let the divergence be silent, which
+ * is the whole of what the issue asks for. Turning any of this into an error
+ * would make the shared conventions mandatory, and they are a default.
+ *
+ * The no-configuration case is the sharper one and is reported even though the
+ * command itself behaves correctly there: with no config file the shared
+ * conventions reach `content-build format` and reach *nothing else*, so an
+ * editor's format-on-save and a bare `npx prettier --check .` apply Prettier's
+ * own defaults to the same tree, and the two take turns rewriting the same
+ * lines. That is not hypothetical — it is what the config files in
+ * `sohl-thalorna` and `sohl-kethira-basic` were added to stop.
+ *
+ * @param {string} root - Repository to ask about.
+ * @param {object} [opts]
+ * @param {object} [opts.prettier] - The Prettier module, for tests.
+ * @returns {Promise<{findings: Array<{file?: string, severity: string,
+ *   message: string}>, configFile: string|null}>} The findings and the config
+ *   file they are about, which is `null` when the repository declares none. A
+ *   finding about a missing file carries no `file`: #17's rule is to drop a
+ *   field rather than invent one.
+ */
+export function checkPrettierConventions(root: string, opts?: {
+    prettier?: object | undefined;
+}): Promise<{
+    findings: Array<{
+        file?: string;
+        severity: string;
+        message: string;
+    }>;
+    configFile: string | null;
+}>;
 /**
  * Lint a repository's markdown against the shared rule set.
  *