linguist-js 2.9.2 → 3.0.0

package/ext/vendor.yml

@@ -165,3 +165,4 @@
 - (^|/)\.github/
 - (^|/)\.obsidian/
 - (^|/)\.teamcity/
+- (^|/)xvba_modules/

package/package.json

@@ -1,18 +1,19 @@
 {
 	"name": "linguist-js",
-	"version": "2.9.2",
-	"description": "Analyse languages used in a folder. Powered by GitHub Linguist, although it doesn't need to be installed.",
+	"version": "3.0.0",
+	"description": "Analyse the programming languages used in a folder or from raw content, using the same rules that GitHub Linguist does.",
 	"main": "dist/index.js",
+	"type": "module",
 	"bin": {
 		"linguist-js": "bin/index.js",
 		"linguist": "bin/index.js"
 	},
 	"engines": {
-		"node": ">=12",
-		"npm": ">=8"
+		"node": ">=26",
+		"npm": ">=10"
 	},
 	"scripts": {
-		"download-files": "npx tsx@3 build/download-files",
+		"download-files": "node build/download-files.ts",
 		"pre-publish": "npm run download-files && npm test && npm run perf",
 		"perf": "tsc && node test/perf",
 		"test": "tsc && node test/folder && node test/unit"
@@ -39,19 +40,19 @@
 	},
 	"homepage": "https://github.com/Nixinova/Linguist#readme",
 	"dependencies": {
-		"binary-extensions": "^2.3.0 <3",
-		"commander": "^9.5.0 <10",
+		"binary-extensions": "^3.1.0",
+		"commander": "^14.0.3",
 		"common-path-prefix": "^3.0.0",
-		"cross-fetch": "^3.2.0 <4",
-		"ignore": "^7.0.4",
-		"isbinaryfile": "^4.0.10 <5",
-		"js-yaml": "^4.1.0",
+		"ignore": "^7.0.5",
+		"isbinaryfile": "^6.0.0",
+		"js-yaml": "^4.1.1",
 		"node-cache": "^5.1.2"
 	},
 	"devDependencies": {
 		"@types/js-yaml": "^4.0.9",
-		"@types/node": "ts5.0",
+		"@types/node": "^25.9.1",
 		"deep-object-diff": "^1.1.9",
-		"typescript": "~5.0.4 <5.1"
+		"prettier": "^3.8.3",
+		"typescript": "~6.0.3"
 	}
 }

package/readme.md

@@ -29,7 +29,7 @@ linguist-js --help
 
 ## Usage
 
-LinguistJS contains one function which analyses a given folder or folders.
+LinguistJS analyses a folder, or a dictionary of already-read file content, and determines what programming languages are used within.
 
 As an example, take the following file structure:
 
@@ -38,89 +38,66 @@ As an example, take the following file structure:
 | src
 | | cli.js 1kB
 | | index.ts 2kB
-| readme.md 3kB
+| info.md 3kB
 | no-lang 10B
-| x.pluginspec 10B
 ```
 
-Running LinguistJS on this folder will return the following JSON:
+This may be represented in object form as a mapping of file path to file content.
+
+Running LinguistJS on this will return the following JSON:
 
 ```json
 {
   "files": {
-    "count": 5,
-    "bytes": 6020,
-    "lines": {
-        "total": 100,
-        "content": 90,
-        "code": 80,
-    },
+    "count": 4,
+    "bytes": 31,
+    "lines": { "total": 8, "content": 4, "code": 4 },
     "results": {
-      "/src/index.ts": "TypeScript",
-      "/src/cli.js": "JavaScript",
-      "/readme.md": "Markdown",
+      "/info.md": "Markdown",
       "/no-lang": null,
-      "/x.pluginspec": "Ruby",
-    },
-    "alternatives": {
-        "/x.pluginspec": ["XML"],
-    },
+      "/src/cli.js": "JavaScript",
+      "/src/index.ts": "TypeScript"
+    }
   },
   "languages": {
     "count": 3,
-    "bytes": 6010,
-    "lines": {
-        "total": 90,
-        "content": 80,
-        "code": 70,
-    },
+    "bytes": 18,
+    "lines": { "total": 6, "content": 3, "code": 3 },
     "results": {
-       "JavaScript": {
-            "type": "programming",
-            "bytes": 1000,
-            "lines": { "total": 49, "content": 49, "code": 44 },
-            "color": "#f1e05a"
-        },
-        "Markdown": {
-            "type": "prose",
-            "bytes": 3000,
-            "lines": { "total": 10, "content": 5, "code": 5 },
-            "color": "#083fa1"
-        },
-        "Ruby": {
-            "type": "programming",
-            "bytes": 10,
-            "lines": { "total": 1, "content": 1, "code": 1 },
-            "color": "#701516"
-        },
-        "TypeScript": {
-            "type": "programming",
-            "bytes": 2000,
-            "lines": { "total": 30, "content": 25, "code": 20 },
-            "color": "#2b7489"
-        },
-    },
+      "Markdown": {
+        "type": "prose",
+        "bytes": 6,
+        "lines": { "total": 2, "content": 1, "code": 1 },
+        "color": "#083fa1"
+      },
+      "JavaScript": {
+        "type": "programming",
+        "bytes": 6,
+        "lines": { "total": 2, "content": 1, "code": 1 },
+        "color": "#f1e05a"
+      },
+      "TypeScript": {
+        "type": "programming",
+        "bytes": 6,
+        "lines": { "total": 2, "content": 1, "code": 1 },
+        "color": "#3178c6"
+      }
+    }
   },
   "unknown": {
     "count": 1,
-    "bytes": 10,
-    "lines": {
-        "total": 10,
-        "content": 10,
-        "code": 10,
-    },
-    "filenames": {
-      "no-lang": 10,
-    },
+    "bytes": 13,
+    "lines": { "total": 2, "content": 1, "code": 1 },
     "extensions": {},
-  },
+    "filenames": { "no-lang": 13 }
+  }
 }
 ```
 
 ### Notes
 
 - File paths in the output use only forward slashes as delimiters, even on Windows.
-- Unless running in offline mode, do not rely on any language classification output from LinguistJS being unchanged between runs.
+- Unless running in offline mode: do not rely on any language classification output from LinguistJS being unchanged between runs.
   Language data is fetched each run from the latest classifications of [`github-linguist`](https://github.com/github/linguist).
   This data is subject to change at any time and may change the results of a run even when using the same version of Linguist.
 
@@ -129,75 +106,86 @@ Running LinguistJS on this folder will return the following JSON:
 ### Node
 
 ```js
-const linguist = require('linguist-js');
+import linguist from 'linguist-js';
 
 // Analyse folder on disc
-const folder = './src';
+const folders = ['./src'];
 const options = { keepVendored: false, quick: false };
-const { files, languages, unknown } = await linguist(folder, options);
+const { files, languages, unknown, repository } = await linguist.analyseFolders(folder, options);
 
 // Analyse file content from raw input
-const fileNames = ['file1.ts', 'file2.ts', 'ignoreme.js'];
-const fileContent = ['#!/usr/bin/env node', 'console.log("Example");', '"ignored"'];
-const options = { ignoredFiles: ['ignore*'] };
-const { files, languages, unknown } = await linguist(fileNames, { fileContent, ...options });
+const fileContent = {
+	['file1.ts']: '#!/usr/bin/env node',
+	['file2.ts']: 'console.log("Example");',
+	['ignoreme.js']: 'ignored!',
+}
+const options = { ignoredFiles: ['ignoreme.*'] };
+const { files, languages, unknown, repository } = await linguist.analyseRawContent(fileContent, options);
 ```
 
-- `linguist(entry?, opts?)` (default export):
+**Exports:**
+
+- `analyseFolders(folders?, opts?)`:
+  Analyse the language of all files found in a folder or folders.
+  - `folders` (optional; string array):
+    A list of folders to analyse (defaults to `['./']`).
+  - `opts` (optional; object):
+    An object containing analyser options.
+- `analyseRawContent(folders?, opts?)`:
   Analyse the language of all files found in a folder or folders.
   - `entry` (optional; string or string array):
-    The folder(s) to analyse (defaults to `./`).
+    A list of folders to analyse (defaults to `['./']`).
   - `opts` (optional; object):
     An object containing analyser options.
-    - `fileContent` (string or string array):
-      Provides the file content associated with the file name(s) given as `entry` to analyse instead of reading from a folder on disk.
-    - `ignoredFiles` (string array):
-      A list of file path globs to explicitly ignore.
-    - `ignoredLanguages` (string array):
-      A list of languages to ignore.
-    - `categories` (string array):
-      A list of programming language categories that should be included in the results.
-      Defaults to `['data', 'markup', 'programming', 'prose']`.
-    - `childLanguages` (boolean):
-      Whether to display sub-languages instead of their parents when possible (defaults to `false`).
-    - `quick` (boolean):
-      Whether to skip complex language analysis such as the checking of heuristics and gitattributes statements (defaults to `false`).
-      Alias for `checkAttributes:false, checkIgnored:false, checkDetected:false, checkHeuristics:false, checkShebang:false, checkModeline:false`.
-    - `offline` (boolean):
-      Whether to use pre-packaged metadata files instead of fetching them from GitHub at runtime (defaults to `false`).
-    - `calculateLines` (boolean):
-      Whether to calculate line of code totals (defaults to `true`).
-    - `keepVendored` (boolean):
-      Whether to keep vendored files (dependencies, etc) (defaults to `false`).
-      Does nothing when `fileContent` is set.
-    - `keepBinary` (boolean):
-      Whether binary files should be included in the output (defaults to `false`).
-    - `relativePaths` (boolean):
-      Change the absolute file paths in the output to be relative to the current working directory (defaults to `false`).
-    - `checkAttributes` (boolean):
-      Force the checking of `.gitattributes` files (defaults to `true` unless `quick` is set).
-      Does nothing when `fileContent` is set.
-    - `checkIgnored` (boolean):
-      Force the checking of `.gitignore` files (defaults to `true` unless `quick` is set).
-      Does nothing when `fileContent` is set.
-    - `checkDetected` (boolean):
-      Force files marked with `linguist-detectable` to show up in the output, even if the file is not part of the declared `categories`.
-    - `checkHeuristics` (boolean):
-      Apply heuristics to ambiguous languages (defaults to `true` unless `quick` is set).
-    - `checkShebang` (boolean):
-      Check shebang (`#!`) lines for explicit language classification (defaults to `true` unless `quick` is set).
-    - `checkModeline` (boolean):
-      Check modelines for explicit language classification (defaults to `true` unless `quick` is set).
+
+**Analyser options:**
+- `ignoredFiles` (string array):
+  A list of file path globs to explicitly ignore.
+- `ignoredLanguages` (string array):
+  A list of languages to ignore.
+- `categories` (string array):
+  A list of programming language categories that should be included in the results.
+  Defaults to `['data', 'markup', 'programming', 'prose']`.
+- `childLanguages` (boolean):
+  Whether to display sub-languages instead of their parents when possible (defaults to `false`).
+- `quick` (boolean):
+  Whether to skip complex language analysis such as the checking of heuristics and gitattributes statements (defaults to `false`).
+  Alias for `checkAttributes:false, checkIgnored:false, checkDetected:false, checkHeuristics:false, checkShebang:false, checkModeline:false`.
+- `offline` (boolean):
+  Whether to use pre-packaged metadata files instead of fetching them from GitHub at runtime (defaults to `false`).
+- `calculateLines` (boolean):
+  Whether to calculate line of code totals (defaults to `true`).
+- `keepVendored` (boolean):
+  Whether to keep vendored files (dependencies, etc) (defaults to `false`).
+  Does nothing when `fileContent` is set.
+- `keepBinary` (boolean):
+  Whether binary files should be included in the output (defaults to `false`).
+- `relativePaths` (boolean):
+  Change the absolute file paths in the output to be relative to the current working directory (defaults to `false`).
+- `checkAttributes` (boolean):
+  Force the checking of `.gitattributes` files (defaults to `true` unless `quick` is set).
+  Does nothing when `fileContent` is set.
+- `checkIgnored` (boolean):
+  Force the checking of `.gitignore` files (defaults to `true` unless `quick` is set).
+  Does nothing when `fileContent` is set.
+- `checkDetected` (boolean):
+  Force files marked with `linguist-detectable` to show up in the output, even if the file is not part of the declared `categories`.
+- `checkHeuristics` (boolean):
+  Apply heuristics to ambiguous languages (defaults to `true` unless `quick` is set).
+- `checkShebang` (boolean):
+  Check shebang (`#!`) lines for explicit language classification (defaults to `true` unless `quick` is set).
+- `checkModeline` (boolean):
+  Check modelines for explicit language classification (defaults to `true` unless `quick` is set).
 
 ### Command-line
 
 ```
-linguist --analyze [<folders...>] [<options...>]
+linguist --analyse [<folders...>] [<options...>]
 linguist --help
 linguist --version
 ```
 
-- `--analyze`:
+- `--analyse`:
   Analyse the language of all files found in a folder or folders.
   - `[<folders...>]`:
     The folders to analyse (defaults to `./`).