asljs-locator 0.0.0-stage → 0.1.2

package/LICENSE.md

@@ -0,0 +1,51 @@
+# Permissive No-Derivatives License 1.0
+
+Copyright (c) 2026 Alexandrite Software Ltd.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of
+this software (the "Software") to:
+
+1. Use the Software for any purpose, including commercial purposes.
+2. Copy and redistribute the Software, including as part of another application,
+   library, or package.
+3. Modify the Software for private or internal use.
+
+Subject to the following conditions:
+
+## 1. No Distribution of Modified Versions
+
+Modified versions of the Software, or substantial portions thereof, must not be
+distributed without prior written permission from the copyright holder.
+
+Routine build transformations, including minification, transpilation, and
+bundling, are permitted for distribution, provided they do not intentionally
+alter the Software's functionality.
+
+## 2. Licence and Copyright Preservation
+
+All distributed copies of the Software must retain this copyright notice and
+licence.
+
+The Software itself, including copies incorporated into other applications,
+libraries, or packages, remains subject to this licence.
+
+The Software must not be sublicensed or redistributed under a different licence.
+
+## 3. Use in Other Software
+
+Applications and libraries that merely use, import, link to, or bundle the
+Software are not considered modified versions of the Software and may be
+distributed under any licence.
+
+Such use, incorporation, or bundling does not grant permission to relicense the
+Software or distribute modified versions of it.
+
+### 4. No Warranty
+
+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 COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR ITS
+USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -1,3 +1,100 @@
-# Temporary Holding Version
+# locator
 
-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.
+> Part of [Alexandrite Software Library][1] – a set of high‑quality, performant
+> JavaScript libraries for everyday use.
+
+## Overview
+
+`asljs-locator` locates files by glob patterns, exclusions and filters such as
+`.gitignore`.
+
+A location says where a set of files lives: the patterns that match them, the
+patterns that take them away again, and the filters that drop whatever should
+never have been listed. `.gitignore` is one of those filters, so a tool can
+honour it without reimplementing it.
+
+A pattern beginning with `/` resolves against the root the resolver was built
+with. Any other pattern resolves against the base path given to the call. That
+pair is what lets one vocabulary describe both a repository-wide location and a
+location relative to the file that declared it.
+
+An absolute path is a pattern where it is, inside the root or not:
+`C:/notes/*.md` always, and `/tmp/notes/*.md` when the root has no `tmp` and the
+file system root has one. A pattern beginning with `/` whose first segment the
+root has, or which begins with a glob, such as `/docs/**` or `/**/*.md`, stays
+from the root.
+
+## Scope
+
+Finding paths, and answering whether a path belongs to a location. Reading the
+files it finds is the caller's business.
+
+## Installation
+
+```bash
+npm install asljs-locator
+```
+
+NPM Package: [asljs-locator][NPM]
+
+## Usage
+
+```js
+import {
+  LocationResolver
+} from 'asljs-locator';
+import {
+  NullLogger
+} from 'asljs-logging';
+
+const resolver = new LocationResolver(new NullLogger(), process.cwd());
+
+const files = await resolver.resolve(process.cwd(), {
+  patterns: ['docs/**/*.md'],
+  exclude: ['docs/drafts/**'],
+  filters: [{ name: 'GitIgnore' }]
+});
+```
+
+`resolve` returns absolute paths, deduplicated and sorted. Give it one location
+or several; several are merged.
+
+`check` answers the same question for a single path without walking the tree,
+which is what makes it usable per file:
+
+```js
+const belongs = await resolver.check(
+  '/repo/docs/guide.md',
+  '/repo',
+  { pattern: 'docs/**/*.md' }
+);
+```
+
+Patterns match files only. A pattern ending with `/` would name folders and
+throws; to treat a folder as an item, point at a file inside it, e.g.
+`packages/*/package.json`.
+
+Two path helpers come with it: `toPosixPath(path)`, the path with forward
+slashes, and `isInside(folder, target, { orSame? })`, whether `target` is
+`folder` or below it; with `orSame: false`, only below it.
+
+## Further reading
+
+- [Architecture][2] for where this sits among the packages.
+
+Questions and bugs: [asljs/issues][ISS].
+
+## Related packages
+
+- [asljs-logging][3] provides the logger the resolver traces through.
+
+## License
+
+MIT License. See [LICENSE][LIC] for details.
+
+[1]: https://github.com/AlexandriteSoftware/asljs
+[2]: ../../docs/Architecture.md
+[3]: ../logging/README.md
+[ISS]: https://github.com/AlexandriteSoftware/asljs/issues
+[LIC]: LICENSE.md
+[NPM]: https://www.npmjs.com/package/asljs-locator

package/dist/git-ignore.d.ts

@@ -0,0 +1,17 @@
+import { Logger } from 'asljs-logging';
+/**
+ * Whether a path is ignored by a `.gitignore`.
+ *
+ * Matchers are loaded from the directory of the path being tested and every
+ * directory above it, because a nested `.gitignore` applies to its own subtree
+ * and git reads them all. Each directory is read once.
+ */
+export declare class GitIgnore {
+    private logger;
+    private matchers;
+    private visitedPaths;
+    constructor(logger: Logger);
+    isIgnored(targetPath: string): boolean;
+    filter(paths: string[]): string[];
+    loadMatchers(directoryPath: string): void;
+}

package/dist/git-ignore.js

@@ -0,0 +1,81 @@
+import ignore from 'ignore';
+import { readFileSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { toPosixPath } from './paths.js';
+/**
+ * Whether a path is ignored by a `.gitignore`.
+ *
+ * Matchers are loaded from the directory of the path being tested and every
+ * directory above it, because a nested `.gitignore` applies to its own subtree
+ * and git reads them all. Each directory is read once.
+ */
+export class GitIgnore {
+    logger;
+    matchers;
+    visitedPaths;
+    constructor(logger) {
+        this.logger = logger;
+        this.matchers = [];
+        this.visitedPaths = new Set();
+    }
+    isIgnored(targetPath) {
+        if (!path.isAbsolute(targetPath)) {
+            throw new Error(`Path must be absolute: ${targetPath}`);
+        }
+        const isDirectory = targetPath.endsWith(path.sep);
+        const normalisedPath = path.normalize(targetPath);
+        if (isDirectory) {
+            this.loadMatchers(normalisedPath);
+        }
+        else {
+            this.loadMatchers(path.dirname(normalisedPath));
+        }
+        for (const matcher of this.matchers) {
+            const relativePath = toPosixPath(path.relative(matcher.path, normalisedPath));
+            if (relativePath === ''
+                || relativePath.startsWith('../')) {
+                continue;
+            }
+            const testRelativePath = isDirectory
+                ? relativePath + '/'
+                : relativePath;
+            if (matcher.matcher.ignores(testRelativePath)) {
+                return true;
+            }
+        }
+        return false;
+    }
+    filter(paths) {
+        return paths.filter(filePath => !this.isIgnored(filePath));
+    }
+    loadMatchers(directoryPath) {
+        if (this.visitedPaths.has(directoryPath)) {
+            return;
+        }
+        this.visitedPaths
+            .add(directoryPath);
+        const gitIgnorePath = path.join(directoryPath, '.gitignore');
+        let gitIgnoreExists = false;
+        try {
+            statSync(gitIgnorePath);
+            gitIgnoreExists = true;
+        }
+        catch (err) {
+            const code = err.code;
+            if (code !== 'ENOENT') {
+                throw err;
+            }
+        }
+        if (gitIgnoreExists) {
+            const gitIgnoreContent = readFileSync(gitIgnorePath, 'utf8');
+            const matcher = ignore()
+                .add(gitIgnoreContent);
+            this.matchers.push({ path: directoryPath,
+                matcher });
+        }
+        const parentPath = path.dirname(directoryPath);
+        if (parentPath !== directoryPath) {
+            this.loadMatchers(parentPath);
+        }
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { GitIgnore } from './git-ignore.js';
+export { LocationResolver, toPatterns, type Location, type LocationFilter } from './location.js';
+export { isInside, toPosixPath } from './paths.js';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { GitIgnore } from './git-ignore.js';
+export { LocationResolver, toPatterns } from './location.js';
+export { isInside, toPosixPath } from './paths.js';

package/dist/location.d.ts

@@ -0,0 +1,71 @@
+import { type Logger } from 'asljs-logging';
+/**
+ * A named filter applied to the matches, rather than a pattern.
+ *
+ * `GitIgnore` is the only one implemented: it drops whatever git would ignore.
+ */
+export interface LocationFilter {
+    name: string;
+}
+/**
+ * Where a set of files lives.
+ *
+ * A pattern beginning with `/` is resolved against the root the resolver was
+ * built with; any other pattern is resolved against the base path passed to
+ * the call. That is what lets a definition name a repository-wide location and
+ * a location relative to itself in the same vocabulary.
+ *
+ * Give either `pattern` for one or `patterns` for several; both are accepted
+ * and read as one list.
+ */
+export interface Location {
+    pattern?: string;
+    patterns?: string[];
+    exclude?: string[];
+    filters?: LocationFilter[];
+}
+/** The patterns of a location, however they were given. */
+export declare function toPatterns(location: Location): string[];
+export declare class LocationResolver {
+    private logger;
+    private rootPath;
+    private gitIgnore;
+    constructor(logger: Logger, rootPath: string);
+    /**
+     * Every path the locations match, deduplicated and sorted.
+     */
+    resolve(basePath: string, location: Location | readonly Location[]): Promise<string[]>;
+    /**
+     * Whether the target path belongs to any of the locations.
+     *
+     * This answers the question without walking the filesystem, which is what
+     * makes it usable per file.
+     */
+    check(targetPath: string, basePath: string, location: Location | readonly Location[]): Promise<boolean>;
+    private resolveOne;
+    private checkOne;
+    /**
+     * How a pattern resolves: `absolute`, a path of the file system, such as
+     * `/tmp/notes/*.md` or `C:/notes/*.md`; `root`, from the root, such as
+     * `/docs/**`; or `base`, from the base path.
+     *
+     * A pattern beginning with `/` is from the root, unless its first segment
+     * is no glob, the root has no entry of that name, and the file system root
+     * has one: `/tmp/x.md`, given under a root without a `tmp`, names the file
+     * where it is.
+     */
+    private kindOf;
+    /**
+     * The absolute paths the patterns match.
+     *
+     * An absolute pattern is expanded where it is, one beginning with `/` from
+     * the root, the rest from the base path, so one call can carry every kind;
+     * see `kindOf`.
+     *
+     * Dotfiles are matched, because `check` matches them and the two have to
+     * agree: without it a path such as `.remarkrc.mjs` would be reported as
+     * belonging to a location that never finds it.
+     */
+    private expand;
+    private applyFilters;
+}

package/dist/location.js

@@ -0,0 +1,205 @@
+import { glob } from 'glob';
+import { minimatch } from 'minimatch';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { GitIgnore } from './git-ignore.js';
+import { toPosixPath } from './paths.js';
+/** The patterns of a location, however they were given. */
+export function toPatterns(location) {
+    const patterns = [...location.pattern === undefined
+            ? []
+            : [location.pattern],
+        ...location.patterns
+            ?? []];
+    if (patterns.length === 0) {
+        throw new Error('A location needs a pattern or patterns.');
+    }
+    return patterns;
+}
+/**
+ * Patterns match files only. A pattern ending with `/` would name folders,
+ * which `resolve` and `check` cannot treat alike, so it is refused.
+ */
+function assertFilePatterns(patterns) {
+    const folderPattern = patterns.find(pattern => pattern.endsWith('/'));
+    if (folderPattern !== undefined) {
+        throw new Error(`Folder patterns are not supported: "${folderPattern}". Point the pattern at a file, e.g. "${folderPattern}package.json".`);
+    }
+}
+function toLocations(location) {
+    return Array.isArray(location)
+        ? location
+        : [location];
+}
+export class LocationResolver {
+    logger;
+    rootPath;
+    gitIgnore;
+    constructor(logger, rootPath) {
+        this.logger = logger;
+        this.rootPath =
+            path.normalize(path.resolve(rootPath));
+        this.gitIgnore =
+            new GitIgnore(this.logger);
+    }
+    /**
+     * Every path the locations match, deduplicated and sorted.
+     */
+    async resolve(basePath, location) {
+        const results = [];
+        for (const one of toLocations(location)) {
+            const resolved = await this.resolveOne(basePath, one);
+            results.push(...resolved);
+        }
+        const unique = [...new Set(results)];
+        unique.sort((a, b) => a.localeCompare(b));
+        return unique;
+    }
+    /**
+     * Whether the target path belongs to any of the locations.
+     *
+     * This answers the question without walking the filesystem, which is what
+     * makes it usable per file.
+     */
+    async check(targetPath, basePath, location) {
+        for (const one of toLocations(location)) {
+            const matched = await this.checkOne(targetPath, basePath, one);
+            if (matched) {
+                return true;
+            }
+        }
+        return false;
+    }
+    async resolveOne(basePath, location) {
+        const patterns = toPatterns(location);
+        const exclude = location.exclude
+            ?? [];
+        const filters = location.filters
+            ?? [];
+        this.logger.trace('LocationResolver.resolve(%s, %s)', basePath, JSON.stringify(location));
+        const normalisedBasePath = path.normalize(path.resolve(basePath));
+        assertFilePatterns([...patterns,
+            ...exclude]);
+        const matches = new Set(await this.expand(patterns, normalisedBasePath));
+        for (const excluded of await this.expand(exclude, normalisedBasePath)) {
+            matches.delete(excluded);
+        }
+        const result = this.applyFilters([...matches], filters);
+        result.sort((a, b) => a.localeCompare(b));
+        this.logger.trace('LocationResolver.resolve() => %d matches', result.length);
+        return result;
+    }
+    async checkOne(targetPath, basePath, location) {
+        const patterns = toPatterns(location);
+        const exclude = location.exclude
+            ?? [];
+        const filters = location.filters
+            ?? [];
+        assertFilePatterns([...patterns,
+            ...exclude]);
+        const normalisedTargetPath = path.normalize(path.resolve(targetPath));
+        const normalisedBasePath = path.normalize(path.resolve(basePath));
+        const matchesPattern = (pattern) => {
+            const kind = this.kindOf(pattern);
+            if (kind === 'absolute') {
+                return minimatch(toPosixPath(normalisedTargetPath), toPosixPath(pattern), { dot: true });
+            }
+            const relativePath = path.relative(kind === 'root'
+                ? this.rootPath
+                : normalisedBasePath, normalisedTargetPath);
+            return minimatch(relativePath, kind === 'root'
+                ? pattern.slice(1)
+                : pattern, { dot: true });
+        };
+        if (!patterns.some(matchesPattern)) {
+            return false;
+        }
+        if (exclude.some(matchesPattern)) {
+            return false;
+        }
+        const result = this.applyFilters([normalisedTargetPath], filters);
+        return result.length > 0;
+    }
+    /**
+     * How a pattern resolves: `absolute`, a path of the file system, such as
+     * `/tmp/notes/*.md` or `C:/notes/*.md`; `root`, from the root, such as
+     * `/docs/**`; or `base`, from the base path.
+     *
+     * A pattern beginning with `/` is from the root, unless its first segment
+     * is no glob, the root has no entry of that name, and the file system root
+     * has one: `/tmp/x.md`, given under a root without a `tmp`, names the file
+     * where it is.
+     */
+    kindOf(pattern) {
+        if (!pattern.startsWith('/')) {
+            return path.isAbsolute(pattern)
+                ? 'absolute'
+                : 'base';
+        }
+        const first = pattern
+            .slice(1)
+            .split('/')[0];
+        return first !== ''
+            && !/[*?[\]{}()!+@]/.test(first)
+            && !existsSync(path.join(this.rootPath, first))
+            && existsSync(path.join(path.parse(this.rootPath).root, first))
+            ? 'absolute'
+            : 'root';
+    }
+    /**
+     * The absolute paths the patterns match.
+     *
+     * An absolute pattern is expanded where it is, one beginning with `/` from
+     * the root, the rest from the base path, so one call can carry every kind;
+     * see `kindOf`.
+     *
+     * Dotfiles are matched, because `check` matches them and the two have to
+     * agree: without it a path such as `.remarkrc.mjs` would be reported as
+     * belonging to a location that never finds it.
+     */
+    async expand(patterns, basePath) {
+        const matches = [];
+        const absolutePatterns = patterns
+            .filter(pattern => this.kindOf(pattern)
+            === 'absolute')
+            .map(pattern => toPosixPath(pattern));
+        if (absolutePatterns.length > 0) {
+            matches.push(...await glob(absolutePatterns, { absolute: true,
+                dot: true,
+                nodir: true }));
+        }
+        const rootPatterns = patterns
+            .filter(pattern => this.kindOf(pattern)
+            === 'root')
+            .map(pattern => pattern.slice(1));
+        if (rootPatterns.length > 0) {
+            matches.push(...await glob(rootPatterns, { cwd: this.rootPath,
+                absolute: true,
+                dot: true,
+                nodir: true }));
+        }
+        const basePatterns = patterns.filter(pattern => this.kindOf(pattern)
+            === 'base');
+        if (basePatterns.length > 0) {
+            matches.push(...await glob(basePatterns, { cwd: basePath,
+                absolute: true,
+                dot: true,
+                nodir: true }));
+        }
+        return matches;
+    }
+    applyFilters(paths, filters) {
+        let result = paths;
+        for (const filter of filters) {
+            switch (filter.name) {
+                case 'GitIgnore':
+                    result =
+                        this.gitIgnore.filter(result);
+                    break;
+                default:
+                    throw new Error(`Unknown filter: ${filter.name}`);
+            }
+        }
+        return result;
+    }
+}

package/dist/paths.d.ts

@@ -0,0 +1,9 @@
+/** A path with forward slashes, which is what glob and .gitignore expect. */
+export declare function toPosixPath(filePath: string): string;
+/**
+ * Whether `target` is inside `folder`, or is `folder` itself; with
+ * `orSame: false`, only inside it.
+ */
+export declare function isInside(folder: string, target: string, options?: {
+    orSame?: boolean;
+}): boolean;

package/dist/paths.js

@@ -0,0 +1,18 @@
+import path from 'node:path';
+/** A path with forward slashes, which is what glob and .gitignore expect. */
+export function toPosixPath(filePath) {
+    return filePath.replaceAll('\\', '/');
+}
+/**
+ * Whether `target` is inside `folder`, or is `folder` itself; with
+ * `orSame: false`, only inside it.
+ */
+export function isInside(folder, target, options = {}) {
+    const relative = path.relative(path.resolve(folder), path.resolve(target));
+    if (relative === '') {
+        return options.orSame !== false;
+    }
+    return relative !== '..'
+        && !relative.startsWith(`..${path.sep}`)
+        && !path.isAbsolute(relative);
+}

package/package.json

@@ -1,6 +1,66 @@
 {
   "name": "asljs-locator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.2",
+  "description": "Locates files by glob patterns, exclusions and filters such as .gitignore.",
+  "type": "module",
+  "asljs": {
+    "type": "lib"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist/**",
+    "README.md",
+    "LICENSE.md",
+    "docs/**"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "npm run codegen --if-present && tsc -p tsconfig.build.json",
+    "build:dist": "npm run codegen --if-present && tsc -p tsconfig.dist.json",
+    "typecheck": "npm run codegen --if-present && tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build:dist && npm run build && npm run test && npm run guard:clean-git",
+    "postpublish": "toolkit tag-release-revision",
+    "test": "node --test --enable-source-maps \"build/**/*.test.js\"",
+    "test:watch": "node --watch --test \"build/**/*.test.js\"",
+    "coverage": "npm run build && node --test --experimental-test-coverage --enable-source-maps --test-coverage-exclude=\"**/*.test.js\" \"build/**/*.test.js\"",
+    "release:patch": "toolkit release-patch",
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+  },
+  "keywords": [
+    "glob",
+    "gitignore",
+    "files",
+    "nodejs",
+    "locator"
+  ],
+  "homepage": "https://github.com/AlexandriteSoftware/asljs#readme",
+  "bugs": {
+    "url": "https://github.com/AlexandriteSoftware/asljs/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
+  },
+  "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
+  "license": "SEE LICENSE IN LICENSE.md",
+  "dependencies": {
+    "asljs-logging": "^0.1.1",
+    "glob": "^13.0.6",
+    "ignore": "^7.0.6",
+    "minimatch": "^10.2.6"
+  },
+  "devDependencies": {
+    "asljs-testing": "^0.1.0",
+    "asljs-tmpdir": "^0.1.13",
+    "asljs-toolkit": "^0.1.0"
+  }
+}