view-ignored 0.5.2 → 0.6.0

package/README.md

@@ -10,19 +10,19 @@ by Git, NPM, Yarn, JSR, VSCE or other tools.
 
 ## Requirements
 
-- Node.js 18 or later for production
-- Node.js 20 or later for production type definitions
-- Node.js 22 or later for development type definitions
+Node.js 18 or later
 
 ## Highlights
 
-- **Native.** Get a list of included files using configuration file
+- **Reader.** Get a list of included files using configuration file
   readers, not command-line wrappers.
 - **Plugins.** Built-in [targets](#targets) for popular tools. Use custom
-  targets by implementing the `Target` interface.
+  targets by implementing/extending the `Target` interface.
 - **TypeScript.** Written in TypeScript with type definitions included.
 - **Lightweight.** Minimal dependencies for fast performance and small bundle size.
 - **Easy-to-modify.** Well-written and MIT-licensed.
+- **Browser.** Can be bundled for browser use. See `ScanOptions.fs` and `import ... "view-ignored/browser"`.
+- **Windows.** Windows paths are converted to Unix paths for compatibility with `memfs` based tests and browsers.
 
 > [!NOTE]
 > Despite the name of the package being "view-ignored",
@@ -36,51 +36,99 @@ by Git, NPM, Yarn, JSR, VSCE or other tools.
 ### Basic example
 
 ```ts
-import * as vign from "view-ignored";
-import { Git } from "view-ignored/targets";
+import * as vign from "view-ignored"
+import { Git as target } from "view-ignored/targets"
 
-const results = await vign.scan({ target: Git });
-results.paths.has(".git/HEAD");
+const ctx = await vign.scan({ target })
+ctx.paths.has(".git/HEAD") // false
+ctx.paths.has("src") // true
+
+ctx.paths.get("src") // { ignored, match, kind, ... }
 ```
 
 ### Using custom target
 
 ```ts
-import * as vign from "view-ignored";
 import {
-  type SourceExtractor,
-  type SignedPattern,
-  extractGitignore
-  findAndExtract,
-  signedPatternIgnores,
-} from "view-ignored/patterns";
-import type { Target } from "view-ignored/targets";
-
-const gitSources = ['.gitignore'];
-const gitSourceMap = new Map<string, SourceExtractor>([
-  ['.gitignore', extractGitignore]
-]);
-const gitPattern: SignedPattern = {
-  exclude: [
-    '.git',
-    '.DS_Store',
-  ],
-  include: []
-};
+	type Extractor,
+	extractGitignore,
+	signedPatternIgnores,
+	signedPatternCompile,
+	type SignedPattern,
+} from "view-ignored/patterns"
+
+import type { Target } from "view-ignored/targets"
+
+const extractors: Extractor[] = [
+	{
+		extract: extractGitignore,
+		path: ".gitignore",
+	},
+	{
+		extract: extractGitignore,
+		path: ".git/info/exclude",
+	},
+]
+
+const internal: SignedPattern = {
+	exclude: [".git", ".DS_Store"],
+	include: [],
+	compiled: null,
+}
+
+signedPatternCompile(internal)
 
 export const Git: Target = {
-  async matcher(entry, isDir, ctx) {
-    if (isDir) {
-      await findAndExtract(entry, gitSources, gitSourceMap, ctx);
-      return true;
-    }
-    return await signedPatternIgnores(gitPattern, entry, gitSources, gitSourceMap, ctx);
-  }
-};
+	extractors,
+	ignores(o) {
+		return signedPatternIgnores({
+			...o,
+			internal,
+			root: "/",
+			target: Git,
+		})
+	},
+}
+
+const ctx = await vign.scan({ target })
+```
+
+### Streaming results
+
+```ts
+import * as vign from "view-ignored"
+import { NPM as target } from "view-ignored/targets"
+
+const stream = await vign.scanStream({ target })
+
+stream.on("dirent", console.log)
+stream.on("end", (ctx) => {
+	ctx.paths.has(".git/HEAD") // false
+	ctx.paths.has("node_modules/") // false
+	ctx.paths.has("package.json") // true
+})
 ```
 
+### Browser and custom FS
+
+To avoid imports from `node:fs` and `node:process` modules,
+use the browser submodule, which requires some additional options.
+
 ```ts
-vign.scan({ target: Git });
+import * as vign from "view-ignored/browser"
+// or view-ignored/browser/scan
+import { Git as target } from "view-ignored/targets"
+
+export const cwd = process.cwd()
+
+const customFs = {
+	promises: {
+		opendir,
+		readFile,
+	},
+}
+
+vign.scan({ target, cwd, fs })
 ```
 
 ## Targets
@@ -92,25 +140,34 @@ vign.scan({ target: Git });
 The following built-in scanners are available:
 
 - Git
-  - Reads `.gitignore` files but does not consider global settings.
-  - Check this scanner by running `git ls-tree -r HEAD --name-only`.
+  - Reads `.gitignore` and `.git/info/exclude` but does not consider global settings.
+  - Starts searching from `/`.
+  - Check this scanner by running `git ls-files --others --exclude-standard --cached`.
   - See the implementation of [Git target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/git.ts) for details.
 - NPM (compatible with Bun, PNPM, and others)
   - Reads `.npmignore` and `package.json` `files` field.
+  - Starts searching from `.` (current working directory).
   - No additional checks for `name`, `version` or `publishConfig`.
   - Check this scanner by running `npm pack --dry-run`.
   - See the implementation of [NPM target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/npm.ts) for details.
 - Yarn
   - Same behavior as `npm`, but also reads `.yarnignore`.
+  - Starts searching from `.` (current working directory).
   - See the implementation of [Yarn target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/yarn.ts) for details.
 - VSCE
-  - Reads `.vscodeignore` and `package.json` `files` field.
+  - Reads `package.json` `files` field, `.vscodeignore` and `.gitignore`.
+  - Starts searching from `.` (current working directory).
   - Check this scanner by running `vsce ls`.
   - See the implementation of [VSCE target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/vsce.ts) for details.
 - JSR (compatible with Deno)
   - Reads `jsr.json(c)` and `deno.json(c)` `include` and `exclude` fields.
+  - Starts searching from `.` (current working directory).
   - See the implementation of [JSR target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/jsr.ts) for details.
 
+## See also
+
+- https://jsr.io/@m234/path - Utility to sort, convert and format paths.
+
 ## License
 
 MIT License. See [LICENSE.txt](LICENSE.txt) for details.

package/out/browser.d.ts

@@ -0,0 +1,3 @@
+export { scan } from "./browser_scan.js";
+export { scanStream as stream } from "./browser_stream.js";
+export type * from "./types.js";

package/out/browser.js

@@ -0,0 +1,2 @@
+export { scan } from "./browser_scan.js";
+export { scanStream as stream } from "./browser_stream.js";

package/out/browser_scan.d.ts

@@ -0,0 +1,20 @@
+import type { MatcherContext } from "./patterns/matcherContext.js";
+import type { ScanOptions, FsAdapter } from "./types.js";
+export type * from "./types.js";
+/**
+ * Scan the directory for included files based on the provided targets.
+ *
+ * Note that this function uses `fs/promises.readFile` and `fs/promises.opendir` without options within
+ * custom recursion, instead of `fs.promises.readdir` with `{ withFileTypes: true }.
+ * It also normalizes paths to use forward slashes.
+ * Please report any issues if you encounter problems related to this behavior.
+ *
+ * @param options Scan options.
+ * @returns A promise that resolves to a {@link MatcherContext} containing the scan results.
+ *
+ * @since 0.0.6
+ */
+export declare function scan(options: ScanOptions & {
+    fs: FsAdapter;
+    cwd: string;
+}): Promise<MatcherContext>;

package/out/browser_scan.js

@@ -0,0 +1,54 @@
+import { resolve } from "node:path";
+import { normalizeCwd } from "./normalizeCwd.js";
+import { opendir } from "./opendir.js";
+import { walkIncludes } from "./walk.js";
+/**
+ * Scan the directory for included files based on the provided targets.
+ *
+ * Note that this function uses `fs/promises.readFile` and `fs/promises.opendir` without options within
+ * custom recursion, instead of `fs.promises.readdir` with `{ withFileTypes: true }.
+ * It also normalizes paths to use forward slashes.
+ * Please report any issues if you encounter problems related to this behavior.
+ *
+ * @param options Scan options.
+ * @returns A promise that resolves to a {@link MatcherContext} containing the scan results.
+ *
+ * @since 0.0.6
+ */
+export function scan(options) {
+    const { target, cwd, within: select = ".", invert = false, depth: maxDepth = Infinity, signal = null, fastDepth = false, fastInternal = false, fs, } = options;
+    if (maxDepth < 0) {
+        throw new TypeError("Depth must be a non-negative integer");
+    }
+    const ctx = {
+        paths: new Map(),
+        external: new Map(),
+        failed: [],
+        depthPaths: new Map(),
+        totalFiles: 0,
+        totalMatchedFiles: 0,
+        totalDirs: 0,
+    };
+    const normalCwd = normalizeCwd(cwd);
+    const scanOptions = {
+        cwd: normalCwd,
+        within: select,
+        depth: maxDepth,
+        fastDepth,
+        fastInternal,
+        fs,
+        invert,
+        signal,
+        target,
+    };
+    const result = opendir(fs, resolve(normalCwd, select), (entry) => walkIncludes({
+        entry,
+        ctx,
+        stream: undefined,
+        scanOptions,
+    }));
+    return (async () => {
+        await result;
+        return ctx;
+    })();
+}

package/out/browser_stream.d.ts

@@ -0,0 +1,12 @@
+import { MatcherStream } from "./patterns/matcherStream.js";
+import type { ScanOptions, FsAdapter } from "./types.js";
+export type * from "./types.js";
+/**
+ * @see {@link browserScan}
+ *
+ * @since 0.0.6
+ */
+export declare function scanStream(options: ScanOptions & {
+    fs: FsAdapter;
+    cwd: string;
+}): MatcherStream;

package/out/browser_stream.js

@@ -0,0 +1,46 @@
+import { resolve } from "node:path";
+import { normalizeCwd } from "./normalizeCwd.js";
+import { opendir } from "./opendir.js";
+import { MatcherStream } from "./patterns/matcherStream.js";
+import { walkIncludes } from "./walk.js";
+/**
+ * @see {@link browserScan}
+ *
+ * @since 0.0.6
+ */
+export function scanStream(options) {
+    const { target, cwd, within: select = ".", invert = false, depth: maxDepth = Infinity, signal = null, fastDepth = false, fastInternal = false, fs, } = options;
+    const ctx = {
+        paths: new Map(),
+        external: new Map(),
+        failed: [],
+        depthPaths: new Map(),
+        totalFiles: 0,
+        totalMatchedFiles: 0,
+        totalDirs: 0,
+    };
+    const stream = new MatcherStream({ captureRejections: false });
+    const normalCwd = normalizeCwd(cwd);
+    const scanOptions = {
+        cwd: normalCwd,
+        within: select,
+        depth: maxDepth,
+        fastDepth,
+        fastInternal,
+        fs,
+        invert,
+        signal,
+        target,
+    };
+    const result = opendir(fs, resolve(normalCwd, select), (entry) => walkIncludes({
+        entry,
+        ctx,
+        stream,
+        scanOptions,
+    }));
+    void (async () => {
+        await result;
+        stream.emit("end", ctx);
+    })();
+    return stream;
+}

package/out/getDepth.d.ts

@@ -0,0 +1,4 @@
+export declare function getDepth(path: string, maxDepth: number): {
+    depth: number;
+    depthSlash: number;
+};

package/out/getDepth.js

@@ -0,0 +1,21 @@
+export function getDepth(path, maxDepth) {
+    if (path.endsWith("/")) {
+        path = path.substring(0, path.length - 1);
+    }
+    const result = {
+        depth: 0,
+        depthSlash: -1,
+    };
+    let i = -1;
+    for (const c of path) {
+        i++;
+        if (c !== "/") {
+            continue;
+        }
+        if (result.depth === maxDepth) {
+            result.depthSlash = i;
+        }
+        result.depth++;
+    }
+    return result;
+}

package/out/index.d.ts

@@ -1 +1,3 @@
-export * from './scan.js';
+export { scan } from "./scan.js";
+export { scanStream } from "./stream.js";
+export type * from "./types.js";

package/out/index.js

@@ -1 +1,2 @@
-export * from './scan.js';
+export { scan } from "./scan.js";
+export { scanStream } from "./stream.js";

package/out/normalizeCwd.d.ts

@@ -0,0 +1 @@
+export declare function normalizeCwd(cwd: string): string;

package/out/normalizeCwd.js

@@ -0,0 +1,4 @@
+import { resolve } from "node:path";
+export function normalizeCwd(cwd) {
+    return resolve(cwd).replaceAll("\\", "/").replace(/\w:/, "");
+}

package/out/opendir.d.ts

@@ -0,0 +1,3 @@
+import type { Dirent, PathLike } from "node:fs";
+import type { FsAdapter } from "./types.js";
+export declare function opendir(fs: FsAdapter, path: PathLike, cb: (entry: Dirent) => Promise<0 | 1 | 2>): Promise<void | 2>;

package/out/opendir.js

@@ -0,0 +1,18 @@
+export async function opendir(fs, path, cb) {
+    const dir = await fs.promises.opendir(path);
+    for await (const entry of dir) {
+        const r = await cb(entry);
+        if (r === 2) {
+            return 2;
+        }
+        if (r === 1) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            const r = await opendir(fs, path + "/" + entry.name, cb);
+            if (r === 2) {
+                return 2;
+            }
+        }
+    }
+}

package/out/patterns/extractor.d.ts

@@ -0,0 +1,80 @@
+import type { Target } from "../targets/target.js";
+import type { FsAdapter } from "../types.js";
+import type { MatcherContext } from "./matcherContext.js";
+import type { Source } from "./source.js";
+/**
+ * Populates the source object from the content of a source file.
+ * Results are available in `ctx.external`.
+ * If `"none"` returned or throwed, will skip the extractor.
+ *
+ * @see {@link Source.pattern} for more details.
+ * @throws Error if extraction fails. Processing stops.
+ *
+ * @since 0.0.6
+ */
+export type ExtractorFn = (source: Source, content: Buffer, ctx: MatcherContext) => void | "none";
+/**
+ * Defines a method for extracting patterns from a specific source file.
+ *
+ * @since 0.0.6
+ */
+export interface Extractor {
+    /**
+     * Relative path.
+     *
+     * @example
+     * ".gitignore"
+     *
+     * @since 0.0.6
+     */
+    path: string;
+    /**
+     * Populates the source object from the content of a source file.
+     *
+     * @see {@link ExtractorFn}
+     *
+     * @since 0.0.6
+     */
+    extract: ExtractorFn;
+}
+/**
+ * Options for finding and extracting patterns from source files.
+ *
+ * @see {@link resolveSources}
+ * @see {@link signedPatternIgnores}
+ *
+ * @since 0.0.6
+ */
+export interface PatternFinderOptions {
+    /**
+     * The file system adapter for directory walking and reading files.
+     *
+     * @since 0.0.6
+     */
+    fs: FsAdapter;
+    /**
+     * The context to modify.
+     *
+     * @since 0.0.6
+     */
+    ctx: MatcherContext;
+    /**
+     * The current working directory.
+     *
+     * @since 0.0.6
+     */
+    cwd: string;
+    /**
+     * The target implementation.
+     *
+     * @since 0.0.6
+     */
+    target: Target;
+    /**
+     * Initial search directory.
+     * Relative to the `cwd` path or absolute path.
+     *
+     * @since 0.0.6
+     */
+    root: string;
+}

package/out/patterns/extractor.js

@@ -0,0 +1 @@
+export {};

package/out/patterns/gitignore.d.ts

@@ -1,3 +1,9 @@
-import { type Source } from './matcher.js';
-export declare function extractGitignore(source: Source, content: Buffer<ArrayBuffer>): void;
-export declare function gitignoreMatch(pattern: string, path: string): boolean;
+import { type Source } from "./source.js";
+/**
+ * Extracts and compiles patterns from the file.
+ *
+ * @see {@link signedPatternCompile}
+ *
+ * @since 0.0.6
+ */
+export declare function extractGitignore(source: Source, content: Buffer): void;

package/out/patterns/gitignore.js

@@ -1,31 +1,24 @@
-import { sourcePushNegatable } from './matcher.js';
-import { minimatch } from 'minimatch';
+import { signedPatternCompile } from "./resolveSources.js";
+import { sourcePushNegatable } from "./source.js";
+/**
+ * Extracts and compiles patterns from the file.
+ *
+ * @see {@link signedPatternCompile}
+ *
+ * @since 0.0.6
+ */
 export function extractGitignore(source, content) {
-    for (let line of content.toString().split('\n')) {
+    for (let line of content.toString().split("\n")) {
         line = line.trim();
-        if (line === '' || line.startsWith('#')) {
+        if (line === "" || line.startsWith("#")) {
             continue;
         }
-        const cdx = line.indexOf('#');
+        const cdx = line.indexOf("#");
         if (cdx >= 0) {
             line = line.substring(-cdx);
         }
         sourcePushNegatable(source, line);
     }
-    // TODO: validate gitignore
+    signedPatternCompile(source.pattern);
 }
 extractGitignore;
-export function gitignoreMatch(pattern, path) {
-    const o = { dot: true };
-    if (pattern.startsWith('/')) {
-        pattern = pattern.substring(1);
-    }
-    else if (!pattern.startsWith('**/')) {
-        if (minimatch(path, '**/' + pattern, o))
-            return true;
-    }
-    if (pattern.endsWith('/')) {
-        pattern = pattern.substring(-1);
-    }
-    return minimatch(path, pattern, o) || minimatch(path, pattern + '/**', o);
-}

package/out/patterns/ignores.d.ts

@@ -0,0 +1,19 @@
+import type { MatcherContext } from "../patterns/matcherContext.js";
+import type { SignedPatternMatch } from "../patterns/signedPattern.js";
+import type { FsAdapter } from "../types.js";
+export interface IgnoresOptions {
+    fs: FsAdapter;
+    cwd: string;
+    entry: string;
+    ctx: MatcherContext;
+}
+/**
+ * Checks whether a given entry path should be ignored based on its patterns.
+ *
+ * @see {@link resolveSources}
+ * @see {@link signedPatternIgnores}
+ * @see {@link https://github.com/Mopsgamer/view-ignored/tree/main/src/targets} for usage examples.
+ *
+ * @since 0.0.6
+ */
+export type Ignores = (options: IgnoresOptions) => Promise<SignedPatternMatch>;

package/out/patterns/ignores.js

@@ -0,0 +1 @@
+export {};

package/out/patterns/index.d.ts

@@ -1,4 +1,13 @@
-export * from './matcher.js';
-export * from './gitignore.js';
-export * from './jsrjson.js';
-export * from './packagejson.js';
+export * from "./extractor.js";
+export * from "./gitignore.js";
+export * from "./ignores.js";
+export * from "./jsrjson.js";
+export * from "./matcherContext.js";
+export * from "./matcherContextPatch.js";
+export * from "./matcherStream.js";
+export * from "./packagejson.js";
+export * from "./pattern.js";
+export * from "./patternMatcher.js";
+export * from "./resolveSources.js";
+export * from "./signedPattern.js";
+export * from "./source.js";

package/out/patterns/index.js

@@ -1,4 +1,13 @@
-export * from './matcher.js';
-export * from './gitignore.js';
-export * from './jsrjson.js';
-export * from './packagejson.js';
+export * from "./extractor.js";
+export * from "./gitignore.js";
+export * from "./ignores.js";
+export * from "./jsrjson.js";
+export * from "./matcherContext.js";
+export * from "./matcherContextPatch.js";
+export * from "./matcherStream.js";
+export * from "./packagejson.js";
+export * from "./pattern.js";
+export * from "./patternMatcher.js";
+export * from "./resolveSources.js";
+export * from "./signedPattern.js";
+export * from "./source.js";

package/out/patterns/jsrjson.d.ts

@@ -1,4 +1,16 @@
-import { type } from 'arktype';
-import type { Source } from './matcher.js';
-export declare function extractJsrJson(source: Source, content: Buffer<ArrayBuffer>): type.errors | undefined;
-export declare function extractJsrJsonc(source: Source, content: Buffer<ArrayBuffer>): type.errors | undefined;
+import type { MatcherContext } from "./matcherContext.js";
+import type { Source } from "./source.js";
+/**
+ * Extracts and compiles patterns from the file.
+ *
+ * @since 0.0.6
+ */
+export declare function extractJsrJson(source: Source, content: Buffer, ctx: MatcherContext): void;
+/**
+ * Extracts and compiles patterns from the file.
+ *
+ * @see {@link signedPatternCompile}
+ *
+ * @since 0.0.6
+ */
+export declare function extractJsrJsonc(source: Source, content: Buffer, ctx: MatcherContext): void;