view-ignored 0.5.0 → 0.5.1

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/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;
 };
 /**
@@ -28,12 +59,44 @@ 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

@@ -10,6 +10,9 @@ export function patternMatches(pattern, path) {
     }
     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) {
@@ -74,6 +77,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/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,11 +3,13 @@ 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;
@@ -86,7 +88,6 @@ export async function scan(options) {
         }
         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.1",
   "description": "Retrieve list of files ignored/included by Git, NPM, Yarn, JSR, VSCE or other tools.",
   "type": "module",
   "scripts": {