asljs-locator 0.0.0-stage → 0.1.1

package/LICENSE.md

@@ -0,0 +1,20 @@
+# MIT License
+
+Copyright (c) 2026 Alexandrite Software Ltd
+
+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,90 @@
-# 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.
+
+## 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`.
+
+## 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 { 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 { toPosixPath } from './paths.js';

package/dist/location.d.ts

@@ -0,0 +1,59 @@
+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;
+    /**
+     * The absolute paths the patterns match.
+     *
+     * A pattern beginning with `/` is expanded from the root, the rest from the
+     * base path, so one call can carry both kinds.
+     *
+     * 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,162 @@
+import { glob } from 'glob';
+import { minimatch } from 'minimatch';
+import path from 'node:path';
+import { GitIgnore } from './git-ignore.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 anchored = pattern.startsWith('/');
+            const relativePath = path.relative(anchored
+                ? this.rootPath
+                : normalisedBasePath, normalisedTargetPath);
+            return minimatch(relativePath, anchored
+                ? 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;
+    }
+    /**
+     * The absolute paths the patterns match.
+     *
+     * A pattern beginning with `/` is expanded from the root, the rest from the
+     * base path, so one call can carry both kinds.
+     *
+     * 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 rootPatterns = patterns
+            .filter(pattern => pattern.startsWith('/'))
+            .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 => !pattern.startsWith('/'));
+        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,2 @@
+/** A path with forward slashes, which is what glob and .gitignore expect. */
+export declare function toPosixPath(filePath: string): string;

package/dist/paths.js

@@ -0,0 +1,4 @@
+/** A path with forward slashes, which is what glob and .gitignore expect. */
+export function toPosixPath(filePath) {
+    return filePath.replaceAll('\\', '/');
+}

package/package.json

@@ -1,6 +1,61 @@
 {
   "name": "asljs-locator",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Locates files by glob patterns, exclusions and filters such as .gitignore.",
+  "type": "module",
+  "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"
+  ],
+  "scripts": {
+    "flint": "toolkit flint",
+    "clean": "toolkit clean",
+    "build": "tsc -p tsconfig.build.json",
+    "build:dist": "tsc -p tsconfig.dist.json",
+    "typecheck": "tsc -p tsconfig.build.json --noEmit",
+    "guard:clean-git": "toolkit ensure-clean-working-directory",
+    "prepack": "npm run clean && npm run build && npm run test && npm run build:dist && 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",
+    "release:patch": "toolkit release-patch",
+    "all": "npm i && 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": "MIT",
+  "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"
+  }
+}