view-ignored 0.1.0 → 0.2.0

package/README.md

@@ -7,10 +7,10 @@ Retrieve list of files ignored/included by Git, NPM, Yarn and VSC Extension.
 
 ## Highlights
 
-- **Multi-target.** Get list of included files, using configuration files reader, not command line wrapper.
+- **Multi-target.** Get list of included files, using configuration files reader, not command-line wrapper.
 - **Use in browser.** view-ignored supports file system adapter.
-- **Command line.** Supports no-color and multiple output styles, including [nerd fonts](https://github.com/ryanoasis/nerd-fonts).
-- **Plugins.** view-ignored allows you to add new [targets](#targets) programmatically. Command line interface does NOT support plugins.
+- **Command-line.** Supports no-color and multiple output styles, 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 throught `--plugin` option.
 
 ## Install
 
@@ -20,7 +20,7 @@ npm i view-ignored
 
 ## Usage
 
-### Command line
+### Command-line
 
 ```bash
 # get started
@@ -31,86 +31,69 @@ view-ignored --help
 # scan: git (default) and npm
 viewig scan .
 viewig scan . --target=npm
+viewig scan . --parsable
 
-# config: print all
+# scan: plugins (space, comma or pipe separated)
+viewig scan . --plugins="vign-p-tsx, vign-p-jsdoc"
+viewig scan . --plugins="vign-p-tsx vign-p-jsdoc"
+viewig scan . --plugins vign-p-tsx vign-p-jsdoc
+viewig scan . --plugins vign-p-tsx, vign-p-jsdoc
+
+# config: print configuration entries
 viewig config get
-# config: print with defaults
-viewig config get --safe
+viewig config get --real
 # config: set npm as default target and scan for npm
 viewig config set target=npm
 viewig scan .
-# config: always use nerd font
-viewig config set style=treeNerd
+# config: always use nerdfonts
+viewig config set style=tree
+# config: always use nerdfonts
+viewig config set decor=nerdfonts
+# config: always use plugins
+viewig config set plugins=typescript-viewig,eslint-vign-plugin
 ```
 
 ### Programmatically
 
 ```js
 import * as vign from "view-ignored";
-import * as vign from "view-ignored/lib/browser"; // for web environment apps
+import * as vign from "view-ignored/out/src/browser"; // for web environment apps
 
-const fileInfoList = vign.scanProject("git");
-const fileInfoList = vign.scanPaths(pathList, "git");
-const fileInfo = vign.scanFile(pathToFile, "git");
+const fileInfoList = await vign.scanProject("git");
+const fileInfo = await vign.scanFile("./path/to/file", "git");
 
 // options available
-const fileInfoList = vign.scanProject("git", { cwd, ... });
-
-// custom
-/**@type {vign.ScanMethod}*/
-export const method = function (data) {
-  const { looker, sourceFile: source } = data
-  if (!looker.isValidPattern(source.content)) {
-      return false
-  }
-  looker.add(source.content)
-  return true
-}
-
-/**@type {vign.Source[]}*/
-export const sources = [
-  { sources: new SourcePattern("**/.gitignore"), patternType: ".*ignore", method, addPatterns: addPatternsExclude },
-]
-vign.scanProject(sources)
+const fileInfoList = await vign.scanProject("git", { cwd, ... });
 
 // use results
 if (fileInfo.ignored) {
-  vscode.explorer.colorFile(fileInfo.filePath, "gray")
+    superCodeEditor.explorer.colorFile(fileInfo.filePath, "gray");
 }
 ```
 
-#### Sorting:
+#### Sorting
 
 ```js
-const fileInfoList = vign.scanProject("npm");
-const sorter = vign.Sorting.Sorters.firstFolders;
-fileInfoList.map(String).sort(sorter);
+const sorter = vign.Sorting.firstFolders;
+const fileInfoList = await vign.scanProject("npm");
+const fileInfoSorted = fileInfoList.map(String).sort(sorter);
 ```
 
 ```js
-const fileInfoList = vign.scanProject("npm")
-const sorter = Sorting.Sorters[flags.sort]
-const cacheEditDates = new Map<FileInfo, Date>()
-for (const look of looked) {
-	cacheEditDates.set(look, fs.statSync(look.filePath).mtime)
-}
-const lookedSorted = looked.sort((a, b) => sorter(
-	a.toString(), b.toString(),
-	cacheEditDates.get(a)!, cacheEditDates.get(b)!
-))
+const sorter = vign.Sorting.modified;
+const fileInfoList = await vign.scanProject("npm");
+
+const cache = new Map<string, number>(fileInfoList.map(String).map(
+    filePath => [filePath, fs.statSync(filePath).mtime.getTime()])
+);
+const lookedSorted = fileInfoList.sort((a, b) => sorter(a.toString(), b.toString(), cache));
 ```
 
 ### Targets
 
 - `git`
-  - Test command: `git ls-tree -r <git-branch-name> --name-only`
-  - Sources walkthrough: '.gitignore' and git config `core.excludesFile`.
-  - `core.excludesFile` does not work at this moment.
 - `npm` (can be usable for PNPM and Bun)
-  - Test command: `npm pack --dry-run`
-  - Sources walkthrough: 'package.json'>"files" otherwise '.npmignore' otherwise '.gitignore'.
 - `yarn`
-  - Sources walkthrough: 'package.json'>"files" otherwise '.yarnignore' otherwise '.npmignore' otherwise '.gitignore'.
 - `vsce`
-  - Test command: `vsce ls`
-  - Sources walkthrough: '.vscodeignore'.
+- `jsr` *planned*
+- `deno` *planned*

package/bin/viewig

@@ -1,2 +1,2 @@
-#! /usr/bin/env node
-import "../lib/bin.js"
+#! /usr/bin/env node
+import "../out/src/bin.js"

package/out/src/bin.d.ts

@@ -0,0 +1,2 @@
+#! /usr/bin/env node
+export {};

package/out/src/bin.js

@@ -0,0 +1,3 @@
+#! /usr/bin/env node
+import { programInit } from "./cli.js";
+programInit();

package/out/src/browser/binds/index.d.ts

@@ -0,0 +1,45 @@
+import { TargetBind } from "./targets.js";
+export * from "./targets.js";
+/**
+ * The result of loading.
+ */
+export interface PluginLoaded {
+    moduleName: string;
+    isLoaded: boolean;
+    exports: unknown;
+}
+/**
+ * If a plugin wants to change something, it must export it as default.
+ */
+export interface PluginExport {
+    viewignored: {
+        addTargets: TargetBind[];
+    };
+}
+/**
+ * Checks if the value is the {@link PluginExport}.
+ */
+export declare function isPluginExport(value: unknown): value is PluginExport;
+/**
+ * Imports the plugin's exported data.
+ */
+export declare function importPlugin(exportData: PluginExport): void;
+/**
+ * No rejects.
+ * @param moduleName Plugin name.
+ * @returns Import result for the module.
+ */
+export declare function loadPlugin(moduleName: string): Promise<PluginLoaded>;
+/**
+ * Loads plugins one by one using {@link loadPlugin}.
+ * @param moduleNameList The list of plugins.
+ */
+export declare function loadPluginsQueue(moduleNameList?: string[]): Promise<PluginLoaded[]>;
+export declare const BuiltInGit: Promise<typeof import("./plugins/git.js")>;
+export declare const BuiltInVsce: Promise<typeof import("./plugins/vsce.js")>;
+export declare const BuiltInNpm: Promise<typeof import("./plugins/npm.js")>;
+export declare const BuiltInYarn: Promise<typeof import("./plugins/yarn.js")>;
+/**
+ * Built-in plugins loading queue.
+ */
+export declare const BuiltIns: Promise<[PromiseSettledResult<typeof import("./plugins/git.js")>, PromiseSettledResult<typeof import("./plugins/vsce.js")>, PromiseSettledResult<typeof import("./plugins/npm.js")>, PromiseSettledResult<typeof import("./plugins/yarn.js")>]>;

package/out/src/browser/binds/index.js

@@ -0,0 +1,78 @@
+import { isTargetBind, targetSet } from "./targets.js";
+import { loadPlugin as load } from "load-plugin";
+export * from "./targets.js";
+/**
+ * Checks if the value is the {@link PluginExport}.
+ */
+export function isPluginExport(value) {
+    if (value?.constructor !== Object) {
+        return false;
+    }
+    const vign = value.viewignored;
+    return (vign?.constructor === Object)
+        && 'addTargets' in vign && Array.isArray(vign.addTargets) && vign.addTargets.every(isTargetBind);
+}
+/**
+ * Imports the plugin's exported data.
+ */
+export function importPlugin(exportData) {
+    const { addTargets } = exportData.viewignored;
+    for (const targetBind of addTargets) {
+        targetSet(targetBind);
+    }
+}
+/**
+ * No rejects.
+ * @param moduleName Plugin name.
+ * @returns Import result for the module.
+ */
+export function loadPlugin(moduleName) {
+    try {
+        return new Promise((resolve) => {
+            load(moduleName)
+                .catch((reason) => {
+                const r = reason;
+                if (r?.code === 'ERR_MODULE_NOT_FOUND') {
+                    reason = r.message;
+                }
+                const fail = { moduleName, isLoaded: false, exports: reason };
+                resolve(fail);
+            })
+                .then((exports) => {
+                const result = { moduleName, isLoaded: true, exports };
+                if (isPluginExport(exports)) {
+                    importPlugin(exports);
+                }
+                resolve(result);
+            });
+        });
+    }
+    catch (reason) {
+        const fail = { moduleName, isLoaded: false, exports: reason };
+        return Promise.resolve(fail);
+    }
+}
+/**
+ * Loads plugins one by one using {@link loadPlugin}.
+ * @param moduleNameList The list of plugins.
+ */
+export async function loadPluginsQueue(moduleNameList) {
+    const resultList = [];
+    for (const module of moduleNameList ?? []) {
+        const result = await loadPlugin(module);
+        resultList.push(result);
+    }
+    return resultList;
+}
+export const BuiltInGit = import("./plugins/git.js");
+BuiltInGit.then(e => e.default).then(importPlugin);
+export const BuiltInVsce = import("./plugins/vsce.js");
+BuiltInVsce.then(e => e.default).then(importPlugin);
+export const BuiltInNpm = import("./plugins/npm.js");
+BuiltInNpm.then(e => e.default).then(importPlugin);
+export const BuiltInYarn = import("./plugins/yarn.js");
+BuiltInYarn.then(e => e.default).then(importPlugin);
+/**
+ * Built-in plugins loading queue.
+ */
+export const BuiltIns = Promise.allSettled([BuiltInGit, BuiltInVsce, BuiltInNpm, BuiltInYarn]);

package/out/src/browser/binds/plugins/git.d.ts

@@ -0,0 +1,3 @@
+import { Plugins } from "../../index.js";
+declare const _default: Plugins.PluginExport;
+export default _default;

package/out/src/browser/binds/plugins/git.js

@@ -0,0 +1,24 @@
+const id = "git";
+const name = {
+    ifNormal: "Git",
+    ifNerd: "\ue65d Git"
+};
+const testCommand = `git ls-tree -r <git-branch-name> --name-only`;
+const matcherExclude = [
+    ".git/**",
+    ".DS_Store/**"
+];
+const scan = function (fileInfo) {
+    const { scanner, content } = fileInfo;
+    const pat = content?.toString();
+    if (!scanner.patternIsValid(pat)) {
+        return false;
+    }
+    scanner.add(pat);
+    return true;
+};
+const methodology = [
+    { pattern: "**/.gitignore", matcher: "gitignore", scan, matcherExclude },
+];
+const bind = { id, name, methodology, testCommand };
+export default { viewignored: { addTargets: [bind] } };

package/out/src/browser/binds/plugins/npm.d.ts

@@ -0,0 +1,11 @@
+import { Plugins, ScanMethod, Methodology } from "../../index.js";
+export declare const id = "npm";
+export declare const name = "NPM";
+export declare const testCommand = "npm pack --dry-run";
+export declare const matcherExclude: string[];
+export declare const matcherInclude: string[];
+export declare const scanGit: ScanMethod;
+export declare const scanPackageJsonFiles: ScanMethod;
+export declare const methodology: Methodology[];
+declare const _default: Plugins.PluginExport;
+export default _default;

package/out/src/browser/binds/plugins/npm.js

@@ -0,0 +1,71 @@
+import getValue from "get-value";
+export const id = "npm";
+export const name = "NPM";
+export const testCommand = "npm pack --dry-run";
+export const matcherExclude = [
+    'node_modules/**',
+    '.*.swp',
+    '._*',
+    '.DS_Store/**',
+    '.git/**',
+    '.gitignore',
+    '.hg/**',
+    '.npmignore',
+    '.npmrc',
+    '.lock-wscript',
+    '.svn/**',
+    '.wafpickle-*',
+    'config.gypi',
+    'CVS/**',
+    'npm-debug.log',
+];
+export const matcherInclude = [
+    '/bin/',
+    '/package.json',
+    '/README',
+    '/README.*',
+    '/LICENSE',
+    '/LICENSE.*',
+    '/LICENCE',
+    '/LICENCE.*',
+];
+export const scanGit = function (data) {
+    const { scanner, content } = data;
+    const pat = content?.toString();
+    if (!scanner.patternIsValid(pat)) {
+        return false;
+    }
+    scanner.add(pat);
+    return true;
+};
+export const scanPackageJsonFiles = function (data) {
+    const { scanner, content } = data;
+    let parsed;
+    try {
+        const pat = content?.toString();
+        if (!pat) {
+            return false;
+        }
+        const json = JSON.parse(pat);
+        if (json?.constructor !== Object) {
+            return false;
+        }
+        parsed = json;
+    }
+    catch {
+        return false;
+    }
+    const propVal = getValue(parsed, "files");
+    if (!scanner.patternIsValid(propVal)) {
+        return false;
+    }
+    scanner.add(propVal);
+    return true;
+};
+export const methodology = [
+    { pattern: ["**/package.json"], matcherNegated: true, matcher: "gitignore", scan: scanPackageJsonFiles, matcherInclude, matcherExclude },
+    { pattern: ["**/.npmignore"], matcher: "gitignore", scan: scanGit, matcherInclude, matcherExclude },
+    { pattern: ["**/.gitignore"], matcher: "gitignore", scan: scanGit, matcherInclude, matcherExclude },
+];
+const bind = { id, name, methodology, testCommand };
+export default { viewignored: { addTargets: [bind] } };

package/out/src/browser/binds/plugins/vsce.d.ts

@@ -0,0 +1,9 @@
+import { Plugins, ScanMethod, Methodology } from "../../index.js";
+export declare const id = "vsce";
+export declare const name = "VSC Extension";
+export declare const testCommand = "vsce ls";
+export declare const matcherExclude: string[];
+export declare const scan: ScanMethod;
+export declare const methodology: Methodology[];
+declare const _default: Plugins.PluginExport;
+export default _default;

package/out/src/browser/binds/plugins/vsce.js

@@ -0,0 +1,21 @@
+export const id = "vsce";
+export const name = "VSC Extension";
+export const testCommand = "vsce ls";
+export const matcherExclude = [
+    ".git/**",
+    ".DS_Store/**"
+];
+export const scan = function (data) {
+    const { scanner, content } = data;
+    const pat = content?.toString();
+    if (!scanner.patternIsValid(pat)) {
+        return false;
+    }
+    scanner.add(pat);
+    return true;
+};
+export const methodology = [
+    { pattern: "**/.vscodeignore", matcher: "minimatch", scan, matcherExclude },
+];
+const bind = { id, name, methodology, testCommand };
+export default { viewignored: { addTargets: [bind] } };

package/out/src/browser/binds/plugins/yarn.d.ts

@@ -0,0 +1,16 @@
+import { Plugins, Methodology, ScanMethod } from "../../index.js";
+export declare const id = "yarn";
+export declare const name = "Yarn";
+/**
+ * [!WARNING] All patterns copied from npm plugin, so they should be verified with yarn docs.
+ */
+export declare const matcherExclude: string[];
+/**
+ * [!WARNING] All patterns copied from npm plugin, so they should be verified with yarn docs.
+ */
+export declare const matcherInclude: string[];
+export declare const scanGit: ScanMethod;
+export declare const scanPackageJsonFiles: ScanMethod;
+export declare const methodology: Methodology[];
+declare const _default: Plugins.PluginExport;
+export default _default;

package/out/src/browser/binds/plugins/yarn.js

@@ -0,0 +1,78 @@
+import getValue from "get-value";
+export const id = "yarn";
+export const name = "Yarn";
+/**
+ * [!WARNING] All patterns copied from npm plugin, so they should be verified with yarn docs.
+ */
+export const matcherExclude = [
+    'node_modules/**',
+    '.*.swp',
+    '._*',
+    '.DS_Store/**',
+    '.git/**',
+    '.gitignore',
+    '.hg/**',
+    '.yarnignore',
+    '.npmignore',
+    '.npmrc',
+    '.lock-wscript',
+    '.svn/**',
+    '.wafpickle-*',
+    'config.gypi',
+    'CVS/**',
+    'npm-debug.log',
+];
+/**
+ * [!WARNING] All patterns copied from npm plugin, so they should be verified with yarn docs.
+ */
+export const matcherInclude = [
+    '/bin/',
+    '/package.json',
+    '/README',
+    '/README.*',
+    '/LICENSE',
+    '/LICENSE.*',
+    '/LICENCE',
+    '/LICENCE.*',
+];
+export const scanGit = function (data) {
+    const { scanner, content } = data;
+    const pat = content?.toString();
+    if (!scanner.patternIsValid(pat)) {
+        return false;
+    }
+    scanner.add(pat);
+    return true;
+};
+export const scanPackageJsonFiles = function (data) {
+    const { scanner, content } = data;
+    let parsed;
+    try {
+        const pat = content?.toString();
+        if (!pat) {
+            return false;
+        }
+        const json = JSON.parse(pat);
+        if (json?.constructor !== Object) {
+            return false;
+        }
+        parsed = json;
+    }
+    catch {
+        return false;
+    }
+    const propVal = getValue(parsed, "files");
+    if (!scanner.patternIsValid(propVal)) {
+        return false;
+    }
+    scanner.add(propVal);
+    return true;
+};
+export const methodology = [
+    { pattern: "**/package.json", matcherNegated: true, matcher: "gitignore", scan: scanPackageJsonFiles, matcherInclude, matcherExclude },
+    { pattern: "**/.yarnignore", matcher: "gitignore", scan: scanGit, matcherInclude, matcherExclude },
+    { pattern: "**/.npmignore", matcher: "gitignore", scan: scanGit, matcherInclude, matcherExclude },
+    { pattern: "**/.gitignore", matcher: "gitignore", scan: scanGit, matcherInclude, matcherExclude },
+];
+const bind = { id, name, methodology };
+export default { viewignored: { addTargets: [bind] } };

package/out/src/browser/binds/targets.d.ts

@@ -0,0 +1,64 @@
+import { ScanFolderOptions, Methodology } from "../lib.js";
+import { DecorConditionOptions } from "../styling.js";
+/**
+ * Should satisfy RegExp: `/^[-a-zA-Z0-9]+$/`.
+ */
+export type TargetId = string;
+/**
+ * @param value Target's id. Simple name.
+ * @returns `true`, if the id is available for binding.
+ */
+export declare function isTargetId(value: unknown): value is TargetId;
+/**
+ * The bind which allows use predefined options for scan functions.
+ * @see {@link scanProject}
+ */
+export interface TargetBind {
+    /**
+     * Simple name.
+     * @see {@link isTargetId}
+     */
+    id: TargetId;
+    /**
+     * Readable name.
+     */
+    name: string | DecorConditionOptions;
+    /**
+     * The walkthrough. Files including patterns.
+     */
+    methodology: Methodology[];
+    /**
+     * Folder deep scanning options for the target.
+     */
+    scanOptions?: ScanFolderOptions;
+    /**
+     * Test command.
+     * @example
+     * "npm pack --dry run"
+     * "vsce ls"
+     */
+    testCommand?: string;
+}
+/**
+ * Checks if the value is the {@link TargetBind}.
+ */
+export declare function isTargetBind(value: unknown): value is TargetBind;
+/**
+ * Allows to create targets for view-ignored scan* functions.
+ * @example
+ * scanProject("abc") // error
+ * Bindings.targetSet("abc", {...})
+ * scanProject("abc") // ok
+ */
+export declare function targetSet(bind: TargetBind): void;
+/**
+ * Get all target ids.
+ * @example
+ * ["git", "npm", "vsce", ...]
+ */
+export declare function targetList(): string[];
+/**
+ * Get target bind by target id.
+ * @param id Target id.
+ */
+export declare function targetGet(id: TargetId): TargetBind | undefined;

package/out/src/browser/binds/targets.js

@@ -0,0 +1,56 @@
+// eslint-disable-next-line @typescript-eslint/no-unused-vars
+import { isMethodology } from "../lib.js";
+/**
+ * @param value Target's id. Simple name.
+ * @returns `true`, if the id is available for binding.
+ */
+export function isTargetId(value) {
+    return typeof value === "string" && value.match(/^[-a-zA-Z0-9]+$/) != null;
+}
+/**
+ * Checks if the value is the {@link TargetBind}.
+ */
+export function isTargetBind(value) {
+    if (value?.constructor !== Object) {
+        return false;
+    }
+    const v = value;
+    return (isTargetId(v.id))
+        && (typeof v.name === "string" || v.name?.constructor === Object)
+        && (Array.isArray(v.methodology) && v.methodology.every(isMethodology))
+        && (v.scanOptions === undefined || v.scanOptions?.constructor === Object)
+        && (v.testCommand === undefined || typeof v.testCommand === "string");
+}
+/**
+ * The container for binds: id=bind.
+ */
+const targetBindMap = new Map();
+/**
+ * Allows to create targets for view-ignored scan* functions.
+ * @example
+ * scanProject("abc") // error
+ * Bindings.targetSet("abc", {...})
+ * scanProject("abc") // ok
+ */
+export function targetSet(bind) {
+    if (!isTargetId(bind.id)) {
+        throw TypeError(`view-ignored can not bind target with id '${bind.id}'`);
+    }
+    targetBindMap.set(bind.id, bind);
+}
+/**
+ * Get all target ids.
+ * @example
+ * ["git", "npm", "vsce", ...]
+ */
+export function targetList() {
+    const list = Array.from(targetBindMap.keys());
+    return list;
+}
+/**
+ * Get target bind by target id.
+ * @param id Target id.
+ */
+export function targetGet(id) {
+    return targetBindMap.get(id);
+}

package/out/src/browser/errors.d.ts

@@ -0,0 +1,10 @@
+import { Methodology } from "../lib.js";
+export declare class SomeError extends Error {
+}
+export declare class ErrorNoSources extends SomeError {
+    constructor(sources?: (readonly Methodology[]) | string);
+    static walk(sources?: (readonly Methodology[]) | string): string;
+}
+export declare class ErrorTargetNotBound extends SomeError {
+    constructor(targetId: unknown);
+}

package/out/src/browser/errors.js

@@ -0,0 +1,20 @@
+import { targetGet } from "./binds/targets.js";
+export class SomeError extends Error {
+}
+export class ErrorNoSources extends SomeError {
+    constructor(sources) {
+        super("No available sources for methodology: " + ErrorNoSources.walk(sources));
+    }
+    static walk(sources) {
+        const s = typeof sources === "string" ? targetGet(sources)?.methodology : sources;
+        if (!s) {
+            return `bad bind for target '${s}'`;
+        }
+        return s.map(m => `'${m.pattern}'`).join(" -> ");
+    }
+}
+export class ErrorTargetNotBound extends SomeError {
+    constructor(targetId) {
+        super(`The target has no bound: '${targetId}'.`);
+    }
+}