@ecoma-io/archkeep 0.13.0

package/src/custom-rules/values.mjs

@@ -0,0 +1,43 @@
+/**
+ * The three questions every refusal in this layer asks of a value: is it a
+ * plain object, is it a string with something in it, and — for the sentence
+ * that refuses it — what was it actually.
+ *
+ * **They live here because the first two copies had already drifted.**
+ * `./evidence.mjs` and `./host.mjs` each grew their own `describeValue`, and
+ * by the time anyone compared them they rendered the same value two ways:
+ * `string "x"` in one, `string ("x")` in the other. Neither was wrong, which
+ * is exactly the problem — two refusals about the same shape read as though
+ * they came from two different tools, and a reader holding a load failure
+ * beside a bundle failure has no way to tell that the difference means
+ * nothing. The BigInt guard is the other half of the warning: it was written
+ * into both copies by hand, in one sitting, and the next fix would have landed
+ * in only one of them.
+ *
+ * The rendering is fixed here and nowhere else: `an array of N`, `null`,
+ * `undefined`, and otherwise the value's type followed by its JSON.
+ */
+
+/** @type {(value: unknown) => value is Record<string, any>} */
+export const isPlainObject = (value) =>
+  value !== null && typeof value === "object" && !Array.isArray(value);
+
+/** @type {(value: unknown) => boolean} */
+export const isNonEmptyString = (value) => typeof value === "string" && value.trim() !== "";
+
+/**
+ * A value's type, for a refusal that shows what was actually there.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function describeValue(value) {
+  if (Array.isArray(value)) return `an array of ${value.length}`;
+  if (value === null) return "null";
+  if (value === undefined) return "undefined";
+  // A BigInt is the one value `JSON.stringify` THROWS on rather than skipping,
+  // and this runs only on a refusal path — a formatter that threw would
+  // replace the named reason with a TypeError about something else entirely.
+  if (typeof value === "bigint") return `bigint ${value}`;
+  return `${typeof value} ${JSON.stringify(value) ?? String(value)}`;
+}

package/src/entry-point.mjs

@@ -0,0 +1,55 @@
+/**
+ * "Was this module run as a program, or imported?" — the one question both
+ * executables ask, and the one they were both getting wrong once installed.
+ *
+ * The idiom this replaces compares `process.argv[1]` to `import.meta.url` as
+ * URLs. Those two strings are produced differently: Node resolves symlinks
+ * before it records a module's URL, and records `argv[1]` exactly as the caller
+ * spelled it. Run the file by a path that goes through a symlink and the
+ * comparison is false — the module loads, defines everything, runs nothing, and
+ * the process exits 0.
+ *
+ * That is not a hypothetical spelling. pnpm's layout IS a symlink:
+ * `node_modules/@scope/pkg` points into `node_modules/.pnpm/…`, so an installed
+ * consumer launching `node node_modules/@scope/pkg/lsp.mjs` hits it every time.
+ * Measured on a real `pnpm pack` + install: the language server answered an
+ * `initialize` frame with no bytes on stdout, none on stderr, and exit 0. The
+ * generated bin shim happens to `exec` the resolved path, which is why the CLI
+ * looked fine through `pnpm exec` while the editor path — Claude Code launches
+ * `${CLAUDE_PLUGIN_ROOT}/lsp.mjs` by path, with no shim in between — did not.
+ *
+ * Exit 0 and silence is the exact failure this project is built to refuse (a
+ * server that published nothing is read as "checked, clean"), so the comparison
+ * is made on real paths, where both spellings of the same file agree.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+
+/**
+ * Resolves a path through symlinks, falling back to the path itself.
+ *
+ * A path that cannot be resolved — deleted between spawn and this call, or a
+ * dangling link — is compared verbatim rather than throwing. Getting the answer
+ * wrong there means an executable does not run; throwing means it crashes with
+ * a stack trace naming a file the caller did not ask about.
+ */
+function realOrGiven(path) {
+  try {
+    return realpathSync(path);
+  } catch {
+    return path;
+  }
+}
+
+/**
+ * True when `moduleUrl` names the file Node was told to run.
+ *
+ * @param {string} moduleUrl `import.meta.url` of the calling module.
+ * @param {string | undefined} [argv1] The invoked path; defaults to `process.argv[1]`,
+ *   which is absent when Node is run with `-e` or as a REPL — imported, not run.
+ * @returns {boolean}
+ */
+export function isProgramEntry(moduleUrl, argv1 = process.argv[1]) {
+  if (!argv1) return false;
+  return realOrGiven(argv1) === realOrGiven(fileURLToPath(moduleUrl));
+}

package/src/errors.mjs

@@ -0,0 +1,36 @@
+/**
+ * The typed error `cli.mjs`'s exit-code classification keys on.
+ *
+ * Which caught errors mean "the caller's argument is wrong" (exit 2) and
+ * which mean "the run could not look" (exit 3) used to be decided by testing
+ * `error.message` against a regex at every catch site in `../cli.mjs`. Prose
+ * is not a contract: rewording a message flipped an exit code with nothing
+ * failing anywhere — the stderr text still named the mistake, so only the
+ * verdict moved, and no gate watched that line. The throw sites now carry
+ * the decision as a class and the catch sites test `instanceof`, so a
+ * message can be reworded without moving an exit code.
+ *
+ * `UsageError` covers exactly the refusals those regexes matched: a path
+ * outside the workspace or matching no tracked file (`./workspace.mjs`'s
+ * `selectFiles`), an unknown project name (`./commands/impact.mjs`'s
+ * `computeImpact`, `./commands/context-command.mjs`'s
+ * `collectProjectContext`), and a malformed `file:line:column` site string
+ * (`./commands/explain.mjs`'s `parseSite`). They are one mistake in four
+ * spellings — retyping the argument is the fix, which is what separates
+ * them from every other failure a run can hit; a run that never reached a
+ * verdict throws a plain `Error` and stays exit 3, so "could not look" is
+ * never mistaken for "looked and found the caller at fault"
+ * (`../AGENTS.md`, check's four exit codes).
+ *
+ * One class, nothing else exported: a second class needs a catch site that
+ * treats two of these mistakes differently, and none does.
+ */
+export class UsageError extends Error {
+  /**
+   * @param {string} message Printed verbatim on stderr; tests pin it.
+   */
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}