linguist-js 2.9.2 → 3.0.0

package/dist/program/classes/attributes.d.ts

@@ -0,0 +1,11 @@
+import { FileGlob, RelFile } from '../../types/types.js';
+import { FlagAttributes } from '../parsing/parseGitattributes.js';
+/** Stores parsed attribute information per file glob */
+export default class Attributes {
+    #private;
+    constructor();
+    get attributes(): Record<FileGlob, FlagAttributes>;
+    add(glob: FileGlob, attributes: FlagAttributes): void;
+    getFlaggedGlobs(attr: keyof FlagAttributes, val: boolean): string[];
+    findAttrsForPath(relFilePath: RelFile): FlagAttributes | null;
+}

package/dist/program/classes/attributes.js

@@ -0,0 +1,37 @@
+import ignore from 'ignore';
+/** Stores parsed attribute information per file glob */
+export default class Attributes {
+    #attributes;
+    constructor() {
+        this.#attributes = {};
+    }
+    get attributes() {
+        return this.#attributes;
+    }
+    add(glob, attributes) {
+        this.#attributes[glob] = attributes;
+    }
+    getFlaggedGlobs(attr, val) {
+        return Object.entries(this.#attributes)
+            .filter(([, attrs]) => attrs[attr] === val)
+            .map(([glob]) => glob);
+    }
+    findAttrsForPath(relFilePath) {
+        const resultAttrs = {};
+        for (const glob in this.#attributes) {
+            const matchingAttrs = this.#attributes[glob];
+            // Check if glob matches rel path
+            if (ignore().add(glob).ignores(relFilePath)) {
+                for (const [attr, val] of Object.entries(matchingAttrs)) {
+                    if (val != null) {
+                        resultAttrs[attr] = val;
+                    }
+                }
+            }
+        }
+        if (!JSON.stringify(resultAttrs).length) {
+            return null;
+        }
+        return resultAttrs;
+    }
+}

package/dist/program/data/loadDataFiles.d.ts

@@ -0,0 +1,4 @@
+/** Nukes unused `generated.rb` file content. */
+export declare function parseGeneratedDataFile(fileContent: string): string[];
+/** Load a data file from github-linguist. */
+export declare function loadFile(file: string, offline?: boolean): Promise<string>;

package/dist/program/data/loadDataFiles.js

@@ -0,0 +1,32 @@
+import Cache from 'node-cache';
+import FS from 'node:fs';
+import Path from 'node:path';
+import { fileURLToPath } from 'node:url';
+const cache = new Cache({});
+const dirname = Path.dirname(fileURLToPath(import.meta.url));
+async function loadWebFile(file) {
+    // Return cache if it exists
+    const cachedContent = cache.get(file);
+    if (cachedContent)
+        return cachedContent;
+    // Otherwise cache the request
+    const dataUrl = (file) => `https://raw.githubusercontent.com/github/linguist/HEAD/lib/linguist/${file}`;
+    // Load file content, falling back to the local file if the request fails
+    const fileContent = await fetch(dataUrl(file))
+        .then((data) => data.text())
+        .catch(async () => await loadLocalFile(file));
+    cache.set(file, fileContent);
+    return fileContent;
+}
+async function loadLocalFile(file) {
+    const filePath = Path.resolve(dirname, '../../../ext', file);
+    return FS.promises.readFile(filePath).then((buffer) => buffer.toString());
+}
+/** Nukes unused `generated.rb` file content. */
+export function parseGeneratedDataFile(fileContent) {
+    return [...(fileContent.match(/(?<=name\.match\(\/).+?(?=(?<!\\)\/)/gm) ?? [])];
+}
+/** Load a data file from github-linguist. */
+export function loadFile(file, offline = false) {
+    return offline ? loadLocalFile(file) : loadWebFile(file);
+}

package/dist/program/data/retrieveData.d.ts

@@ -0,0 +1,12 @@
+import { HeuristicsSchema, LanguagesScema, VendorSchema } from '../../types/schema.js';
+type LoadedData = {
+    langData: LanguagesScema;
+    vendorData: VendorSchema;
+    docData: VendorSchema;
+    heuristicsData: HeuristicsSchema;
+    generatedData: string[];
+    vendorPaths: string[];
+};
+/** Load data from github-linguist web repo or cached local file. */
+export default function retrieveData(offline: boolean): Promise<LoadedData>;
+export {};

package/dist/program/data/retrieveData.js

@@ -0,0 +1,27 @@
+import YAML from 'js-yaml';
+import { loadFile, parseGeneratedDataFile } from './loadDataFiles.js';
+let data = null;
+async function initRetrieveData(offline) {
+    // Only load the data on mont
+    if (data)
+        return;
+    const langData = (await loadFile('languages.yml', offline).then(YAML.load));
+    const vendorData = (await loadFile('vendor.yml', offline).then(YAML.load));
+    const docData = (await loadFile('documentation.yml', offline).then(YAML.load));
+    const heuristicsData = (await loadFile('heuristics.yml', offline).then(YAML.load));
+    const generatedData = (await loadFile('generated.rb', offline).then(parseGeneratedDataFile));
+    const vendorPaths = [...vendorData, ...docData, ...generatedData];
+    data = {
+        langData,
+        vendorData,
+        docData,
+        heuristicsData,
+        generatedData,
+        vendorPaths,
+    };
+}
+/** Load data from github-linguist web repo or cached local file. */
+export default async function retrieveData(offline) {
+    await initRetrieveData(offline);
+    return data;
+}

package/dist/program/fs/normalisedPath.d.ts

@@ -0,0 +1,3 @@
+export declare const normPath: (...inputPaths: string[]) => string;
+export declare const normAbsPath: (...inputPaths: string[]) => string;
+export declare const getFileExtension: (filePath: string) => string;

package/dist/program/fs/normalisedPath.js

@@ -0,0 +1,17 @@
+import Path from 'node:path';
+export const normPath = function normalisedPath(...inputPaths) {
+    return Path.join(...inputPaths).replace(/\\/g, '/');
+};
+export const normAbsPath = function normalisedAbsolutePath(...inputPaths) {
+    return Path.resolve(...inputPaths).replace(/\\/g, '/');
+};
+export const getFileExtension = function getFileExtension(filePath) {
+    const extension = Path.extname(filePath).toLowerCase();
+    if (extension)
+        return extension;
+    const basename = Path.basename(filePath);
+    if (basename.startsWith('.') && basename.length > 1 && basename.indexOf('.', 1) === -1) {
+        return basename.toLowerCase();
+    }
+    return '';
+};

package/dist/program/fs/readFile.js

@@ -0,0 +1,17 @@
+import FS from 'node:fs';
+/**
+ * Read part of a file on disc.
+ * @throws 'EPERM' if the file is not readable.
+ */
+export default async function readFileChunk(filename, onlyFirstLine = false) {
+    const chunkSize = 100;
+    const stream = FS.createReadStream(filename, { highWaterMark: chunkSize });
+    let content = '';
+    for await (const data of stream) { // may throw
+        content += data.toString();
+        if (onlyFirstLine) {
+            return content.split(/\r?\n/)[0];
+        }
+    }
+    return content;
+}

package/dist/program/fs/walkTree.d.ts

@@ -0,0 +1,20 @@
+import { Ignore } from 'ignore';
+interface WalkInput {
+    /** Whether this is walking the tree from the root */
+    init: boolean;
+    /** The common root absolute path of all folders being checked */
+    commonRoot: string;
+    /** The absolute path that each folder is relative to */
+    folderRoots: string[];
+    /** The absolute path of folders being checked */
+    folders: string[];
+    /** An instantiated Ignore object listing ignored files */
+    ignored: Ignore;
+}
+interface WalkOutput {
+    files: string[];
+    folders: string[];
+}
+/** Generate list of files in a directory. */
+export default function walkTree(data: WalkInput): WalkOutput;
+export {};

package/dist/program/fs/walkTree.js

@@ -0,0 +1,82 @@
+import FS from 'node:fs';
+import Path from 'node:path';
+import parseGitignore from '../parsing/parseGitignore.js';
+import { normAbsPath, normPath } from './normalisedPath.js';
+let allFiles;
+let allFolders;
+/** Generate list of files in a directory. */
+export default function walkTree(data) {
+    const { init, commonRoot, folderRoots, folders, ignored } = data;
+    // Initialise files and folders lists
+    if (init) {
+        allFiles = new Set();
+        allFolders = new Set();
+    }
+    // Walk tree of a folder
+    if (folders.length === 1) {
+        const folder = folders[0];
+        const localRoot = folderRoots[0].replace(commonRoot, '').replace(/^\//, '');
+        // Get list of files and folders inside this folder
+        const files = FS.readdirSync(folder).map((file) => {
+            // Create path relative to root
+            const base = normAbsPath(folder, file).replace(commonRoot, '.');
+            // Add trailing slash to mark directories
+            const isDir = FS.lstatSync(Path.resolve(commonRoot, base)).isDirectory();
+            return isDir ? `${base}/` : base;
+        });
+        // Read and apply gitignores
+        const gitignoreFilename = normPath(folder, '.gitignore');
+        if (FS.existsSync(gitignoreFilename)) {
+            const gitignoreContents = FS.readFileSync(gitignoreFilename, 'utf-8');
+            const ignoredPaths = parseGitignore(gitignoreContents);
+            const rootRelIgnoredPaths = ignoredPaths.map((ignorePath) => 
+            // get absolute path of the ignore glob
+            normPath(folder, ignorePath)
+                // convert abs ignore glob to be relative to the root folder
+                .replace(commonRoot + '/', ''));
+            ignored.add(rootRelIgnoredPaths);
+        }
+        // Add gitattributes if present
+        const gitattributesPath = normPath(folder, '.gitattributes');
+        if (FS.existsSync(gitattributesPath)) {
+            allFiles.add(gitattributesPath);
+        }
+        // Loop through files and folders
+        for (const file of files) {
+            // Create absolute path for disc operations
+            const path = normAbsPath(commonRoot, file);
+            const localPath = localRoot ? file.replace(`./${localRoot}/`, '') : file.replace('./', '');
+            // Skip if nonexistant
+            const nonExistant = !FS.existsSync(path);
+            if (nonExistant)
+                continue;
+            // Skip if marked in gitignore
+            const isIgnored = ignored.test(localPath).ignored;
+            if (isIgnored)
+                continue;
+            // Add absolute folder path to list
+            allFolders.add(normAbsPath(folder));
+            // Check if this is a folder or file
+            if (file.endsWith('/')) {
+                // Recurse into subfolders
+                allFolders.add(path);
+                walkTree({ init: false, commonRoot, folderRoots, folders: [path], ignored });
+            }
+            else {
+                // Add file path to list
+                allFiles.add(path);
+            }
+        }
+    }
+    // Recurse into all folders
+    else {
+        for (const i in folders) {
+            walkTree({ init: false, commonRoot, folderRoots: [folderRoots[i]], folders: [folders[i]], ignored });
+        }
+    }
+    // Return absolute files and folders lists
+    return {
+        files: [...allFiles].map((file) => file.replace(/^\./, commonRoot)),
+        folders: [...allFolders],
+    };
+}

package/dist/program/parsing/parseGitattributes.d.ts

@@ -0,0 +1,17 @@
+import * as T from '../../types/types.js';
+export type FlagAttributes = {
+    'vendored': boolean | null;
+    'generated': boolean | null;
+    'documentation': boolean | null;
+    'detectable': boolean | null;
+    'binary': boolean | null;
+    'language': T.LanguageResult;
+};
+export type ParsedGitattributes = Array<{
+    glob: T.FileGlob;
+    attrs: FlagAttributes;
+}>;
+/**
+ * Parses a gitattributes file.
+ */
+export default function parseGitattributes(content: string, folderRoot?: string): ParsedGitattributes;

package/dist/program/parsing/parseGitattributes.js

@@ -0,0 +1,33 @@
+import { normPath } from '../fs/normalisedPath.js';
+/**
+ * Parses a gitattributes file.
+ */
+export default function parseGitattributes(content, folderRoot = '.') {
+    const output = [];
+    for (const rawLine of content.split('\n')) {
+        const line = rawLine.replace(/#.*/, '').trim();
+        if (!line)
+            continue;
+        const parts = line.split(/\s+/g);
+        const fileGlob = parts[0];
+        const relFileGlob = normPath(folderRoot, fileGlob);
+        const attrParts = parts.slice(1);
+        const isTrue = (str) => !str.startsWith('-') && !str.endsWith('=false');
+        const isFalse = (str) => str.startsWith('-') || str.endsWith('=false');
+        const trueParts = (str) => attrParts.filter(part => part.includes(str) && isTrue(part));
+        const falseParts = (str) => attrParts.filter(part => part.includes(str) && isFalse(part));
+        const hasTrueParts = (str) => trueParts(str).length > 0;
+        const hasFalseParts = (str) => falseParts(str).length > 0;
+        const boolOrNullVal = (str) => hasTrueParts(str) ? true : hasFalseParts(str) ? false : null;
+        const attrs = {
+            'generated': boolOrNullVal('linguist-generated'),
+            'vendored': boolOrNullVal('linguist-vendored'),
+            'documentation': boolOrNullVal('linguist-documentation'),
+            'detectable': boolOrNullVal('linguist-detectable'),
+            'binary': hasTrueParts('binary') || hasFalseParts('text') ? true : hasFalseParts('binary') || hasTrueParts('text') ? false : null,
+            'language': trueParts('linguist-language').at(-1)?.split('=')[1] ?? null,
+        };
+        output.push({ glob: relFileGlob, attrs });
+    }
+    return output;
+}

package/dist/program/parsing/parseGitignore.js

@@ -0,0 +1,9 @@
+export default function parseGitignore(content) {
+    const readableData = content
+        // Remove comments unless escaped
+        .replace(/(?<!\\)#.+/g, '')
+        // Remove whitespace unless escaped
+        .replace(/(?:(?<!\\)\s)+$/g, '');
+    const arrayData = readableData.split(/\r?\n/).filter(data => data);
+    return arrayData;
+}

package/dist/program/processFiles.d.ts

@@ -0,0 +1,9 @@
+import * as T from '../types/types.js';
+import Attributes from './classes/attributes.js';
+type ProcessFilesResult = {
+    files: T.AbsFile[];
+    manualAttributes: Attributes;
+    relPath(file: T.AbsFile): T.RelFile;
+};
+export default function processFiles(input: string[], opts: T.Options, useRawContent: boolean, vendorPaths: string[]): Promise<ProcessFilesResult>;
+export {};

package/dist/program/processFiles.js

@@ -0,0 +1,111 @@
+import commonPrefix from 'common-path-prefix';
+import ignore from 'ignore';
+import FS from 'node:fs';
+import Path from 'node:path';
+import Attributes from './classes/attributes.js';
+import { normPath } from './fs/normalisedPath.js';
+import readFileChunk from './fs/readFile.js';
+import walkTree from './fs/walkTree.js';
+import parseGitattributes from './parsing/parseGitattributes.js';
+const binaryData = JSON.parse(FS.readFileSync(new URL('../../node_modules/binary-extensions/binary-extensions.json', import.meta.url), 'utf-8'));
+export default async function processFiles(input, opts, useRawContent, vendorPaths) {
+    // Set a common root path so that vendor paths do not incorrectly match parent folders
+    const resolvedInput = input.map((path) => normPath(Path.resolve(path)));
+    const commonRoot = (input.length > 1 ? commonPrefix(resolvedInput) : resolvedInput[0]).replace(/\/?$/, '');
+    const relPath = (file) => (useRawContent ? file : normPath(Path.relative(commonRoot, file)));
+    const unRelPath = (file) => (useRawContent ? file : normPath(Path.resolve(commonRoot, file)));
+    // Other helper functions
+    const filterOutIgnored = (files, ignored) => ignored.filter(files.map((file) => relPath(file))).map((file) => unRelPath(file));
+    //*PREPARE FILES AND DATA*//
+    // Prepare list of ignored files
+    const ignored = ignore();
+    ignored.add('.git/');
+    ignored.add(opts.ignoredFiles ?? []);
+    const regexIgnores = opts.keepVendored ? [] : vendorPaths.map((path) => RegExp(path, 'i'));
+    // Load file paths and folders
+    let files;
+    if (useRawContent) {
+        // Uses raw file content
+        files = input;
+    }
+    else {
+        // Uses directory on disc
+        const data = walkTree({ init: true, commonRoot, folderRoots: resolvedInput, folders: resolvedInput, ignored });
+        files = data.files;
+    }
+    // Fetch and normalise gitattributes data of all subfolders and save to metadata
+    const manualAttributes = new Attributes();
+    if (!useRawContent && opts.checkAttributes) {
+        const nestedAttrFiles = files.filter((file) => file.endsWith('.gitattributes'));
+        for (const attrFile of nestedAttrFiles) {
+            const relAttrFile = relPath(attrFile);
+            const relAttrFolder = Path.dirname(relAttrFile);
+            const contents = await readFileChunk(attrFile);
+            const parsed = parseGitattributes(contents, relAttrFolder);
+            for (const { glob, attrs } of parsed) {
+                manualAttributes.add(glob, attrs);
+            }
+        }
+    }
+    // Remove files that are linguist-ignored via regex by default unless explicitly unignored in gitattributes
+    const filesToIgnore = [];
+    for (const file of files) {
+        const relFile = relPath(file);
+        const isRegexIgnored = regexIgnores.some((pattern) => pattern.test(relFile));
+        if (!isRegexIgnored) {
+            // Checking overrides is moot if file is not even marked as ignored by default
+            continue;
+        }
+        const fileAttrs = manualAttributes.findAttrsForPath(relPath(file));
+        if (fileAttrs?.generated === false || fileAttrs?.vendored === false) {
+            // File is explicitly marked as *not* to be ignored
+            // do nothing
+        }
+        else {
+            filesToIgnore.push(file);
+        }
+    }
+    files = files.filter((file) => !filesToIgnore.includes(file));
+    // Apply vendor file path matches and filter out vendored files
+    if (!opts.keepVendored) {
+        // Get data of files that have been manually marked with metadata
+        const vendorTrueGlobs = [
+            ...manualAttributes.getFlaggedGlobs('vendored', true),
+            ...manualAttributes.getFlaggedGlobs('generated', true),
+            ...manualAttributes.getFlaggedGlobs('documentation', true),
+        ];
+        const vendorFalseGlobs = [
+            ...manualAttributes.getFlaggedGlobs('vendored', false),
+            ...manualAttributes.getFlaggedGlobs('generated', false),
+            ...manualAttributes.getFlaggedGlobs('documentation', false),
+        ];
+        // Set up glob ignore object to use for expanding globs to match files
+        const vendorTrueIgnore = ignore().add(vendorTrueGlobs);
+        const vendorFalseIgnore = ignore().add(vendorFalseGlobs);
+        // Remove all files marked as vendored by default
+        const excludedFiles = files.filter((file) => vendorPaths.some((pathPtn) => RegExp(pathPtn, 'i').test(relPath(file))));
+        files = files.filter((file) => !excludedFiles.includes(file));
+        // Re-add removed files that are overridden manually in gitattributes
+        const overriddenExcludedFiles = excludedFiles.filter((file) => vendorFalseIgnore.ignores(relPath(file)));
+        files.push(...overriddenExcludedFiles);
+        // Remove files explicitly marked as vendored in gitattributes
+        files = files.filter((file) => !vendorTrueIgnore.ignores(relPath(file)));
+    }
+    // Filter out binary files
+    if (!opts.keepBinary) {
+        // Filter out files that are binary by default
+        files = files.filter((file) => !binaryData.some((ext) => file.endsWith('.' + ext)));
+        // Filter out manually specified binary files
+        const binaryIgnored = ignore().add(manualAttributes.getFlaggedGlobs('binary', true));
+        files = filterOutIgnored(files, binaryIgnored);
+        // Re-add files manually marked not as binary
+        const binaryUnignored = ignore().add(manualAttributes.getFlaggedGlobs('binary', false));
+        const unignoredList = filterOutIgnored(files, binaryUnignored);
+        files.push(...unignoredList);
+    }
+    return {
+        files,
+        manualAttributes,
+        relPath,
+    };
+}

package/dist/program/utils/pcre.js

@@ -0,0 +1,35 @@
+/** Convert a PCRE regex into JS. */
+export default function pcre(regex) {
+    let finalRegex = regex;
+    const replace = (search, replace) => finalRegex = finalRegex.replace(search, replace);
+    const finalFlags = new Set();
+    // Convert inline flag declarations
+    const inlineMatches = regex.matchAll(/\?(-)?([a-z]):/g);
+    const startMatches = regex.matchAll(/\(\?(-)?([a-z]+)\)/g);
+    for (const [match, isNegative, flags] of [...inlineMatches, ...startMatches]) {
+        replace(match, '');
+        const func = (flag) => isNegative ? finalFlags.delete(flag) : finalFlags.add(flag);
+        [...flags].forEach(func);
+    }
+    // Remove PCRE-only syntax
+    replace(/([*+]){2}/g, '$1');
+    replace(/\(\?>/g, '(?:');
+    // Remove start/end-of-file markers
+    if (/\\[AZ]/.test(finalRegex)) {
+        replace(/\\A/g, '^');
+        replace(/\\Z/g, '$');
+        finalFlags.delete('m');
+    }
+    else {
+        finalFlags.add('m');
+    }
+    // Reformat free-spacing mode
+    if (finalFlags.has('x')) {
+        finalFlags.delete('x');
+        replace(/#.+/g, '');
+        replace(/^\s+|\s+$|\n/gm, '');
+        replace(/\s+/g, ' ');
+    }
+    // Return final regex
+    return RegExp(finalRegex, [...finalFlags].join(''));
+}

package/dist/src/cli/output/default.d.ts

@@ -0,0 +1,3 @@
+import { OptionValues } from 'commander';
+import { Results } from '../../types/types.js';
+export default function defaultOutput(args: OptionValues, data: Results): Promise<void>;

package/dist/src/cli/output/default.js

@@ -0,0 +1,106 @@
+import FS from 'node:fs';
+import Path from 'node:path';
+import { normPath } from '../../program/fs/normalisedPath.js';
+import { colouredMsg, hexToRgb } from '../utils.js';
+export default async function defaultOutput(args, data) {
+    const { files, languages, unknown, repository } = data;
+    if (args.minSize) {
+        // Ignore languages with a bytes/% size less than the declared min size
+        const totalSize = languages.bytes;
+        const minSizeAmt = parseFloat(args.minSize.replace(/[a-z]+$/i, '')); // '2KB' -> 2
+        const minSizeUnit = args.minSize.replace(/^\d+/, '').toLowerCase(); // '2KB' -> 'kb'
+        const checkBytes = minSizeUnit !== 'loc'; // whether to check bytes or loc
+        const conversionFactors = {
+            ['b']: (n) => n,
+            ['kb']: (n) => n * 1e3,
+            ['mb']: (n) => n * 1e6,
+            ['%']: (n) => (n * totalSize) / 100,
+            ['loc']: (n) => n,
+        };
+        const minBytesSize = conversionFactors[minSizeUnit](+minSizeAmt);
+        const other = { count: 0, bytes: 0, lines: { total: 0, content: 0, code: 0 } };
+        // Apply specified minimums: delete language results that do not reach the threshold
+        for (const [lang, data] of Object.entries(languages.results)) {
+            const checkUnit = checkBytes ? data.bytes : data.lines.content;
+            if (checkUnit < minBytesSize) {
+                // Add to 'other' count
+                other.count++;
+                other.bytes += data.bytes;
+                other.lines.total += data.lines.total;
+                other.lines.content += data.lines.content;
+                // Remove language result
+                delete languages.results[lang];
+            }
+        }
+        if (other.bytes) {
+            languages.results['Other'] = other;
+        }
+    }
+    const sortedEntries = Object.entries(languages.results).sort((a, b) => (a[1].bytes < b[1].bytes ? +1 : -1));
+    const totalBytes = languages.bytes;
+    console.log(`\n Analysed ${files.bytes.toLocaleString()} B from ${files.count} files with linguist-js`);
+    console.log(`\n Language analysis results: \n`);
+    let count = 0;
+    if (sortedEntries.length === 0)
+        console.log(`  None`);
+    // Collate files per language
+    const filesPerLanguage = {};
+    if (args.listFiles) {
+        for (const language of Object.keys(languages.results)) {
+            filesPerLanguage[language] = [];
+        }
+        for (const [file, lang] of Object.entries(files.results)) {
+            if (lang) {
+                filesPerLanguage[lang].push(file);
+            }
+        }
+    }
+    // List parsed results
+    for (const [lang, { bytes, lines }] of sortedEntries) {
+        const colour = hexToRgb(repository[lang].color ?? '#ededed');
+        const percent = (bytes) => (bytes / (totalBytes || 1)) * 100;
+        const fmtd = {
+            index: (++count).toString().padStart(2, ' '),
+            lang: lang.padEnd(24, ' '),
+            percent: percent(bytes).toFixed(2).padStart(5, ' '),
+            bytes: bytes.toLocaleString().padStart(10, ' '),
+            loc: lines.content.toLocaleString().padStart(10, ' '),
+            icon: colouredMsg(colour, '\u2588'),
+        };
+        console.log(`  ${fmtd.index}. ${fmtd.icon} ${fmtd.lang} ${fmtd.percent}% ${fmtd.bytes} B ${fmtd.loc} LOC`);
+        // If using `listFiles` option, list all files tagged as this language
+        if (args.listFiles) {
+            console.log(); // padding
+            for (const file of filesPerLanguage[lang]) {
+                let relFile = normPath(Path.relative(Path.resolve('.'), file));
+                if (!relFile.startsWith('../')) {
+                    relFile = './' + relFile;
+                }
+                const fileStat = await FS.promises.stat(file);
+                const bytes = fileStat.size;
+                const fmtd2 = {
+                    file: relFile.padEnd(42, ' '),
+                    percent: percent(bytes).toFixed(2).padStart(5, ' '),
+                    bytes: bytes.toLocaleString().padStart(10, ' '),
+                };
+                console.log(`        ${fmtd.icon} ${fmtd2.file}  ${fmtd2.percent}% ${fmtd2.bytes} B`);
+            }
+            console.log(); // padding
+        }
+    }
+    if (!args.listFiles) {
+        console.log(); // padding
+    }
+    console.log(` Total: ${totalBytes.toLocaleString()} B`);
+    // List unknown files/extensions
+    if (unknown.bytes > 0) {
+        console.log(`\n Unknown files and extensions:`);
+        for (const [name, bytes] of Object.entries(unknown.filenames)) {
+            console.log(`  '${name}': ${bytes.toLocaleString()} B`);
+        }
+        for (const [ext, bytes] of Object.entries(unknown.extensions)) {
+            console.log(`  '*${ext}': ${bytes.toLocaleString()} B`);
+        }
+        console.log(` Total: ${unknown.bytes.toLocaleString()} B`);
+    }
+}

package/dist/src/cli/output/tree.d.ts

@@ -0,0 +1,3 @@
+import { OptionValues } from 'commander';
+import { Results } from '../../types/types.js';
+export default function treeOutput(args: OptionValues, data: Results): void;

package/dist/src/cli/output/tree.js

@@ -0,0 +1,11 @@
+export default function treeOutput(args, data) {
+    const treeParts = args.tree.split('.');
+    let nestedData = data;
+    for (const part of treeParts) {
+        if (!nestedData[part]) {
+            throw Error(`TraversalError: Key '${part}' cannot be found on output object.`);
+        }
+        nestedData = nestedData[part];
+    }
+    console.log(nestedData);
+}

package/dist/src/cli/runCliAnalysis.d.ts

@@ -0,0 +1,2 @@
+import { OptionValues } from 'commander';
+export default function runCliAnalysis(args: OptionValues): Promise<void>;

package/dist/src/cli/runCliAnalysis.js

@@ -0,0 +1,25 @@
+import linguist from '../index.js';
+import defaultOutput from './output/default.js';
+import treeOutput from './output/tree.js';
+const validCategories = ['data', 'programming', 'prose', 'markup'];
+export default async function runCliAnalysis(args) {
+    // Check arguments
+    if (args.categories?.some((category) => !validCategories.includes(category))) {
+        console.log(`Error: '${args.categories.join(', ')}' contains an invalid category.`);
+        console.log(`\tValid options: ${validCategories.join(', ')}.`);
+        return;
+    }
+    // Fetch language data
+    const root = args.analyze === true ? '.' : args.analyze;
+    const data = await linguist(root, args);
+    // Print output
+    if (!args.json) {
+        defaultOutput(args, data);
+    }
+    else if (args.tree) {
+        treeOutput(args, data);
+    }
+    else {
+        console.dir(data, { depth: null });
+    }
+}