@aljazmc/config 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aljazmc
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# > config
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 in `src/config.ts`. On run, `<package>.config.ts`
+(or `.js`) in the current directory, if present, overrides them key by key.
+
+```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",
+    ],
+};
+```
+
+`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.

package/bin/index.js

@@ -0,0 +1,210 @@
+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 { join } from "node:path";
+import { pathToFileURL } from "node:url";
+
+// shared/config/src/pattern.ts
+var Pattern = class _Pattern {
+  static {
+    __name(this, "Pattern");
+  }
+  #anchored;
+  #regex;
+  constructor(source) {
+    const glob = source.replace(/^\.?\/+|\/+$/g, "");
+    this.#anchored = glob.includes("/");
+    this.#regex = new RegExp(`^${_Pattern.#toRegex(glob)}$`);
+  }
+  matches(path) {
+    const segments = path.split("/");
+    return segments.some(
+      (segment, index) => this.#regex.test(
+        this.#anchored ? segments.slice(0, index + 1).join("/") : segment
+      )
+    );
+  }
+  /** Translates `**`, `*`, `?` and `{a,b}` alternatives, other characters match themselves. */
+  static #toRegex(glob) {
+    const tokens = {
+      "**/": "(?:.*/)?",
+      "**": ".*",
+      "*": "[^/]*",
+      "?": "[^/]"
+    };
+    let regex = "";
+    let braces = 0;
+    for (const [token] of glob.matchAll(/\*\*\/|\*\*|[\s\S]/g)) {
+      if (token in tokens) regex += tokens[token] ?? token;
+      else if (token === "{") {
+        braces++;
+        regex += "(?:";
+      } else if (token === "}" && braces > 0) {
+        braces--;
+        regex += ")";
+      } else if (token === "," && braces > 0) regex += "|";
+      else regex += token.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    }
+    return regex;
+  }
+};
+
+// shared/config/src/ignore.ts
+var Ignore = class {
+  static {
+    __name(this, "Ignore");
+  }
+  #patterns;
+  constructor(sources) {
+    this.#patterns = sources.map((source) => new Pattern(source));
+  }
+  matches(path) {
+    const normalized = path.replaceAll("\\", "/").replace(/^\.\//, "");
+    return this.#patterns.some((pattern) => pattern.matches(normalized));
+  }
+};
+
+// shared/config/src/config.ts
+var Config = class _Config {
+  static {
+    __name(this, "Config");
+  }
+  static extensions = ["ts", "js"];
+  root;
+  ignore;
+  rules;
+  /** What the config file set, before the defaults were merged in. */
+  custom;
+  constructor(options, root = process.cwd(), custom = {}) {
+    this.root = root;
+    this.ignore = new Ignore(options.ignore);
+    this.rules = options.rules;
+    this.custom = custom;
+  }
+  static async load(name, defaults, root = process.cwd()) {
+    for (const extension of _Config.extensions) {
+      const file = join(root, `${name}.config.${extension}`);
+      if (existsSync(file)) {
+        const { default: options } = await import(pathToFileURL(file).href);
+        return new _Config(
+          _Config.merge(defaults, options),
+          root,
+          options
+        );
+      }
+    }
+    return new _Config(defaults, root);
+  }
+  /** 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");
+    if (index === -1) return false;
+    const next = argv[index + 1];
+    const extension = next === void 0 || next.startsWith("-") ? "ts" : next;
+    try {
+      console.log(
+        `created: ${_Config.export(name, defaults, extension, root)}`
+      );
+    } catch (error) {
+      console.error(error instanceof Error ? error.message : error);
+      process.exitCode = 1;
+    }
+    return true;
+  }
+  /** Writes the defaults to `<name>.config.<extension>` in the root, unless a config file is there already. */
+  static export(name, defaults, extension = "ts", root = process.cwd()) {
+    if (!_Config.extensions.includes(extension))
+      throw new Error(
+        `Unknown config file type ${extension}, use ts or js.`
+      );
+    for (const existing of _Config.extensions) {
+      const file2 = `${name}.config.${existing}`;
+      if (existsSync(join(root, file2)))
+        throw new Error(`${file2} already exists.`);
+    }
+    const file = `${name}.config.${extension}`;
+    writeFileSync(
+      join(root, file),
+      `export default ${_Config.#literal(defaults)};
+`
+    );
+    return file;
+  }
+  /** A value as JavaScript source, objects one property per line, short arrays on one line. */
+  static #literal(value, indent = "") {
+    const inner = `${indent}    `;
+    const lines = /* @__PURE__ */ __name((items, open, close) => items.length === 0 ? `${open}${close}` : `${open}
+${items.map((item) => `${inner}${item},
+`).join("")}${indent}${close}`, "lines");
+    if (Array.isArray(value)) {
+      const items = value.map((item) => _Config.#literal(item, inner));
+      const line = `[${items.join(", ")}]`;
+      return line.length <= 60 && !line.includes("\n") ? line : lines(items, "[", "]");
+    }
+    if (value?.constructor === Object)
+      return lines(
+        Object.entries(value).map(
+          ([key, item]) => `${/^[A-Za-z_$][\w$]*$/.test(key) ? key : JSON.stringify(key)}: ${_Config.#literal(item, inner)}`
+        ),
+        "{",
+        "}"
+      );
+    return JSON.stringify(value);
+  }
+  /** Deep merges plain objects, anything else in override replaces base. */
+  static merge(base, override) {
+    const plain = /* @__PURE__ */ __name((value) => value?.constructor === Object, "plain");
+    if (!plain(base) || !plain(override)) return override ?? base;
+    const merged = { ...base };
+    for (const [key, value] of Object.entries(override))
+      merged[key] = _Config.merge(base[key], value);
+    return merged;
+  }
+  *files(directory = "") {
+    const entries = readdirSync(join(this.root, directory), {
+      withFileTypes: true
+    });
+    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;
+    }
+  }
+  /** Text files that are not ignored and that accepts takes, binaries are skipped. */
+  *sources(accepts = () => 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 };
+    }
+  }
+};
+
+// shared/config/src/includes.ts
+var Includes = class {
+  static {
+    __name(this, "Includes");
+  }
+  #globs;
+  constructor(globs) {
+    this.#globs = globs.map((glob) => ({
+      pattern: new Pattern(glob.replace(/^!/, "")),
+      included: !glob.startsWith("!")
+    }));
+  }
+  matches(file) {
+    let included = false;
+    for (const { pattern, included: positive } of this.#globs)
+      if (pattern.matches(file)) included = positive;
+    return included;
+  }
+};
+export {
+  Includes,
+  Pattern,
+  Config as default
+};

package/bin/types/config.d.ts

@@ -0,0 +1,31 @@
+import Ignore from "./ignore.js";
+export interface Options<Rules extends object = object> {
+    ignore: string[];
+    rules: Rules;
+}
+/** A text file found by a tool, with its path relative to the root. */
+export interface Source {
+    file: string;
+    path: string;
+    text: string;
+}
+export default class Config<Rules extends object = object> {
+    #private;
+    static readonly extensions: string[];
+    readonly root: string;
+    readonly ignore: Ignore;
+    readonly rules: Rules;
+    /** What the config file set, before the defaults were merged in. */
+    readonly custom: Partial<Options<Rules>>;
+    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. */
+    static init(name: string, defaults: Options, argv?: string[], root?: string): boolean;
+    /** Writes the defaults to `<name>.config.<extension>` in the root, unless a config file is there already. */
+    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;
+    files(directory?: string): Generator<string>;
+    /** Text files that are not ignored and that accepts takes, binaries are skipped. */
+    sources(accepts?: (file: string) => boolean): Generator<Source>;
+}

package/bin/types/ignore.d.ts

@@ -0,0 +1,5 @@
+export default class Ignore {
+    #private;
+    constructor(sources: readonly string[]);
+    matches(path: string): boolean;
+}

package/bin/types/includes.d.ts

@@ -0,0 +1,6 @@
+/** Biome style `includes`: globs in order, the last one matching a file decides, `!` excludes. */
+export default class Includes {
+    #private;
+    constructor(globs: readonly string[]);
+    matches(file: string): boolean;
+}

package/bin/types/index.d.ts

@@ -0,0 +1,4 @@
+export type { Options, Source } from "./config.js";
+export { default } from "./config.js";
+export { default as Includes } from "./includes.js";
+export { default as Pattern } from "./pattern.js";

package/bin/types/pattern.d.ts

@@ -0,0 +1,5 @@
+export default class Pattern {
+    #private;
+    constructor(source: string);
+    matches(path: string): boolean;
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@aljazmc/config",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.3.0",
+  "description": "Shared, dependency-free configuration loader, file finder and glob matcher for @aljazmc packages.",
+  "author": "aljazmc",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/aljazmc/aljazmc.git",
+    "directory": "shared/config"
+  },
+  "engines": {
+    "node": "^22.18.0 || ^24.2.0 || ^25 || ^26"
+  },
+  "types": "./bin/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./bin/types/index.d.ts",
+      "default": "./bin/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./bin/types/index.d.ts",
+        "default": "./bin/index.js"
+      },
+      "./package.json": "./package.json"
+    }
+  },
+  "devDependencies": {
+    "@jest/globals": "^30.5.2",
+    "@types/node": "^26.6.5"
+  }
 }