@intentius/chant 0.124.13 → 0.124.14

package/dist/discovery/specifier-resolve.js

@@ -0,0 +1,320 @@
+/**
+ * chant#3090 — the file-system half of fold's import resolution: which file a
+ * relative specifier names, which file a package's `exports` map names for a
+ * subpath, and which file a tsconfig `paths` entry names.
+ *
+ * The rules follow TypeScript's `bundler` resolution with `noDtsResolution`,
+ * the resolver `tsc` and the editor use for these specifiers:
+ *
+ * - `./x.js` names `./x.ts` (or `./x.tsx`) when that file exists, and the
+ *   `.js` file only otherwise. `.mjs` maps to `.mts`, `.cjs` to `.cts` and
+ *   `.jsx` to `.tsx` the same way.
+ * - A package's `exports` map is read for the root and for subpaths, with
+ *   one `*` per pattern key, and its condition objects are read in key order
+ *   against the `import`, `node` and `default` conditions, as an ESM import
+ *   in Node reads them.
+ * - A `paths` entry from the nearest `tsconfig.json` resolves relative to
+ *   `baseUrl` when the config chain sets one and to the directory of the
+ *   config that declares `paths` otherwise.
+ *
+ * Nothing here calls Node's `Module._resolveFilename`: every answer comes from
+ * `statSync` and `readFileSync`, which is what keeps the cold-resolution cost
+ * of chant#1020 off this path.
+ */
+import * as ts from "typescript";
+import { readFileSync, statSync } from "node:fs";
+import { dirname, extname, isAbsolute, join, resolve as resolvePath } from "node:path";
+/** True when `path` is an existing regular file. */
+export function isFile(path) {
+    try {
+        return statSync(path, { throwIfNoEntry: false })?.isFile() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/** True when `path` is an existing directory. */
+function isDirectory(path) {
+    try {
+        return statSync(path, { throwIfNoEntry: false })?.isDirectory() ?? false;
+    }
+    catch {
+        return false;
+    }
+}
+/** The TypeScript source extensions a JavaScript extension in a specifier stands for, in the order `tsc` tries them. */
+const TS_SOURCE_FOR_JS_EXTENSION = {
+    ".js": [".ts", ".tsx"],
+    ".jsx": [".tsx"],
+    ".mjs": [".mts"],
+    ".cjs": [".cts"],
+};
+/**
+ * The file an absolute module base path names, or `undefined` when none of
+ * the probed files exists. A JavaScript extension is first swapped for its
+ * TypeScript source extension. Then the path itself, the path with `.ts`,
+ * `.tsx`, `.js` and `.mjs` appended, and `index.ts` and `index.js` under it
+ * are tried in that order.
+ */
+export function probeModuleFile(base) {
+    const ext = extname(base);
+    const sourceExts = TS_SOURCE_FOR_JS_EXTENSION[ext];
+    if (sourceExts) {
+        const stem = base.slice(0, -ext.length);
+        for (const sourceExt of sourceExts) {
+            if (isFile(stem + sourceExt))
+                return stem + sourceExt;
+        }
+    }
+    const candidates = [
+        base,
+        `${base}.ts`,
+        `${base}.tsx`,
+        `${base}.js`,
+        `${base}.mjs`,
+        join(base, "index.ts"),
+        join(base, "index.js"),
+    ];
+    return candidates.find(isFile);
+}
+/** A bare specifier split into its package name and the subpath after it (`"."` for the root). */
+export function splitBareSpecifier(specifier) {
+    const segments = specifier.split("/");
+    const nameLength = specifier.startsWith("@") ? 2 : 1;
+    if (segments.length < nameLength || segments.slice(0, nameLength).some((s) => s === ""))
+        return undefined;
+    const name = segments.slice(0, nameLength).join("/");
+    const rest = segments.slice(nameLength).join("/");
+    return { name, subpath: rest === "" ? "." : `./${rest}` };
+}
+/** The conditions an ESM import in Node matches, which is what the run path does. */
+const EXPORT_CONDITIONS = new Set(["import", "node", "default"]);
+/**
+ * The target an `exports` value selects, with `star` substituted for each `*`
+ * when it came from a pattern key. A string is the target; an array yields its
+ * first resolvable entry; a condition object is read in key order and the
+ * first matching condition that resolves wins. `null`, and a condition object
+ * with no matching condition, resolve to nothing.
+ */
+function exportsValueTarget(value, star) {
+    if (typeof value === "string")
+        return star === undefined ? value : value.split("*").join(star);
+    if (Array.isArray(value)) {
+        for (const entry of value) {
+            const target = exportsValueTarget(entry, star);
+            if (target !== undefined)
+                return target;
+        }
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    for (const [condition, conditional] of Object.entries(value)) {
+        if (!EXPORT_CONDITIONS.has(condition))
+            continue;
+        const target = exportsValueTarget(conditional, star);
+        if (target !== undefined)
+            return target;
+    }
+    return undefined;
+}
+/**
+ * The target `exportsField` gives `subpath` (`"."` or `"./x"`), relative to
+ * the package directory, or `undefined` when the map does not export it. An
+ * exact key wins over a pattern; among patterns, the longest prefix before the
+ * `*` wins, as in Node's own resolver.
+ */
+export function packageExportsTarget(exportsField, subpath) {
+    const isSubpathMap = typeof exportsField === "object" &&
+        exportsField !== null &&
+        !Array.isArray(exportsField) &&
+        Object.keys(exportsField).some((k) => k.startsWith("."));
+    if (!isSubpathMap)
+        return subpath === "." ? exportsValueTarget(exportsField, undefined) : undefined;
+    const map = exportsField;
+    if (Object.prototype.hasOwnProperty.call(map, subpath) && !subpath.includes("*"))
+        return exportsValueTarget(map[subpath], undefined);
+    let bestKey;
+    let bestStar;
+    for (const key of Object.keys(map)) {
+        const starAt = key.indexOf("*");
+        if (starAt === -1 || key.indexOf("*", starAt + 1) !== -1)
+            continue;
+        const prefix = key.slice(0, starAt);
+        const suffix = key.slice(starAt + 1);
+        if (!subpath.startsWith(prefix) || subpath === prefix)
+            continue;
+        if (suffix !== "" && (!subpath.endsWith(suffix) || subpath.length < key.length))
+            continue;
+        if (bestKey === undefined || prefix.length > bestKey.indexOf("*") || (prefix.length === bestKey.indexOf("*") && key.length > bestKey.length)) {
+            bestKey = key;
+            bestStar = subpath.slice(prefix.length, subpath.length - suffix.length);
+        }
+    }
+    return bestKey === undefined ? undefined : exportsValueTarget(map[bestKey], bestStar);
+}
+/** Nearest `tsconfig.json` for a directory (`null` when there is none). */
+const nearestTsconfigCache = new Map();
+/** Parsed config chains by leaf config path, re-read when a file in the chain changes. */
+const tsconfigCache = new Map();
+function nearestTsconfig(dir) {
+    const cached = nearestTsconfigCache.get(dir);
+    if (cached !== undefined)
+        return cached;
+    const candidate = join(dir, "tsconfig.json");
+    let found;
+    if (isFile(candidate))
+        found = candidate;
+    else {
+        const parent = dirname(dir);
+        found = parent === dir ? null : nearestTsconfig(parent);
+    }
+    nearestTsconfigCache.set(dir, found);
+    return found;
+}
+function mtimeOf(path) {
+    try {
+        return statSync(path, { throwIfNoEntry: false })?.mtimeMs ?? -1;
+    }
+    catch {
+        return -1;
+    }
+}
+/** The config file an `extends` entry names, or `undefined` when it cannot be found. */
+function resolveExtends(entry, fromConfig) {
+    const fromDir = dirname(fromConfig);
+    if (entry.startsWith(".") || isAbsolute(entry)) {
+        const path = resolvePath(fromDir, entry);
+        if (isFile(path))
+            return path;
+        if (!path.endsWith(".json") && isFile(`${path}.json`))
+            return `${path}.json`;
+        return undefined;
+    }
+    // A package's config, looked up in `node_modules` the way `tsc` does for
+    // the common shapes: the file itself, the file plus `.json`, or the
+    // package directory's `tsconfig.json`.
+    for (let dir = fromDir;;) {
+        const path = join(dir, "node_modules", entry);
+        if (isFile(path))
+            return path;
+        if (!path.endsWith(".json") && isFile(`${path}.json`))
+            return `${path}.json`;
+        if (isDirectory(path) && isFile(join(path, "tsconfig.json")))
+            return join(path, "tsconfig.json");
+        const parent = dirname(dir);
+        if (parent === dir)
+            return undefined;
+        dir = parent;
+    }
+}
+/** Read `configPath` and everything it extends, later configs overriding earlier ones. */
+function readConfigChain(configPath, files, seen) {
+    if (seen.has(configPath))
+        return {};
+    seen.add(configPath);
+    files.push(configPath);
+    let text;
+    try {
+        text = readFileSync(configPath, "utf-8");
+    }
+    catch {
+        return {};
+    }
+    const { config } = ts.parseConfigFileTextToJson(configPath, text);
+    if (typeof config !== "object" || config === null)
+        return {};
+    const raw = config;
+    const merged = {};
+    const parents = typeof raw.extends === "string" ? [raw.extends] : Array.isArray(raw.extends) ? raw.extends : [];
+    for (const parent of parents) {
+        if (typeof parent !== "string")
+            continue;
+        const parentPath = resolveExtends(parent, configPath);
+        if (parentPath === undefined)
+            continue;
+        const inherited = readConfigChain(parentPath, files, seen);
+        if (inherited.paths)
+            merged.paths = inherited.paths;
+        if (inherited.baseUrl !== undefined)
+            merged.baseUrl = inherited.baseUrl;
+    }
+    const options = raw.compilerOptions;
+    if (options && typeof options.paths === "object" && options.paths !== null && !Array.isArray(options.paths)) {
+        merged.paths = { value: options.paths, declaredIn: dirname(configPath) };
+    }
+    if (options && typeof options.baseUrl === "string")
+        merged.baseUrl = resolvePath(dirname(configPath), options.baseUrl);
+    return merged;
+}
+function parsePaths(chain) {
+    if (!chain.paths)
+        return undefined;
+    const patterns = [];
+    for (const [key, value] of Object.entries(chain.paths.value)) {
+        if (!Array.isArray(value))
+            continue;
+        const substitutions = value.filter((s) => typeof s === "string");
+        const starAt = key.indexOf("*");
+        if (starAt !== -1 && key.indexOf("*", starAt + 1) !== -1)
+            continue;
+        patterns.push(starAt === -1
+            ? { key, prefix: key, suffix: undefined, substitutions }
+            : { key, prefix: key.slice(0, starAt), suffix: key.slice(starAt + 1), substitutions });
+    }
+    return { base: chain.baseUrl ?? chain.paths.declaredIn, patterns };
+}
+function tsconfigPathsFor(configPath) {
+    const cached = tsconfigCache.get(configPath);
+    if (cached && cached.stamps.every(([file, mtime]) => mtimeOf(file) === mtime))
+        return cached.paths;
+    const files = [];
+    const paths = parsePaths(readConfigChain(configPath, files, new Set()));
+    tsconfigCache.set(configPath, { stamps: files.map((f) => [f, mtimeOf(f)]), paths });
+    return paths;
+}
+/**
+ * The tsconfig `paths` entry that matches a bare `specifier` imported by
+ * `fromFile`, read from the nearest `tsconfig.json` above it, and the file it
+ * maps the specifier to (`target`, `undefined` when no substitution names an
+ * existing file). `undefined` when no entry matches. An exact key wins over a
+ * pattern, and among patterns the longest prefix wins, as in `tsc`.
+ * Substitutions are tried in order with {@link probeModuleFile}.
+ */
+export function tsconfigPathsMatch(specifier, fromFile) {
+    const configPath = nearestTsconfig(dirname(fromFile));
+    if (configPath === null)
+        return undefined;
+    const paths = tsconfigPathsFor(configPath);
+    if (!paths)
+        return undefined;
+    let best;
+    for (const pattern of paths.patterns) {
+        if (pattern.suffix === undefined) {
+            if (pattern.key === specifier) {
+                best = pattern;
+                break;
+            }
+            continue;
+        }
+        if (specifier.length >= pattern.prefix.length + pattern.suffix.length &&
+            specifier.startsWith(pattern.prefix) &&
+            specifier.endsWith(pattern.suffix) &&
+            (best === undefined || pattern.prefix.length > best.prefix.length)) {
+            best = pattern;
+        }
+    }
+    if (!best)
+        return undefined;
+    const star = best.suffix === undefined ? "" : specifier.slice(best.prefix.length, specifier.length - best.suffix.length);
+    for (const substitution of best.substitutions) {
+        const target = probeModuleFile(resolvePath(paths.base, substitution.split("*").join(star)));
+        if (target !== undefined)
+            return { key: best.key, target };
+    }
+    return { key: best.key, target: undefined };
+}
+/** The file {@link tsconfigPathsMatch} maps `specifier` to, or `undefined`. */
+export function tsconfigPathsTarget(specifier, fromFile) {
+    return tsconfigPathsMatch(specifier, fromFile)?.target;
+}

package/dist/discovery/walk.js

@@ -0,0 +1,284 @@
+/**
+ * The one discovery walk (chant#2527).
+ *
+ * Every command that decides which files chant reads walks the tree here:
+ * source discovery (`./files.ts`'s `findInfraFiles`, behind build, graph,
+ * list, explain and lexicon detection), `chant lint`, component discovery,
+ * Op discovery and the `chant audit` walk. They used to have five walkers
+ * with five sets of rules. v0.80.0 warned about every file whose status the
+ * convergence changes (#2571), and this module is that convergence. It is on
+ * #2525's level-0 exception list.
+ *
+ * The rules, for every walker:
+ *
+ * - `node_modules` and `.git` are never entered.
+ * - Dot-directories are skipped. The audit walk keeps `.github` and
+ *   `.forgejo`, which hold the CI files it audits.
+ * - `dist` is skipped.
+ * - Git-ignored paths are skipped, nested `.gitignore` files, `.git/info/exclude`
+ *   and the global excludes file included, the way git itself decides. Only
+ *   paths below the scan root are asked about: when the scan root is itself
+ *   ignored, nothing under it is dropped for being ignored, so building or
+ *   linting an ignored directory still reads it.
+ * - When the scan root is inside a chant project, a child directory holding a
+ *   project config is a boundary and is not entered. A `chant.config.json`
+ *   holding only lint keys is a fragment, not a project config, and is not a
+ *   boundary. A `chant.config.ts` always is one, since telling a lint-only one
+ *   apart would mean running it. When the scan root is outside every project,
+ *   every child project is read. Op discovery always stops at child projects
+ *   below its root.
+ * - The project's `exclude` globs (#2519) drop what they match, and its
+ *   `include` globs re-admit what `exclude` or any rule above would skip.
+ *   `node_modules`, `.git` and workspace members are the exceptions: include
+ *   never re-admits them.
+ * - Workspace members and group matches leave the root project's walk
+ *   (#2525 rule 3), and only when a workspace declaration exists. Without one nothing is loaded and
+ *   nothing is excluded; see {@link workspaceMemberDirs}.
+ *
+ * The walk is synchronous: the audit walk it replaced was, and the glob and
+ * ignore facts are gathered once before it starts.
+ */
+import { execFileSync } from "node:child_process";
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+// @ts-ignore — picomatch has no types declaration
+import picomatch from "picomatch";
+import { findProjectConfig, findWorkspaceRoot } from "../project-root.js";
+import { isLintOnlyFragment } from "../config.js";
+/** Dot-directories the audit walk enters anyway, since they hold the CI files it audits. */
+export const AUDIT_DOT_DIRS = new Set([".github", ".forgejo"]);
+/** Directories no rule and no glob ever lets the walk into. */
+const NEVER_ENTER = new Set(["node_modules", ".git"]);
+/** Path parts below `home`, or undefined for `home` itself or a path outside it. */
+function partsBelow(home, full) {
+    const rel = relative(home, resolve(full));
+    if (rel === "" || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return undefined;
+    return rel.split(sep);
+}
+function compileGlobs(globs) {
+    if (!globs || (globs.exclude.length === 0 && globs.include.length === 0))
+        return undefined;
+    const home = resolve(globs.root);
+    const matcher = (patterns) => {
+        if (patterns.length === 0)
+            return () => false;
+        const match = picomatch(patterns, { dot: true });
+        return (full) => {
+            const parts = partsBelow(home, full);
+            return parts !== undefined && parts.some((_, i) => match(parts.slice(0, i + 1).join("/")));
+        };
+    };
+    // The literal directory part of each include pattern: `.cache/keep/**`
+    // gives `.cache/keep`. The walk enters a skipped directory on the way to it.
+    const bases = globs.include.map((p) => picomatch.scan(p).base).filter((b) => b !== "");
+    return {
+        excluded: matcher(globs.exclude),
+        included: matcher(globs.include),
+        includeBelow: (full) => {
+            const parts = partsBelow(home, full);
+            if (parts === undefined)
+                return false;
+            const rel = parts.join("/");
+            return bases.some((b) => b.startsWith(`${rel}/`));
+        },
+    };
+}
+// ── Git ──────────────────────────────────────────────────────────────────────
+/**
+ * The untracked paths git ignores under `root`, absolute, with fully ignored
+ * directories listed once. One `git ls-files` call. A tree outside git, a
+ * missing `git`, or a root that is itself ignored yields an empty set: ignore
+ * rules are asked only about paths below the scan root.
+ */
+export function gitIgnoredBelow(root) {
+    let out;
+    try {
+        out = execFileSync("git", ["ls-files", "-z", "--others", "--ignored", "--exclude-standard", "--directory"], {
+            cwd: root,
+            encoding: "utf-8",
+            stdio: ["ignore", "pipe", "ignore"],
+            maxBuffer: 256 * 1024 * 1024,
+        });
+    }
+    catch {
+        return new Set();
+    }
+    const ignored = new Set();
+    const abs = resolve(root);
+    for (const entry of out.split("\0")) {
+        if (entry === "")
+            continue;
+        const rel = entry.endsWith("/") ? entry.slice(0, -1) : entry;
+        // `./` (or `.`): the scan root is itself ignored.
+        if (rel === "." || rel === "")
+            return new Set();
+        ignored.add(join(abs, rel));
+    }
+    return ignored;
+}
+// ── Boundaries ───────────────────────────────────────────────────────────────
+/** A directory that holds a project config: `chant.config.ts`, or a `chant.config.json` that is not a lint-only fragment. */
+export function isProjectBoundary(dir) {
+    if (existsSync(join(dir, "chant.config.ts")))
+        return true;
+    const json = join(dir, "chant.config.json");
+    return existsSync(json) && !isLintOnlyFragment(json);
+}
+/** Whether child projects end the walk from `root`: always for Ops, otherwise when `root` is inside a project. */
+export function childProjectsAreBoundaries(walker, root) {
+    return walker === "ops" || findProjectConfig(root).configPath !== undefined;
+}
+// ── Workspace members ────────────────────────────────────────────────────────
+/**
+ * The directories a workspace declaration moves out of the root project's
+ * discovery (#2525 rule 3), absolute and strictly below `root`, or none:
+ * every member's directory but the root's, and every group match
+ * (`rootExclusions` in `../workspace/declaration.ts`).
+ *
+ * Level 0 pays for `findWorkspaceRoot`, which only tests whether a
+ * `chant.workspace.json` or `.jsonc` exists from `root` up to the git root,
+ * and loads nothing. Only when a declaration is found are the workspace
+ * modules loaded to read it. A declaration that fails to read excludes
+ * nothing here; `chant workspace ls` is where its errors are reported. This
+ * is the only place discovery asks about workspaces; the walkers pass the
+ * result as `excludeDirs`.
+ */
+export async function workspaceMemberDirs(root) {
+    const found = findWorkspaceRoot(root);
+    if (!found)
+        return [];
+    const start = resolve(root);
+    const [{ readDeclaration, resolveGroups, rootExclusions }, { workingTree }] = await Promise.all([
+        import("../workspace/declaration.js"),
+        import("../workspace/tree.js"),
+    ]);
+    let dirs;
+    try {
+        const tree = workingTree(found.dir);
+        const declaration = readDeclaration(tree);
+        dirs = rootExclusions(declaration, resolveGroups(declaration, tree)).map((e) => resolve(found.dir, e.dir));
+    }
+    catch {
+        return [];
+    }
+    return dirs.filter((d) => partsBelow(start, d) !== undefined);
+}
+// ── Markers ──────────────────────────────────────────────────────────────────
+/** The first `bytes` of a file as UTF-8, or "" when it can't be read. */
+export function readHead(file, bytes) {
+    let fd;
+    try {
+        fd = openSync(file, "r");
+        const buf = Buffer.alloc(bytes);
+        const n = readSync(fd, buf, 0, bytes, 0);
+        return buf.toString("utf8", 0, n);
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== undefined)
+            closeSync(fd);
+    }
+}
+// ── The walk ─────────────────────────────────────────────────────────────────
+/** Walk `opts.root` under the rules in the module doc and return the files `accept` took. */
+export function walkDiscovery(opts) {
+    const out = [];
+    const globs = compileGlobs(opts.globs);
+    const ignored = gitIgnoredBelow(opts.root);
+    const boundaries = childProjectsAreBoundaries(opts.walker, opts.root);
+    const excludeDirs = new Set((opts.excludeDirs ?? []).map((d) => resolve(d)));
+    const dotDirsKept = opts.walker === "audit" ? AUDIT_DOT_DIRS : new Set();
+    const limit = opts.limit;
+    const isIgnored = (full) => ignored.size > 0 && ignored.has(resolve(full));
+    /** Take a path; false once the limit is reached. */
+    const take = (full) => {
+        if (limit && out.length >= limit.max) {
+            limit.truncated = true;
+            return false;
+        }
+        out.push(full);
+        return true;
+    };
+    const kind = (dir, e) => {
+        if (e.isDirectory())
+            return "dir";
+        if (e.isFile())
+            return "file";
+        if (opts.followSymlinks && e.isSymbolicLink()) {
+            try {
+                const s = statSync(join(dir, e.name));
+                return s.isDirectory() ? "dir" : s.isFile() ? "file" : undefined;
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return undefined;
+    };
+    /**
+     * Walk `dir`. `probing` is true below a directory a rule skipped that the
+     * walk entered only because an `include` pattern names something inside
+     * it: there, only what `include` matches is taken.
+     */
+    const walk = (dir, probing) => {
+        let entries;
+        try {
+            entries = readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return true;
+        }
+        if (opts.sorted)
+            entries.sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+        for (const e of entries) {
+            if (limit?.truncated)
+                return false;
+            const full = join(dir, e.name);
+            const type = kind(dir, e);
+            if (type === "dir") {
+                if (NEVER_ENTER.has(e.name) || excludeDirs.has(resolve(full)))
+                    continue;
+                const dotSkip = e.name.startsWith(".") && !dotDirsKept.has(e.name);
+                if (dotSkip && opts.takeSkippedDir?.(e.name, full)) {
+                    if (!take(full))
+                        return false;
+                    continue;
+                }
+                const ruleSkip = dotSkip ||
+                    e.name === "dist" ||
+                    (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+                    (boundaries && isProjectBoundary(full));
+                if (ruleSkip || probing) {
+                    if (globs?.included(full)) {
+                        if (!walk(full, false))
+                            return false;
+                    }
+                    else if (globs?.includeBelow(full)) {
+                        if (!walk(full, true))
+                            return false;
+                    }
+                    continue;
+                }
+                if (!walk(full, false))
+                    return false;
+            }
+            else if (type === "file") {
+                const skipped = probing ||
+                    (isIgnored(full) && !opts.keepIgnored?.(full)) ||
+                    (globs?.excluded(full) ?? false);
+                if (skipped && !globs?.included(full))
+                    continue;
+                if (!opts.accept(e.name, full))
+                    continue;
+                if (!take(full))
+                    return false;
+            }
+        }
+        return true;
+    };
+    walk(opts.root, false);
+    return out;
+}