view-ignored 0.4.8 → 0.5.1

package/README.md

@@ -5,130 +5,111 @@
 [![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
-
-The following built-in plugins are available:
-
-- `git`
-- `npm` (compatible with Bun, PNPM, and others)
-- `yarn`
-- `vsce`
-- `jsr` (compatible with Deno)
+## Targets
+
+> [!NOTE]
+> Each scanner expects minimal configurations, but the actual tool can have
+> more/less complex rules. Refer to the documentation of each tool for details.
+
+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`.
+  - 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.
+  - 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`.
+  - 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.
+  - 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.
+  - See the implementation of [JSR target](https://github.com/Mopsgamer/view-ignored/tree/main/src/targets/jsr.ts) for details.
 
 ## License
 

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,102 @@
+/**
+ * The results and statistics of a scanning operation.
+ */
+export type MatcherContext = {
+    /**
+     * `Set` can be sorted, but `view-ignored`
+     * does not sort paths.
+     * @example
+     * new Set(sort(new Set(['a/b', 'a/a'])))
+     */
+    paths: Set<string>;
+    /**
+     * Maps directory paths to their corresponding sources.
+     * @example
+     * "src" => Source
+     */
+    external: Map<string, Source>;
+    /**
+     * Maps directory paths to the quantity of path segments they contain.
+     * @example
+     * "src/components" => 2
+     */
+    depthPaths: Map<string, number>;
+    /**
+     * Any errors encountered while processing source files.
+     */
+    sourceErrors: Error[];
+    /**
+     * Total number of files scanned.
+     */
+    totalFiles: number;
+    /**
+     * Total number of files matched by the target.
+     */
+    totalMatchedFiles: number;
+    /**
+     * Total number of directories scanned.
+     */
+    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;
+};
+/**
+ * Checks whether a given path should be ignored based on its patterns.
+ * @see {@link findAndExtract}
+ * @see {@link signedPatternIgnores}
+ * @see {@link https://github.com/Mopsgamer/view-ignored/tree/main/src/targets} for usage examples.
+ */
+export type PathChecker = (path: string, isDir: boolean, ctx: MatcherContext) => Promise<boolean>;
+/**
+ * Represents a source of patterns for matching paths.
+ */
+export type Source = {
+    /**
+     * Patterns defined within the source file.
+     * Those patterns are for ignoring files.
+     */
+    pattern: SignedPattern;
+    /**
+     * Name of the source file.
+     */
+    name: string;
+    /**
+     * Indicates if the matching logic is inverted.
+     * For example, `package.json` `files` field inverts the matching logic,
+     * because it specifies files to include rather than exclude.
+     */
+    inverted: boolean;
+};
+/**
+ * Populates a `Source` object from the content of a source file.
+ * @see {@link Source.pattern} for more details.
+ */
+export type SourceExtractor = (source: Source, content: Buffer<ArrayBuffer>) => void;
+/**
+ * Populates the {@link MatcherContext.external} map with {@link Source} objects.
+ */
+export declare function findAndExtract(directory: string, sources: string[], matcher: Map<string, SourceExtractor>, ctx: MatcherContext): Promise<void>;
+/**
+ * Checks whether a given file should be ignored based on internal and external patterns.
+ * Populates unknown sources using {@link findAndExtract}.
+ */
+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,125 @@
+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;
+}
+/**
+ * Populates the {@link MatcherContext.external} map with {@link Source} objects.
+ */
+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;
+        }
+    }
+}
+/**
+ * Checks whether a given file should be ignored based on internal and external patterns.
+ * Populates unknown sources using {@link findAndExtract}.
+ */
+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,49 @@
+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 matcher.
+     */
+    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;
+    /**
+     * Requires depth >= 0.
+     * If enabled, directories will be processed faster
+     * by skipping 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.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.
+ */
+export declare function scan(options: ScanOptions): Promise<MatcherContext>;