@aljazmc/config 0.3.0 → 0.3.2

package/README.md

@@ -1,25 +1,49 @@
 # > config
 
-Shared, dependency-free configuration loader, file finder and glob matcher, bundled
-into every `@aljazmc` package and published for their types.
+Shared, dependency-free configuration loader, file finder and glob
+matcher, bundled into every `@aljazmc` package and published for their
+types. Each package ships its defaults, and `<package>.config.ts` (or
+`.js`) in the current directory overrides them key by key.
 
-Each package ships its defaults in `src/config.ts`. On run, `<package>.config.ts`
-(or `.js`) in the current directory, if present, overrides them key by key.
+## > Features
+
+| Export / member    | Description                                                     |
+| ------------------ | --------------------------------------------------------------- |
+| `config.custom`    | What the config file set, before the defaults were merged in.   |
+| `config.files()`   | Lists the files that are not ignored.                           |
+| `config.sources()` | Reads the text files that are not ignored.                      |
+| `Includes`         | Matches `includes` globs: the last match decides, `!` excludes. |
+| `Pattern`          | Matches a single glob.                                          |
+
+## > Ignore patterns
 
 ```js
 // testero.config.js
 export default {
     ignore: [
-        "node_modules", // name: any file or directory called node_modules
-        "packages/testero/tests", // path: relative to root, with its contents
-        "*.log", // globs: * and ? within a segment, ** across segments, {a,b} alternatives
-        "packages/*/bin",
         "**/tmp/*.ts",
+        "*.log",
+        "node_modules",
+        "packages/*/bin",
+        "packages/testero/tests",
     ],
 };
 ```
 
-`config.files()` lists the files that are not ignored, and `config.sources()`
-reads the text ones. `Includes` matches `includes` globs like formatero and lintero use them, where
-the last matching glob decides and `!` excludes. `config.custom` holds what the
-config file set, before the defaults were merged in.
+| Pattern  | Matches                                                 |
+| -------- | ------------------------------------------------------- |
+| `**`     | Any number of segments.                                 |
+| `*`, `?` | Any characters, or one character, within a segment.     |
+| `/name`  | `name` at the root only, like `./name`.                 |
+| `name/`  | Folders only, with their contents.                      |
+| `{a,b}`  | Alternatives.                                           |
+| name     | Any file or folder with that name, like `node_modules`. |
+| path     | A path relative to the root, with its contents.         |
+
+Symlinks are followed. Binary files are skipped. Broken symlinks,
+unreadable folders and files that are not UTF-8 are skipped with a
+warning.
+
+## > License
+
+MIT, see [LICENSE](LICENSE).

package/bin/index.js

@@ -2,7 +2,14 @@ var __defProp = Object.defineProperty;
 var __name = (target, value) => __defProp(target, "name", { value, configurable: true });
 
 // shared/config/src/config.ts
-import { existsSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
+import {
+  existsSync,
+  readdirSync,
+  readFileSync,
+  realpathSync,
+  statSync,
+  writeFileSync
+} from "node:fs";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 
@@ -12,22 +19,33 @@ var Pattern = class _Pattern {
     __name(this, "Pattern");
   }
   #anchored;
+  #directories;
   #regex;
-  constructor(source) {
+  /** With the name of the setting the glob comes from, for its errors. */
+  constructor(source, setting = "glob") {
+    this.#directories = /[^/]\/+$/.test(source);
     const glob = source.replace(/^\.?\/+|\/+$/g, "");
-    this.#anchored = glob.includes("/");
-    this.#regex = new RegExp(`^${_Pattern.#toRegex(glob)}$`);
+    this.#anchored = glob.includes("/") || /^\.?\//.test(source);
+    this.#regex = new RegExp(
+      `^${_Pattern.#toRegex(glob, source, setting)}$`
+    );
   }
-  matches(path) {
+  /**
+   * Whether a path, or a folder it is in, matches. Whether the path itself
+   * is a folder matters to globs ending with `/`.
+   */
+  matches(path, directory = false) {
     const segments = path.split("/");
-    return segments.some(
-      (segment, index) => this.#regex.test(
+    return segments.some((segment, index) => {
+      if (this.#directories && index === segments.length - 1 && !directory)
+        return false;
+      return this.#regex.test(
         this.#anchored ? segments.slice(0, index + 1).join("/") : segment
-      )
-    );
+      );
+    });
   }
   /** Translates `**`, `*`, `?` and `{a,b}` alternatives, other characters match themselves. */
-  static #toRegex(glob) {
+  static #toRegex(glob, source, setting) {
     const tokens = {
       "**/": "(?:.*/)?",
       "**": ".*",
@@ -37,7 +55,7 @@ var Pattern = class _Pattern {
     let regex = "";
     let braces = 0;
     for (const [token] of glob.matchAll(/\*\*\/|\*\*|[\s\S]/g)) {
-      if (token in tokens) regex += tokens[token] ?? token;
+      if (Object.hasOwn(tokens, token)) regex += tokens[token];
       else if (token === "{") {
         braces++;
         regex += "(?:";
@@ -47,6 +65,10 @@ var Pattern = class _Pattern {
       } else if (token === "," && braces > 0) regex += "|";
       else regex += token.replace(/[.+^${}()|[\]\\]/g, "\\$&");
     }
+    if (braces > 0)
+      throw new Error(
+        `Invalid ${setting} ${JSON.stringify(source)}: a { is not closed by a }.`
+      );
     return regex;
   }
 };
@@ -58,11 +80,14 @@ var Ignore = class {
   }
   #patterns;
   constructor(sources) {
-    this.#patterns = sources.map((source) => new Pattern(source));
+    this.#patterns = sources.map((source) => new Pattern(source, "ignore"));
   }
-  matches(path) {
+  /** Whether a path is ignored, globs ending with `/` only ignore folders. */
+  matches(path, directory = false) {
     const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
-    return this.#patterns.some((pattern) => pattern.matches(normalized));
+    return this.#patterns.some(
+      (pattern) => pattern.matches(normalized, directory)
+    );
   }
 };
 
@@ -77,6 +102,11 @@ var Config = class _Config {
   rules;
   /** What the config file set, before the defaults were merged in. */
   custom;
+  /**
+   * Reports files and folders that are left out, like a broken symlink, an
+   * unreadable folder or a file that is not UTF-8, as a warning by default.
+   */
+  warn = /* @__PURE__ */ __name((message) => console.log(`warn: ${message}`), "warn");
   constructor(options, root = process.cwd(), custom = {}) {
     this.root = root;
     this.ignore = new Ignore(options.ignore);
@@ -88,6 +118,7 @@ var Config = class _Config {
       const file = join(root, `${name}.config.${extension}`);
       if (existsSync(file)) {
         const { default: options } = await import(pathToFileURL(file).href);
+        _Config.#check(`${name}.config.${extension}`, options);
         return new _Config(
           _Config.merge(defaults, options),
           root,
@@ -97,12 +128,26 @@ var Config = class _Config {
     }
     return new _Config(defaults, root);
   }
+  /** Fails clearly on a config file that does not export the shape of the defaults. */
+  static #check(file, options) {
+    if (options === void 0) return;
+    if (options?.constructor !== Object)
+      throw new Error(
+        `${file} must export default an object, like { ignore: [], rules: {} }, not ${Array.isArray(options) ? "an array" : typeof options}.`
+      );
+    const { ignore } = options;
+    if (ignore !== void 0 && !(Array.isArray(ignore) && ignore.every((item) => typeof item === "string")))
+      throw new Error(`${file}: ignore must be a list of strings.`);
+  }
   /** Handles `--config`, writing the defaults to a TypeScript config file, or with `--config js` a JavaScript one. Returns whether it was given. */
   static init(name, defaults, argv = process.argv.slice(2), root = process.cwd()) {
-    const index = argv.indexOf("--config");
+    const index = argv.findIndex(
+      (arg) => arg === "--config" || arg.startsWith("--config=")
+    );
     if (index === -1) return false;
-    const next = argv[index + 1];
-    const extension = next === void 0 || next.startsWith("-") ? "ts" : next;
+    const [, inline] = argv[index].split(/=(.*)/s);
+    const next = inline ?? argv[index + 1];
+    const extension = next === void 0 || next === "" || next.startsWith("-") ? "ts" : next;
     try {
       console.log(
         `created: ${_Config.export(name, defaults, extension, root)}`
@@ -162,24 +207,93 @@ ${items.map((item) => `${inner}${item},
       merged[key] = _Config.merge(base[key], value);
     return merged;
   }
+  /**
+   * The files that are not ignored, relative to the root. Symlinks are
+   * followed, a folder by every path to it, but not into a folder it is in,
+   * which would never end; broken symlinks and unreadable folders are
+   * reported and left out, like pipes and other special files.
+   */
   *files(directory = "") {
-    const entries = readdirSync(join(this.root, directory), {
-      withFileTypes: true
-    });
+    yield* this.#walk(directory, /* @__PURE__ */ new Set());
+  }
+  *#walk(directory, ancestors) {
+    const absolute = join(this.root, directory);
+    let entries;
+    let real;
+    try {
+      real = realpathSync(absolute);
+      if (ancestors.has(real)) return;
+      entries = readdirSync(absolute, { withFileTypes: true });
+    } catch (error) {
+      this.warn(
+        `${directory || "."}: the folder cannot be read (${_Config.#reason(error)}), left out.`
+      );
+      return;
+    }
+    ancestors.add(real);
     for (const entry of entries) {
       const path = directory ? `${directory}/${entry.name}` : entry.name;
-      if (this.ignore.matches(path)) continue;
-      if (entry.isDirectory()) yield* this.files(path);
-      else yield path;
+      let kind = entry.isDirectory() ? "directory" : entry.isFile() ? "file" : "other";
+      if (entry.isSymbolicLink())
+        try {
+          const target = statSync(join(this.root, path));
+          kind = target.isDirectory() ? "directory" : target.isFile() ? "file" : "other";
+        } catch (error) {
+          if (!this.ignore.matches(path))
+            this.warn(
+              `${path}: a broken symlink (${_Config.#reason(error)}), left out.`
+            );
+          continue;
+        }
+      if (this.ignore.matches(path, kind === "directory")) continue;
+      if (kind === "directory") yield* this.#walk(path, ancestors);
+      else if (kind === "file") yield path;
     }
+    ancestors.delete(real);
   }
-  /** Text files that are not ignored and that accepts takes, binaries are skipped. */
+  /**
+   * Text files that are not ignored and that accepts takes. Binaries, with
+   * a NUL byte, are skipped; files that are not UTF-8 are reported and
+   * skipped, as writing them back as UTF-8 would change their text.
+   */
   *sources(accepts = () => true) {
+    const utf8 = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
     for (const file of this.files()) {
       if (!accepts(file)) continue;
       const path = join(this.root, file);
-      const text = readFileSync(path, "utf8");
-      if (!text.includes("\0")) yield { file, path, text };
+      let bytes;
+      try {
+        bytes = readFileSync(path);
+      } catch (error) {
+        this.warn(
+          `${file}: the file cannot be read (${_Config.#reason(error)}), left out.`
+        );
+        continue;
+      }
+      if (bytes.includes(0)) continue;
+      let text;
+      try {
+        text = utf8.decode(bytes);
+      } catch {
+        this.warn(`${file}: not UTF-8, left out.`);
+        continue;
+      }
+      yield { file, path, text };
+    }
+  }
+  /** Why a file system call failed, in words. */
+  static #reason(error) {
+    const code = error?.code;
+    switch (code) {
+      case "ENOENT":
+        return "its target does not exist";
+      case "EACCES":
+      case "EPERM":
+        return "no permission";
+      case "ELOOP":
+        return "a loop of symlinks";
+      default:
+        return error instanceof Error ? error.message : String(error);
     }
   }
 };
@@ -190,9 +304,10 @@ var Includes = class {
     __name(this, "Includes");
   }
   #globs;
-  constructor(globs) {
+  /** With the name of the setting the globs come from, for their errors. */
+  constructor(globs, setting = "includes") {
     this.#globs = globs.map((glob) => ({
-      pattern: new Pattern(glob.replace(/^!/, "")),
+      pattern: new Pattern(glob.replace(/^!/, ""), setting),
       included: !glob.startsWith("!")
     }));
   }

package/bin/types/config.d.ts

@@ -17,6 +17,11 @@ export default class Config<Rules extends object = object> {
     readonly rules: Rules;
     /** What the config file set, before the defaults were merged in. */
     readonly custom: Partial<Options<Rules>>;
+    /**
+     * Reports files and folders that are left out, like a broken symlink, an
+     * unreadable folder or a file that is not UTF-8, as a warning by default.
+     */
+    warn: (message: string) => void;
     constructor(options: Options<Rules>, root?: string, custom?: Partial<Options<Rules>>);
     static load<Rules extends object>(name: string, defaults: Options<Rules>, root?: string): Promise<Config<Rules>>;
     /** Handles `--config`, writing the defaults to a TypeScript config file, or with `--config js` a JavaScript one. Returns whether it was given. */
@@ -25,7 +30,17 @@ export default class Config<Rules extends object = object> {
     static export(name: string, defaults: Options, extension?: string, root?: string): string;
     /** Deep merges plain objects, anything else in override replaces base. */
     static merge<T>(base: T, override: unknown): T;
+    /**
+     * The files that are not ignored, relative to the root. Symlinks are
+     * followed, a folder by every path to it, but not into a folder it is in,
+     * which would never end; broken symlinks and unreadable folders are
+     * reported and left out, like pipes and other special files.
+     */
     files(directory?: string): Generator<string>;
-    /** Text files that are not ignored and that accepts takes, binaries are skipped. */
+    /**
+     * Text files that are not ignored and that accepts takes. Binaries, with
+     * a NUL byte, are skipped; files that are not UTF-8 are reported and
+     * skipped, as writing them back as UTF-8 would change their text.
+     */
     sources(accepts?: (file: string) => boolean): Generator<Source>;
 }

package/bin/types/ignore.d.ts

@@ -1,5 +1,6 @@
 export default class Ignore {
     #private;
     constructor(sources: readonly string[]);
-    matches(path: string): boolean;
+    /** Whether a path is ignored, globs ending with `/` only ignore folders. */
+    matches(path: string, directory?: boolean): boolean;
 }

package/bin/types/includes.d.ts

@@ -1,6 +1,7 @@
-/** Biome style `includes`: globs in order, the last one matching a file decides, `!` excludes. */
+/** `includes`: globs in order, the last one matching a file decides, `!` excludes. */
 export default class Includes {
     #private;
-    constructor(globs: readonly string[]);
+    /** With the name of the setting the globs come from, for their errors. */
+    constructor(globs: readonly string[], setting?: string);
     matches(file: string): boolean;
 }

package/bin/types/pattern.d.ts

@@ -1,5 +1,16 @@
+/**
+ * A glob of paths relative to the root, like `.gitignore`'s: one without a
+ * `/` matches a file or folder of that name anywhere, one with a `/` a path
+ * from the root, also when it starts with `/` or `./`, and one that ends
+ * with `/` only folders. A folder that matches also matches its contents.
+ */
 export default class Pattern {
     #private;
-    constructor(source: string);
-    matches(path: string): boolean;
+    /** With the name of the setting the glob comes from, for its errors. */
+    constructor(source: string, setting?: string);
+    /**
+     * Whether a path, or a folder it is in, matches. Whether the path itself
+     * is a folder matters to globs ending with `/`.
+     */
+    matches(path: string, directory?: boolean): boolean;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aljazmc/config",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Shared, dependency-free configuration loader, file finder and glob matcher for @aljazmc packages.",
   "author": "aljazmc",
   "license": "MIT",
@@ -31,7 +31,6 @@
     }
   },
   "devDependencies": {
-    "@jest/globals": "^30.5.2",
-    "@types/node": "^26.6.5"
+    "@types/node": "^26.6.6"
   }
 }