view-ignored 0.5.0 → 0.5.2

package/README.md

@@ -85,19 +85,32 @@ vign.scan({ target: Git });
 
 ## Targets
 
-
-The following built-in targets are available:
-
-- `git`
-- `npm` (compatible with Bun, PNPM, and others)
-- `yarn`
-- `vsce`
-- `jsr` (compatible with Deno)
+> [!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
 
 MIT License. See [LICENSE.txt](LICENSE.txt) for details.
-
-## Target implementations
-<!-- .ts links -->
-See [Target implementations](src/targets/README.md) for details.

package/out/patterns/gitignore.d.ts

@@ -1,3 +1,3 @@
-import type { Source } from './matcher.js';
+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

@@ -1,3 +1,4 @@
+import { sourcePushNegatable } from './matcher.js';
 import { minimatch } from 'minimatch';
 export function extractGitignore(source, content) {
     for (let line of content.toString().split('\n')) {
@@ -9,12 +10,7 @@ export function extractGitignore(source, content) {
         if (cdx >= 0) {
             line = line.substring(-cdx);
         }
-        if (line.startsWith('!')) {
-            source.pattern.include.push(line.substring(1));
-        }
-        else {
-            source.pattern.exclude.push(line);
-        }
+        sourcePushNegatable(source, line);
     }
     // TODO: validate gitignore
 }

package/out/patterns/matcher.d.ts

@@ -1,10 +1,41 @@
+/**
+ * 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;
 };
 /**
@@ -15,6 +46,8 @@ export declare function patternMatches(pattern: Pattern, path: string): boolean;
 /**
  * Represents a set of include and exclude patterns.
  * These patterns are positive minimatch patterns.
+ *
+ * @see {@link PatternMatcher}
  */
 export type SignedPattern = {
     include: Pattern;
@@ -22,18 +55,60 @@ export type SignedPattern = {
 };
 /**
  * Combined internal and external patterns for matching.
- * Used in {@link signedPatternIgnores} function.
+ *
+ * `exclude` patterns take precedence over `include` patterns.
+ *
+ * `internal` patterns take precedence over `external` patterns.
+ * @see {@link signedPatternIgnores}
  */
 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;
 };
+/**
+ * Adds a negatable pattern to the source's pattern lists.
+ * Strips the leading '!' for include patterns,
+ * and adds to exclude patterns otherwise.
+ */
+export declare function sourcePushNegatable(source: Source, pattern: string): void;
+/**
+ * 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

@@ -10,6 +10,21 @@ export function patternMatches(pattern, path) {
     }
     return false;
 }
+/**
+ * Adds a negatable pattern to the source's pattern lists.
+ * Strips the leading '!' for include patterns,
+ * and adds to exclude patterns otherwise.
+ */
+export function sourcePushNegatable(source, pattern) {
+    if (pattern.startsWith('!')) {
+        source.pattern.include.push(pattern.substring(1));
+        return;
+    }
+    source.pattern.exclude.push(pattern);
+}
+/**
+ * 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) {
@@ -74,6 +89,10 @@ export async function findAndExtract(directory, sources, matcher, ctx) {
         }
     }
 }
+/**
+ * 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);

package/out/patterns/packagejson.d.ts

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

package/out/patterns/packagejson.js

@@ -1,4 +1,5 @@
 import { type } from 'arktype';
+import { sourcePushNegatable, } from './matcher.js';
 const nodeJsManifest = type({
     files: 'string[]?',
 });
@@ -12,13 +13,8 @@ export function extractPackageJson(source, content) {
     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);
-        }
+    for (const pattern of dist.files) {
+        sourcePushNegatable(source, pattern);
     }
     return;
 }

package/out/scan.d.ts

@@ -11,7 +11,7 @@ export type ScanOptions = {
      */
     cwd?: string;
     /**
-     * If enabled, the scan will return files that are ignored by the target matchers.
+     * If enabled, the scan will return files that are ignored by the target matcher.
      */
     invert?: boolean;
     /**
@@ -24,8 +24,9 @@ export type ScanOptions = {
      */
     signal?: AbortSignal;
     /**
-     * If enabled, Depth will be calculated faster by skipping
-     * other files after first match.
+     * 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},
@@ -37,10 +38,12 @@ export type ScanOptions = {
 /**
  * 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..
+ * 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 map of targets to their matcher contexts.
+ * @returns A promise that resolves to a {@link MatcherContext} containing the scan results.
  */
 export declare function scan(options: ScanOptions): Promise<MatcherContext>;

package/out/scan.js

@@ -3,14 +3,19 @@ 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..
+ * 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 map of targets to their matcher contexts.
+ * @returns A promise that resolves to a {@link MatcherContext} containing the scan results.
  */
 export async function scan(options) {
     const { target, cwd: cwdo = (await import('node:process')).cwd(), depth: maxDepth = Infinity, invert = false, signal = undefined, fastDepth = false, } = options;
+    if (maxDepth < 0) {
+        throw new TypeError('Depth must be a non-negative integer');
+    }
     const cwd = cwdo.replaceAll('\\', '/');
     const ctx = {
         paths: new Set(),
@@ -22,9 +27,7 @@ export async function scan(options) {
         totalDirs: 0,
     };
     await opendir(cwd, async (entry) => {
-        if (signal?.aborted) {
-            return 2;
-        }
+        signal?.throwIfAborted();
         const path = posix.join(posix.relative(cwd, entry.parentPath.replaceAll('\\', '/')), entry.name);
         if (entry.isDirectory()) {
             ctx.totalDirs++;
@@ -77,16 +80,13 @@ export async function scan(options) {
         }
         return 0;
     });
-    if (signal?.aborted) {
-        return ctx;
-    }
+    signal?.throwIfAborted();
     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) {

package/out/targets/target.d.ts

@@ -1,4 +1,7 @@
 import type { PathChecker } from '../patterns/matcher.js';
+/**
+ * Contains the matcher used for target scanning.
+ */
 export interface Target {
     /**
      * Glob-pattern parser.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "view-ignored",
-  "version": "0.5.0",
+  "version": "0.5.2",
   "description": "Retrieve list of files ignored/included by Git, NPM, Yarn, JSR, VSCE or other tools.",
   "type": "module",
   "scripts": {