view-ignored

Retrieve list of files ignored/included by Git, NPM, Yarn, JSR, VSCE or other tools.

Requirements

Node.js 18 or later

Highlights

• Reader. Get a list of included files using configuration file readers, not command-line wrappers.
• Plugins. Built-in targets for popular tools. Use custom targets by implementing/extending the Target interface.
• Streaming. Native scanStream support for processing massive file trees with minimal memory overhead.
• Execution Control. Use fastDepth and fastInternal options to fine-tune traversal depth and skip unnecessary directory checks.
• Abortable. Full support for AbortSignal to cancel long-running scans instantly.
• 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", 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

Basic example

import * as vign from "view-ignored"
import { Git as target } from "view-ignored/targets"

const ctx = await vign.scan({ target })
ctx.paths.has(".git/HEAD") // false
ctx.paths.has("src") // true

const match = ctx.paths.get("src")
if (match.kind === "external") {
	console.log(match.source.path) // ".gitignore"
	console.log(match.pattern) // "src/**"
}

Using custom target

import {
	type Extractor,
	extractGitignore,
	ruleTest,
	ruleCompile,
	type Rule,
} 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: Rule[] = [
	ruleCompile({
		excludes: true,
		pattern: [".git", ".DS_Store"],
		compiled: null,
	}),
]

export const Git: Target = {
	internalRules: internal,
	extractors,
	root: "/",
	// TODO: Git should read configs
	init() {},
	ignores: ruleTest,
}

const ctx = await vign.scan({ target })

Streaming results

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
})
stream.start() // important

Browser and custom FS

To avoid imports from node:fs and node:process modules, use the browser submodule, which requires some additional options.

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

The following built-in scanners are available:

• Git (implementation)
  • 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.
• NPM (implementation)
  • Expecting to be compatible with PNPM, and others.
  • Validates package.json.
  • Reads package.json files field, .npmignore and .gitignore.
  • Starts searching from . (current working directory).
  • Check this scanner by running npm pack --dry-run.
• Bun (implementation)
  • Bun tries to mimic NPM, but that does not mean it behaves the same way.
  • Check this scanner by running bun pm pack --dry-run.
• Yarn (implementation)
  • Modern Berry behavior.
  • Validates package.json.
  • Reads package.json files field, .npmignore and .gitignore.
  • Requires package.json: includes paths from main, module, browser and bin.
  • Starts searching from . (current working directory).
  • YarnClassic is available. (implementation)
• VSCE (implementation)
  • Validates package.json.
  • Reads package.json files field, .vscodeignore and .gitignore.
  • Starts searching from . (current working directory).
  • Check this scanner by running vsce ls.
• JSR (implementation)
  • Validates and reads jsr.json(c) include and exclude fields.
  • Starts searching from . (current working directory).
• Deno (implementation)
  • Validates and reads jsr.json(c) and deno.json(c) include and exclude fields.
  • Starts searching from . (current working directory).

See also

• https://jsr.io/@m234/path - Utility to sort, convert and format paths.

License

MIT License. See LICENSE.txt for details.