view-ignored 0.4.7 → 0.5.0

package/README.md

@@ -5,124 +5,88 @@
 [![github](https://img.shields.io/github/stars/Mopsgamer/view-ignored.svg?style=flat)](https://github.com/Mopsgamer/view-ignored)
 [![github issues](https://img.shields.io/github/issues/Mopsgamer/view-ignored.svg?style=flat)](https://github.com/Mopsgamer/view-ignored/issues)
 
-Retrieve list of files ignored/included by Git, NPM, Yarn, JSR, VSCE or other
-tools.
+Retrieve list of files ignored/included
+by Git, NPM, Yarn, JSR, VSCE or other tools.
 
 ## Requirements
 
-Requires Node.js v18 or later.
+- 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
 
 ## Highlights
 
-- **Multi-target.** Get a list of included files using configuration file
+- **Native.** Get a list of included files using configuration file
   readers, not command-line wrappers.
-- **Use in browser.** view-ignored can run in the browser using a file system
-  adapter.
-- **Command-line.** Supports no-color and multiple output styles (tree, list,
-  parsable, etc.), including
-  [Nerd Fonts](https://github.com/ryanoasis/nerd-fonts).
-- **Plugins.** view-ignored allows you to add new [targets](#targets)
-  programmatically. Command-line interface supports plugins through `--plugins`
-  option.
+- **Plugins.** Built-in [targets](#targets) for popular tools. Use custom
+  targets by implementing 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.
+
+> [!NOTE]
+> Despite the name of the package being "view-ignored",
+> the primary purpose is to get the list of
+> **included** files, i.e., files that are **not ignored**.
+> You can invert the results if you need the ignored files
+> by setting the `invert` option to `true`.
 
 ## Usage
 
-### Command-line
-
-After installing globally, you can use the following commands:
-
-```bash
-# get started
-npm i -g view-ignored
-viewig --help
-view-ignored --help
-
-# scan: git (default) and npm
-viewig scan
-viewig scan --target=npm
-viewig sc -t npm
-viewig scan --parsable
-
-# scan: plugins (space, comma or pipe separated)
-# all built-in plugins loaded automatically
-# Replace example1/example2 with real plugin names
-viewig scan --plugins="example1, example2"
-viewig scan --plugins="example1 example2"
-viewig scan --plugins example1 example2
-viewig scan --plugins example1, example2
-
-# config: print configuration entries
-viewig config get
-viewig config get --real
-# config: set npm as default target and scan for npm
-viewig config set target=npm
-viewig scan
-# config: always use nerdfonts
-viewig config set style=tree
-# config: always use Nerd Fonts for decoration
-viewig config set decor=nerdfonts
-# config: always use plugins
-viewig config set plugins=example1,example2
-```
-
-### Programmatically
+### Basic example
 
-To use programmatically:
+```ts
+import * as vign from "view-ignored";
+import { Git } from "view-ignored/targets";
 
-```js
-import * as vign from "view-ignored"; // or "view-ignored/browser"
+const results = await vign.scan({ target: Git });
+results.paths.has(".git/HEAD");
+```
 
-await vign.Plugins.loadBuiltIns(["git", "npm"]); // load built-in plugins
-await vign.Plugins.loadBuiltIns(); // load all built-in plugins
-await vign.Plugins.loadPlugins(["example"]); // load third-party plugins
+### Using custom target
 
-// scan - options available
-const fileInfoList = await vign.scan(".", {
-  target: "git",
-  cwd: process.cwd(),
-});
-const fileInfoList2 = await vign.scan(["./path/to/file"], {
-  target: "git",
-  cwd: process.cwd(),
-});
+```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: []
+};
 
-// use results
-for (const fileInfo of fileInfoList) {
-  if (fileInfo.ignored) {
-    superCodeEditor.explorer.colorFile(fileInfo.relativePath, "gray");
+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);
   }
-}
-```
-
-#### Sorting
-
-```js
-const sorter = vign.Sorting.firstFolders;
-const fileInfoList = await vign.scan(".", { target: "npm" });
-const fileInfoSorted = fileInfoList.sort((a, b) =>
-  sorter(String(a), String(b))
-);
+};
 ```
 
-#### Plugin export example
-
 ```ts
-const bind: Plugins.TargetBind = {
-  id,
-  icon,
-  name,
-  testCommand,
-  scanOptions: {
-    target: methodologyGitignoreLike(".gitignore"),
-  },
-};
-const git: Plugins.PluginExport = { viewignored: { addTargets: [bind] } };
-export default git;
+vign.scan({ target: Git });
 ```
 
-### Targets
+## Targets
+
 
-The following built-in plugins are available:
+The following built-in targets are available:
 
 - `git`
 - `npm` (compatible with Bun, PNPM, and others)
@@ -133,3 +97,7 @@ The following built-in plugins are available:
 ## License
 
 MIT License. See [LICENSE.txt](LICENSE.txt) for details.
+
+## Target implementations
+<!-- .ts links -->
+See [Target implementations](src/targets/README.md) for details.

package/out/index.d.ts

@@ -1,4 +1 @@
-import * as ViewIgnored from './lib.js';
-export default ViewIgnored;
-export * from './lib.js';
-//# sourceMappingURL=index.d.ts.map
+export * from './scan.js';

package/out/index.js

@@ -1,4 +1 @@
-import * as ViewIgnored from './lib.js';
-export default ViewIgnored;
-export * from './lib.js';
-//# sourceMappingURL=index.js.map
+export * from './scan.js';

package/out/patterns/gitignore.d.ts

@@ -0,0 +1,3 @@
+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;

package/out/patterns/gitignore.js

@@ -0,0 +1,35 @@
+import { minimatch } from 'minimatch';
+export function extractGitignore(source, content) {
+    for (let line of content.toString().split('\n')) {
+        line = line.trim();
+        if (line === '' || line.startsWith('#')) {
+            continue;
+        }
+        const cdx = line.indexOf('#');
+        if (cdx >= 0) {
+            line = line.substring(-cdx);
+        }
+        if (line.startsWith('!')) {
+            source.pattern.include.push(line.substring(1));
+        }
+        else {
+            source.pattern.exclude.push(line);
+        }
+    }
+    // TODO: validate gitignore
+}
+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/index.d.ts

@@ -0,0 +1,4 @@
+export * from './matcher.js';
+export * from './gitignore.js';
+export * from './jsrjson.js';
+export * from './packagejson.js';

package/out/patterns/index.js

@@ -0,0 +1,4 @@
+export * from './matcher.js';
+export * from './gitignore.js';
+export * from './jsrjson.js';
+export * from './packagejson.js';

package/out/patterns/jsrjson.d.ts

@@ -0,0 +1,4 @@
+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;

package/out/patterns/jsrjson.js

@@ -0,0 +1,39 @@
+import { type } from 'arktype';
+import stripJsonComments from 'strip-json-comments';
+const jsrManifest = type({
+    exclude: 'string[]?',
+    include: 'string[]?',
+    publish: {
+        exclude: 'string[]?',
+        include: 'string[]?',
+    },
+});
+const parse = jsrManifest.pipe((s) => JSON.parse(s));
+export function extractJsrJson(source, content) {
+    const dist = parse(content.toString());
+    if (dist instanceof type.errors) {
+        return dist;
+    }
+    if (!dist.publish) {
+        if (dist.exclude) {
+            source.pattern.exclude.push(...dist.exclude);
+        }
+    }
+    else if (dist.publish.exclude) {
+        source.pattern.exclude.push(...dist.publish.exclude);
+    }
+    if (!dist.publish) {
+        if (dist.include) {
+            source.pattern.include.push(...dist.include);
+        }
+    }
+    else if (dist.publish.include) {
+        source.pattern.include.push(...dist.publish.include);
+    }
+    return;
+}
+extractJsrJson;
+export function extractJsrJsonc(source, content) {
+    return extractJsrJson(source, Buffer.from(stripJsonComments(content.toString())));
+}
+extractJsrJsonc;

package/out/patterns/matcher.d.ts

@@ -0,0 +1,39 @@
+export type MatcherContext = {
+    paths: Set<string>;
+    external: Map<string, Source>;
+    depthPaths: Map<string, number>;
+    sourceErrors: Error[];
+    totalFiles: number;
+    totalMatchedFiles: number;
+    totalDirs: number;
+};
+/**
+ * Represents a list of positive minimatch patterns.
+ */
+export type Pattern = string[];
+export declare function patternMatches(pattern: Pattern, path: string): boolean;
+/**
+ * Represents a set of include and exclude patterns.
+ * These patterns are positive minimatch patterns.
+ */
+export type SignedPattern = {
+    include: Pattern;
+    exclude: Pattern;
+};
+/**
+ * Combined internal and external patterns for matching.
+ * Used in {@link signedPatternIgnores} function.
+ */
+export type PatternMatcher = {
+    internal: SignedPattern;
+    external: SignedPattern;
+};
+export type PathChecker = (path: string, isDir: boolean, ctx: MatcherContext) => Promise<boolean>;
+export type Source = {
+    pattern: SignedPattern;
+    name: string;
+    inverted: boolean;
+};
+export type SourceExtractor = (source: Source, content: Buffer<ArrayBuffer>) => void;
+export declare function findAndExtract(directory: string, sources: string[], matcher: Map<string, SourceExtractor>, ctx: MatcherContext): Promise<void>;
+export declare function signedPatternIgnores(internal: SignedPattern, file: string, sources: string[], sourceMap: Map<string, SourceExtractor>, ctx: MatcherContext): Promise<boolean>;

package/out/patterns/matcher.js

@@ -0,0 +1,118 @@
+import * as fsp from 'node:fs/promises';
+import { dirname } from 'node:path';
+import { gitignoreMatch } from './gitignore.js';
+export function patternMatches(pattern, path) {
+    for (const p of pattern) {
+        const matched = gitignoreMatch(p, path);
+        if (matched) {
+            return true;
+        }
+    }
+    return false;
+}
+export async function findAndExtract(directory, sources, matcher, ctx) {
+    const keys = [];
+    for (const sourceFileName of sources) {
+        for (;;) {
+            let buff;
+            try {
+                buff = await fsp.readFile(directory + '/' + sourceFileName);
+            }
+            catch (err) {
+                const error = err;
+                if (error.code !== 'ENOENT') {
+                    ctx.sourceErrors.push(error);
+                    return;
+                }
+            }
+            const dir = dirname(directory);
+            if (!ctx.external.has(directory)) {
+                keys.push(directory);
+            }
+            if (!buff) {
+                if (directory === '.') {
+                    break;
+                }
+                directory = dir;
+                continue;
+            }
+            if (directory === '.' && !keys.length) {
+                break;
+            }
+            const sourceExtractor = matcher.get(sourceFileName);
+            if (!sourceExtractor) {
+                const err = new Error('No extractor for source file: ' + sourceFileName);
+                ctx.sourceErrors.push(err);
+                break;
+            }
+            const source = {
+                inverted: false,
+                name: sourceFileName,
+                pattern: {
+                    exclude: [],
+                    include: [],
+                },
+            };
+            try {
+                sourceExtractor(source, buff);
+            }
+            catch (err) {
+                ctx.sourceErrors.push(err);
+                break;
+            }
+            for (const key of keys) {
+                const m = ctx.external.get(key);
+                if (!m) {
+                    ctx.external.set(key, source);
+                }
+            }
+            if (directory === '.') {
+                return;
+            }
+            keys.length = 0;
+            directory = dir;
+        }
+    }
+}
+export async function signedPatternIgnores(internal, file, sources, sourceMap, ctx) {
+    const parent = dirname(file);
+    let source = ctx.external.get(parent);
+    if (!source) {
+        await findAndExtract(parent, sources, sourceMap, ctx);
+        if (ctx.sourceErrors.length) {
+            return false;
+        }
+        source = ctx.external.get(parent);
+        if (!source) {
+            return false;
+        }
+    }
+    const matcher = {
+        internal,
+        external: source.pattern,
+    };
+    try {
+        let check = false;
+        check = patternMatches(matcher.internal.exclude, file);
+        if (check) {
+            return true;
+        }
+        check = patternMatches(matcher.internal.include, file);
+        if (check) {
+            return false;
+        }
+        check = patternMatches(matcher.external.exclude, file);
+        if (check) {
+            return true;
+        }
+        check = patternMatches(matcher.external.include, file);
+        if (check) {
+            return false;
+        }
+    }
+    catch (err) {
+        ctx.sourceErrors.push(err);
+        return false;
+    }
+    return source.inverted;
+}

package/out/patterns/packagejson.d.ts

@@ -0,0 +1,3 @@
+import { type } from 'arktype';
+import type { Source } from './matcher.js';
+export declare function extractPackageJson(source: Source, content: Buffer<ArrayBuffer>): type.errors | undefined;

package/out/patterns/packagejson.js

@@ -0,0 +1,25 @@
+import { type } from 'arktype';
+const nodeJsManifest = type({
+    files: 'string[]?',
+});
+const parse = nodeJsManifest.pipe((s) => JSON.parse(s));
+export function extractPackageJson(source, content) {
+    source.inverted = true;
+    const dist = parse(content.toString());
+    if (dist instanceof type.errors) {
+        return dist;
+    }
+    if (!dist.files) {
+        return;
+    }
+    for (const p of dist.files) {
+        if (p.startsWith('!')) {
+            source.pattern.exclude.push(...p.substring(1));
+        }
+        else {
+            source.pattern.include.push(...p);
+        }
+    }
+    return;
+}
+extractPackageJson;

package/out/scan.d.ts

@@ -0,0 +1,46 @@
+import type { MatcherContext } from './patterns/matcher.js';
+import type { Target } from './targets/target.js';
+export type DepthMode = 'files' | undefined;
+export type ScanOptions = {
+    /**
+     * Provides the matcher to use for scanning.
+     */
+    target: Target;
+    /**
+     * Current working directory to start the scan from.
+     */
+    cwd?: string;
+    /**
+     * If enabled, the scan will return files that are ignored by the target matchers.
+     */
+    invert?: boolean;
+    /**
+     * Starting from depth `0` means you will see
+     * children of the current working directory.
+     */
+    depth?: number;
+    /**
+     * Return as soon as possible.
+     */
+    signal?: AbortSignal;
+    /**
+     * If enabled, Depth will be calculated faster by skipping
+     * other files after first match.
+     * This makes the scan faster but affects
+     * {@link MatcherContext.totalDirs},
+     * {@link MatcherContext.totalFiles},
+     * {@link MatcherContext.totalMatchedFiles}
+     * and {@link MatcherContext.depthPaths}.
+     */
+    fastDepth?: boolean;
+};
+/**
+ * Scan the directory for included files based on the provided targets.
+ *
+ * Note that this function uses `fs/promises.opendir` with recursive option,
+ * and `fs/promises.readFile`. It also normalizes paths to use forward slashes..
+ *
+ * @param options Scan options.
+ * @returns A promise that resolves to a map of targets to their matcher contexts.
+ */
+export declare function scan(options: ScanOptions): Promise<MatcherContext>;

package/out/scan.js

@@ -0,0 +1,113 @@
+import { posix } from 'node:path';
+import { opendir } from './walk.js';
+/**
+ * Scan the directory for included files based on the provided targets.
+ *
+ * Note that this function uses `fs/promises.opendir` with recursive option,
+ * and `fs/promises.readFile`. It also normalizes paths to use forward slashes..
+ *
+ * @param options Scan options.
+ * @returns A promise that resolves to a map of targets to their matcher contexts.
+ */
+export async function scan(options) {
+    const { target, cwd: cwdo = (await import('node:process')).cwd(), depth: maxDepth = Infinity, invert = false, signal = undefined, fastDepth = false, } = options;
+    const cwd = cwdo.replaceAll('\\', '/');
+    const ctx = {
+        paths: new Set(),
+        external: new Map(),
+        depthPaths: new Map(),
+        sourceErrors: [],
+        totalFiles: 0,
+        totalMatchedFiles: 0,
+        totalDirs: 0,
+    };
+    await opendir(cwd, async (entry) => {
+        if (signal?.aborted) {
+            return 2;
+        }
+        const path = posix.join(posix.relative(cwd, entry.parentPath.replaceAll('\\', '/')), entry.name);
+        if (entry.isDirectory()) {
+            ctx.totalDirs++;
+            if (!fastDepth) {
+                return 0;
+            }
+            const { depth } = getDepth(path, maxDepth);
+            if (depth <= maxDepth) {
+                return 0;
+            }
+            return 1;
+        }
+        ctx.totalFiles++;
+        if (fastDepth) {
+            const { depth, depthSlash } = getDepth(path, maxDepth);
+            if (depth > maxDepth) {
+                let ignored = await target.matcher(path, false, ctx);
+                if (ctx.sourceErrors.length > 0) {
+                    return 2;
+                }
+                if (invert) {
+                    ignored = !ignored;
+                }
+                if (ignored) {
+                    return 0;
+                }
+                const dir = path.substring(0, depthSlash);
+                ctx.depthPaths.set(dir, (ctx.depthPaths.get(dir) ?? 0) + 1);
+                return 1;
+            }
+        }
+        let ignored = await target.matcher(path, false, ctx);
+        if (ctx.sourceErrors.length > 0) {
+            return 2;
+        }
+        if (invert) {
+            ignored = !ignored;
+        }
+        if (ignored) {
+            return 0;
+        }
+        ctx.totalMatchedFiles++;
+        const { depth, depthSlash } = getDepth(path, maxDepth);
+        if (depth > maxDepth) {
+            const dir = path.substring(0, depthSlash);
+            ctx.depthPaths.set(dir, (ctx.depthPaths.get(dir) ?? 0) + 1);
+        }
+        else {
+            ctx.paths.add(path);
+        }
+        return 0;
+    });
+    if (signal?.aborted) {
+        return ctx;
+    }
+    for (const [dir, count] of ctx.depthPaths) {
+        if (count === 0) {
+            continue;
+        }
+        ctx.paths.add(dir + '/');
+    }
+    console.log(ctx.paths);
+    return ctx;
+}
+function getDepth(path, maxDepth) {
+    const result = {
+        depth: 0,
+        depthSlash: 0,
+    };
+    result.depthSlash = -1;
+    if (maxDepth < 0) {
+        return result;
+    }
+    for (const [i, c] of Array.from(path).entries()) {
+        if (c !== '/') {
+            continue;
+        }
+        result.depth++;
+        if (result.depth < maxDepth) {
+            continue;
+        }
+        result.depthSlash = i;
+        return result;
+    }
+    return result;
+}

package/out/targets/git.d.ts

@@ -0,0 +1,2 @@
+import type { Target } from './target.js';
+export declare const Git: Target;

package/out/targets/git.js

@@ -0,0 +1,22 @@
+import { signedPatternIgnores, findAndExtract } from '../patterns/matcher.js';
+import { extractGitignore } from '../patterns/gitignore.js';
+const gitSources = ['.gitignore'];
+const gitSourceMap = new Map([
+    ['.gitignore', extractGitignore],
+]);
+const gitPattern = {
+    exclude: [
+        '.git',
+        '.DS_Store',
+    ],
+    include: [],
+};
+export const Git = {
+    async matcher(entry, isDir, ctx) {
+        if (isDir) {
+            await findAndExtract(entry, gitSources, gitSourceMap, ctx);
+            return true;
+        }
+        return await signedPatternIgnores(gitPattern, entry, gitSources, gitSourceMap, ctx);
+    },
+};