asljs-locator 0.1.1 → 0.1.2

package/LICENSE.md

@@ -1,20 +1,51 @@
-# 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.
+# 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

@@ -18,6 +18,12 @@ 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
@@ -68,6 +74,10 @@ 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.

package/dist/index.d.ts

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

package/dist/index.js

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

package/dist/location.d.ts

@@ -44,11 +44,23 @@ export declare class LocationResolver {
     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.
      *
-     * A pattern beginning with `/` is expanded from the root, the rest from the
-     * base path, so one call can carry both kinds.
+     * 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

package/dist/location.js

@@ -1,7 +1,9 @@
 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
@@ -98,11 +100,14 @@ export class LocationResolver {
         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
+            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, anchored
+            return minimatch(relativePath, kind === 'root'
                 ? pattern.slice(1)
                 : pattern, { dot: true });
         };
@@ -115,11 +120,38 @@ export class LocationResolver {
         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.
      *
-     * A pattern beginning with `/` is expanded from the root, the rest from the
-     * base path, so one call can carry both kinds.
+     * 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
@@ -127,8 +159,18 @@ export class LocationResolver {
      */
     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 => pattern.startsWith('/'))
+            .filter(pattern => this.kindOf(pattern)
+            === 'root')
             .map(pattern => pattern.slice(1));
         if (rootPatterns.length > 0) {
             matches.push(...await glob(rootPatterns, { cwd: this.rootPath,
@@ -136,7 +178,8 @@ export class LocationResolver {
                 dot: true,
                 nodir: true }));
         }
-        const basePatterns = patterns.filter(pattern => !pattern.startsWith('/'));
+        const basePatterns = patterns.filter(pattern => this.kindOf(pattern)
+            === 'base');
         if (basePatterns.length > 0) {
             matches.push(...await glob(basePatterns, { cwd: basePath,
                 absolute: true,

package/dist/paths.d.ts

@@ -1,2 +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

@@ -1,4 +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,8 +1,11 @@
 {
   "name": "asljs-locator",
-  "version": "0.1.1",
+  "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": {
@@ -14,21 +17,23 @@
   "files": [
     "dist/**",
     "README.md",
-    "LICENSE.md"
+    "LICENSE.md",
+    "docs/**"
   ],
   "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",
+    "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 && npm run test && npm run build:dist && npm run guard:clean-git",
+    "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",
+    "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 i && npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
+    "all": "npm run clean && npm run build:dist && npm run flint && npm run typecheck && npm run build && npm run test"
   },
   "keywords": [
     "glob",
@@ -46,7 +51,7 @@
     "url": "git+https://github.com/AlexandriteSoftware/asljs.git"
   },
   "author": "\"Alex Netkachov\" <alex.netkachov@gmail.com>",
-  "license": "MIT",
+  "license": "SEE LICENSE IN LICENSE.md",
   "dependencies": {
     "asljs-logging": "^0.1.1",
     "glob": "^13.0.6",