@azerion/bunosaurus-glob 0.0.0-stage → 4.0.0

package/README.md

@@ -1,3 +1,5 @@
-# Temporary Holding Version
+# `@docusaurus/glob`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+File globbing, glob matching and file watching utilities for Docusaurus packages.
+
+This package is mostly designed for internal usage and is undocumented. Its APIs should remain mostly retro-compatible within a major version.

package/lib/globUtils.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import * as Tinyglobby from 'tinyglobby';
+/**
+ * Our own glob options: we only expose the options we actually use, so that
+ * we can swap the underlying lib (e.g. for Node.js native `fs.glob`).
+ */
+export type GlobOptions = Pick<Tinyglobby.GlobOptions, 'cwd' | 'ignore' | 'absolute'>;
+/** Finds the files matching the given glob patterns. */
+export declare function glob(patterns: string | string[], options?: GlobOptions): Promise<string[]>;
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
+export declare const GlobExcludeDefault: string[];
+type Matcher = (str: string) => boolean;
+/**
+ * Creates a matcher that tells if a path is matched by any of the patterns.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns. If the list is empty, it defaults to
+ * matching none.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
+export declare function createMatcher(patterns: string[]): Matcher;
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
+export declare function createAbsoluteFilePathMatcher(patterns: string[], rootFolders: string[]): Matcher;
+export declare function safeGlob(patterns: string[], options?: GlobOptions): Promise<string[]>;
+export {};
+//# sourceMappingURL=globUtils.d.ts.map

package/lib/globUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"globUtils.d.ts","sourceRoot":"","sources":["../src/globUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAMH,OAAO,KAAK,UAAU,MAAM,YAAY,CAAC;AAEzC;;;GAGG;AACH,MAAM,MAAM,WAAW,GAAG,IAAI,CAC5B,UAAU,CAAC,WAAW,EACtB,KAAK,GAAG,QAAQ,GAAG,UAAU,CAC9B,CAAC;AAEF,wDAAwD;AACxD,wBAAsB,IAAI,CACxB,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAC3B,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAGnB;AAED;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,UAK9B,CAAC;AAEF,KAAK,OAAO,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;AAExC;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,OAAO,CASzD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,6BAA6B,CAC3C,QAAQ,EAAE,MAAM,EAAE,EAClB,WAAW,EAAE,MAAM,EAAE,GACpB,OAAO,CAuBT;AAcD,wBAAsB,QAAQ,CAC5B,QAAQ,EAAE,MAAM,EAAE,EAClB,OAAO,CAAC,EAAE,WAAW,GACpB,OAAO,CAAC,MAAM,EAAE,CAAC,CAQnB"}

package/lib/globUtils.js

@@ -0,0 +1,93 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GlobExcludeDefault = void 0;
+exports.glob = glob;
+exports.createMatcher = createMatcher;
+exports.createAbsoluteFilePathMatcher = createAbsoluteFilePathMatcher;
+exports.safeGlob = safeGlob;
+const tslib_1 = require("tslib");
+// Tinyglobby/Micromatch are the 2 libs we use in Docusaurus consistently
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const micromatch_1 = tslib_1.__importDefault(require("micromatch"));
+const Tinyglobby = tslib_1.__importStar(require("tinyglobby"));
+/** Finds the files matching the given glob patterns. */
+async function glob(patterns, options) {
+    // Other lib options are still forwarded at runtime for retro-compatibility
+    return Tinyglobby.glob(patterns, { ...options });
+}
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
+exports.GlobExcludeDefault = [
+    '**/_*.{js,jsx,ts,tsx,md,mdx}',
+    '**/_*/**',
+    '**/*.test.{js,jsx,ts,tsx}',
+    '**/__tests__/**',
+];
+/**
+ * Creates a matcher that tells if a path is matched by any of the patterns.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns. If the list is empty, it defaults to
+ * matching none.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
+function createMatcher(patterns) {
+    if (patterns.length === 0) {
+        // `/(?:)/.test("foo")` is `true`
+        return () => false;
+    }
+    const regexp = new RegExp(patterns.map((pattern) => micromatch_1.default.makeRe(pattern).source).join('|'));
+    return (str) => regexp.test(str);
+}
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
+function createAbsoluteFilePathMatcher(patterns, rootFolders) {
+    const matcher = createMatcher(patterns);
+    function getRelativeFilePath(absoluteFilePath) {
+        const rootFolder = rootFolders.find((folderPath) => ['/', '\\'].some((separator) => absoluteFilePath.startsWith(folderPath.endsWith(separator) ? folderPath : folderPath + separator)));
+        if (!rootFolder) {
+            throw new Error(`createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders: ${rootFolders.join(', ')}`);
+        }
+        return node_path_1.default.relative(rootFolder, absoluteFilePath);
+    }
+    return (absoluteFilePath) => matcher(getRelativeFilePath(absoluteFilePath));
+}
+// Duplicated from @docusaurus/utils to keep this package dependency-free
+// See https://github.com/sindresorhus/slash/blob/main/index.js
+function posixPath(str) {
+    const isExtendedLengthPath = str.startsWith('\\\\?\\');
+    if (isExtendedLengthPath) {
+        return str;
+    }
+    return str.replace(/\\/g, '/');
+}
+// Glob that fix Windows path patterns
+// See https://github.com/facebook/docusaurus/pull/4222#issuecomment-795517329
+async function safeGlob(patterns, options) {
+    // Required for Windows support, as paths using \ should not be used by glob
+    // (also using the windows hard drive prefix like c: is not a good idea)
+    const globPaths = patterns.map((dirPath) => posixPath(node_path_1.default.relative(process.cwd(), dirPath)));
+    return glob(globPaths, options);
+}
+//# sourceMappingURL=globUtils.js.map

package/lib/globUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"globUtils.js","sourceRoot":"","sources":["../src/globUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;;;;AAEH,yEAAyE;AAEzE,kEAA6B;AAC7B,oEAAoC;AACpC,MAAY,UAAU,+CAAmB;AAWzC,wDAAwD;AACjD,KAAK,eACV,QAA2B,EAC3B,OAAqB;IAErB,2EAA2E;IAC3E,OAAO,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,EAAC,GAAG,OAAO,EAAC,CAAC,CAAC;AACjD,CAAC;AAED;;;;GAIG;AACU,QAAA,kBAAkB,GAAG;IAChC,8BAA8B;IAC9B,UAAU;IACV,2BAA2B;IAC3B,iBAAiB;CAClB,CAAC;AAIF;;;;;;;;GAQG;AACH,uBAA8B,QAAkB;IAC9C,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAC1B,iCAAiC;QACjC,OAAO,GAAG,EAAE,CAAC,KAAK,CAAC;IACrB,CAAC;IACD,MAAM,MAAM,GAAG,IAAI,MAAM,CACvB,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,oBAAU,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CACvE,CAAC;IACF,OAAO,CAAC,GAAG,EAAE,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACnC,CAAC;AAED;;;;;;;;;;;;GAYG;AACH,uCACE,QAAkB,EAClB,WAAqB;IAErB,MAAM,OAAO,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAExC,SAAS,mBAAmB,CAAC,gBAAwB;QACnD,MAAM,UAAU,GAAG,WAAW,CAAC,IAAI,CAAC,CAAC,UAAU,EAAE,EAAE,CACjD,CAAC,GAAG,EAAE,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,EAAE,CAC7B,gBAAgB,CAAC,UAAU,CACzB,UAAU,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,UAAU,GAAG,SAAS,CACrE,CACF,CACF,CAAC;QACF,IAAI,CAAC,UAAU,EAAE,CAAC;YAChB,MAAM,IAAI,KAAK,CACb,oEAAoE,gBAAgB,kDAAkD,WAAW,CAAC,IAAI,CACpJ,IAAI,CACL,EAAE,CACJ,CAAC;QACJ,CAAC;QACD,OAAO,mBAAI,CAAC,QAAQ,CAAC,UAAU,EAAE,gBAAgB,CAAC,CAAC;IACrD,CAAC;IAED,OAAO,CAAC,gBAAwB,EAAE,EAAE,CAClC,OAAO,CAAC,mBAAmB,CAAC,gBAAgB,CAAC,CAAC,CAAC;AACnD,CAAC;AAED,yEAAyE;AACzE,+DAA+D;AAC/D,SAAS,SAAS,CAAC,GAAW;IAC5B,MAAM,oBAAoB,GAAG,GAAG,CAAC,UAAU,CAAC,SAAS,CAAC,CAAC;IACvD,IAAI,oBAAoB,EAAE,CAAC;QACzB,OAAO,GAAG,CAAC;IACb,CAAC;IACD,OAAO,GAAG,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;AACjC,CAAC;AAED,sCAAsC;AACtC,8EAA8E;AACvE,KAAK,mBACV,QAAkB,EAClB,OAAqB;IAErB,4EAA4E;IAC5E,wEAAwE;IACxE,MAAM,SAAS,GAAG,QAAQ,CAAC,GAAG,CAAC,CAAC,OAAO,EAAE,EAAE,CACzC,SAAS,CAAC,mBAAI,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,EAAE,EAAE,OAAO,CAAC,CAAC,CACjD,CAAC;IAEF,OAAO,IAAI,CAAC,SAAS,EAAE,OAAO,CAAC,CAAC;AAClC,CAAC"}

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export { glob, type GlobOptions, GlobExcludeDefault, safeGlob, createMatcher, createAbsoluteFilePathMatcher, } from './globUtils';
+export { globTranslatableSourceFiles } from './translationUtils';
+export { watch, type Watcher, type WatchOptions } from './watchUtils';
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,IAAI,EACJ,KAAK,WAAW,EAChB,kBAAkB,EAClB,QAAQ,EACR,aAAa,EACb,6BAA6B,GAC9B,MAAM,aAAa,CAAC;AACrB,OAAO,EAAC,2BAA2B,EAAC,MAAM,oBAAoB,CAAC;AAC/D,OAAO,EAAC,KAAK,EAAE,KAAK,OAAO,EAAE,KAAK,YAAY,EAAC,MAAM,cAAc,CAAC"}

package/lib/index.js

@@ -0,0 +1,20 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watch = exports.globTranslatableSourceFiles = exports.createAbsoluteFilePathMatcher = exports.createMatcher = exports.safeGlob = exports.GlobExcludeDefault = exports.glob = void 0;
+var globUtils_1 = require("./globUtils");
+Object.defineProperty(exports, "glob", { enumerable: true, get: function () { return globUtils_1.glob; } });
+Object.defineProperty(exports, "GlobExcludeDefault", { enumerable: true, get: function () { return globUtils_1.GlobExcludeDefault; } });
+Object.defineProperty(exports, "safeGlob", { enumerable: true, get: function () { return globUtils_1.safeGlob; } });
+Object.defineProperty(exports, "createMatcher", { enumerable: true, get: function () { return globUtils_1.createMatcher; } });
+Object.defineProperty(exports, "createAbsoluteFilePathMatcher", { enumerable: true, get: function () { return globUtils_1.createAbsoluteFilePathMatcher; } });
+var translationUtils_1 = require("./translationUtils");
+Object.defineProperty(exports, "globTranslatableSourceFiles", { enumerable: true, get: function () { return translationUtils_1.globTranslatableSourceFiles; } });
+var watchUtils_1 = require("./watchUtils");
+Object.defineProperty(exports, "watch", { enumerable: true, get: function () { return watchUtils_1.watch; } });
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;AAEH,yCAOqB;AANnB,iGAAA,IAAI,OAAA;AAEJ,+GAAA,kBAAkB,OAAA;AAClB,qGAAA,QAAQ,OAAA;AACR,0GAAA,aAAa,OAAA;AACb,0HAAA,6BAA6B,OAAA;AAE/B,uDAA+D;AAAvD,+HAAA,2BAA2B,OAAA;AACnC,2CAAoE;AAA5D,mGAAA,KAAK,OAAA"}

package/lib/translationUtils.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+export declare const isTranslatableSourceFile: (filePath: string) => boolean;
+export declare function globTranslatableSourceFiles(patterns: string[]): Promise<string[]>;
+//# sourceMappingURL=translationUtils.d.ts.map

package/lib/translationUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"translationUtils.d.ts","sourceRoot":"","sources":["../src/translationUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAQH,eAAO,MAAM,wBAAwB,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAsBzD,CAAC;AAEL,wBAAsB,2BAA2B,CAC/C,QAAQ,EAAE,MAAM,EAAE,GACjB,OAAO,CAAC,MAAM,EAAE,CAAC,CAKnB"}

package/lib/translationUtils.js

@@ -0,0 +1,43 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isTranslatableSourceFile = void 0;
+exports.globTranslatableSourceFiles = globTranslatableSourceFiles;
+const tslib_1 = require("tslib");
+// Awkward to have translation code in this package, but it is consumed by both
+// @docusaurus/core and @docusaurus/theme-translations: this avoids duplication
+const node_path_1 = tslib_1.__importDefault(require("node:path"));
+const globUtils_1 = require("./globUtils");
+exports.isTranslatableSourceFile = (() => {
+    // We only support extracting source code translations from these extensions
+    const extensionsAllowed = new Set([
+        '.js',
+        '.jsx',
+        '.ts',
+        '.tsx',
+        // TODO support md/mdx too? (may be overkill)
+        // need to compile the MDX to JSX first and remove front matter
+        // '.md',
+        // '.mdx',
+    ]);
+    const isBlacklistedFilePath = (filePath) => {
+        // We usually extract from ts files, unless they are .d.ts files
+        return filePath.endsWith('.d.ts');
+    };
+    return (filePath) => {
+        const ext = node_path_1.default.extname(filePath);
+        return extensionsAllowed.has(ext) && !isBlacklistedFilePath(filePath);
+    };
+})();
+async function globTranslatableSourceFiles(patterns) {
+    const filePaths = await (0, globUtils_1.safeGlob)(patterns, {
+        absolute: true,
+    });
+    return filePaths.filter(exports.isTranslatableSourceFile);
+}
+//# sourceMappingURL=translationUtils.js.map

package/lib/translationUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"translationUtils.js","sourceRoot":"","sources":["../src/translationUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;;AAEH,+EAA+E;AAC/E,+EAA+E;AAE/E,kEAA6B;AAC7B,2CAAqC;AAExB,QAAA,wBAAwB,GAAkC,CAAC,GAAG,EAAE;IAC3E,4EAA4E;IAC5E,MAAM,iBAAiB,GAAG,IAAI,GAAG,CAAC;QAChC,KAAK;QACL,MAAM;QACN,KAAK;QACL,MAAM;QACN,6CAA6C;QAC7C,+DAA+D;QAC/D,SAAS;QACT,UAAU;KACX,CAAC,CAAC;IAEH,MAAM,qBAAqB,GAAG,CAAC,QAAgB,EAAE,EAAE;QACjD,gEAAgE;QAChE,OAAO,QAAQ,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACpC,CAAC,CAAC;IAEF,OAAO,CAAC,QAAQ,EAAW,EAAE;QAC3B,MAAM,GAAG,GAAG,mBAAI,CAAC,OAAO,CAAC,QAAQ,CAAC,CAAC;QACnC,OAAO,iBAAiB,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACxE,CAAC,CAAC;AACJ,CAAC,CAAC,EAAE,CAAC;AAEE,KAAK,sCACV,QAAkB;IAElB,MAAM,SAAS,GAAG,MAAM,IAAA,oBAAQ,EAAC,QAAQ,EAAE;QACzC,QAAQ,EAAE,IAAI;KACf,CAAC,CAAC;IACH,OAAO,SAAS,CAAC,MAAM,CAAC,QAAA,wBAAwB,CAAC,CAAC;AACpD,CAAC"}

package/lib/watchUtils.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import * as Chokidar from 'chokidar';
+/**
+ * Our own watch options: we only expose the options we actually use, so that
+ * we can upgrade or swap the underlying lib.
+ */
+export type WatchOptions = Pick<Chokidar.WatchOptions, 'cwd' | 'usePolling' | 'interval'>;
+/** Our own file watcher handle, exposing only the APIs we actually use. */
+export type Watcher = Pick<Chokidar.FSWatcher, 'on' | 'close'>;
+/**
+ * Watches file system paths for changes.
+ * Only emits events for changes happening after the watcher is created.
+ */
+export declare function watch(paths: string | string[], options?: WatchOptions): Watcher;
+//# sourceMappingURL=watchUtils.d.ts.map

package/lib/watchUtils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchUtils.d.ts","sourceRoot":"","sources":["../src/watchUtils.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,OAAO,KAAK,QAAQ,MAAM,UAAU,CAAC;AAErC;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAC7B,QAAQ,CAAC,YAAY,EACrB,KAAK,GAAG,YAAY,GAAG,UAAU,CAClC,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,SAAS,EAAE,IAAI,GAAG,OAAO,CAAC,CAAC;AAE/D;;;GAGG;AACH,wBAAgB,KAAK,CACnB,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,EACxB,OAAO,CAAC,EAAE,YAAY,GACrB,OAAO,CAMT"}

package/lib/watchUtils.js

@@ -0,0 +1,24 @@
+"use strict";
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watch = watch;
+const tslib_1 = require("tslib");
+// Chokidar is the lib we use in Docusaurus to watch files
+const Chokidar = tslib_1.__importStar(require("chokidar"));
+/**
+ * Watches file system paths for changes.
+ * Only emits events for changes happening after the watcher is created.
+ */
+function watch(paths, options) {
+    return Chokidar.watch(paths, {
+        // Other lib options are still forwarded at runtime for retro-compatibility
+        ...options,
+        ignoreInitial: true,
+    });
+}
+//# sourceMappingURL=watchUtils.js.map

package/lib/watchUtils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchUtils.js","sourceRoot":"","sources":["../src/watchUtils.ts"],"names":[],"mappings":";AAAA;;;;;GAKG;;;;AAEH,0DAA0D;AAE1D,MAAY,QAAQ,6CAAiB;AAcrC;;;GAGG;AACH,eACE,KAAwB,EACxB,OAAsB;IAEtB,OAAO,QAAQ,CAAC,KAAK,CAAC,KAAK,EAAE;QAC3B,2EAA2E;QAC3E,GAAG,OAAO;QACV,aAAa,EAAE,IAAI;KACpB,CAAC,CAAC;AACL,CAAC"}

package/package.json

@@ -1,6 +1,32 @@
 {
   "name": "@azerion/bunosaurus-glob",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "4.0.0",
+  "description": "File globbing, glob matching and file watching utilities for Docusaurus packages.",
+  "main": "./lib/index.js",
+  "types": "./lib/index.d.ts",
+  "scripts": {
+    "build": "tsc",
+    "watch": "tsc --watch"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/azerion/bunosaurus.git",
+    "directory": "packages/docusaurus-glob"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "chokidar": "^3.6.0",
+    "micromatch": "^4.0.8",
+    "tinyglobby": "^0.2.17",
+    "tslib": "^2.8.1"
+  },
+  "engines": {
+    "bun": ">=1.4.1"
+  },
+  "devDependencies": {
+    "@types/micromatch": "^4.0.10"
+  }
+}

package/src/globUtils.ts

@@ -0,0 +1,130 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// Tinyglobby/Micromatch are the 2 libs we use in Docusaurus consistently
+
+import path from 'node:path';
+import Micromatch from 'micromatch';
+import * as Tinyglobby from 'tinyglobby';
+
+/**
+ * Our own glob options: we only expose the options we actually use, so that
+ * we can swap the underlying lib (e.g. for Node.js native `fs.glob`).
+ */
+export type GlobOptions = Pick<
+  Tinyglobby.GlobOptions,
+  'cwd' | 'ignore' | 'absolute'
+>;
+
+/** Finds the files matching the given glob patterns. */
+export async function glob(
+  patterns: string | string[],
+  options?: GlobOptions,
+): Promise<string[]> {
+  // Other lib options are still forwarded at runtime for retro-compatibility
+  return Tinyglobby.glob(patterns, {...options});
+}
+
+/**
+ * The default glob patterns we ignore when sourcing content.
+ * - Ignore files and folders starting with `_` recursively
+ * - Ignore tests
+ */
+export const GlobExcludeDefault = [
+  '**/_*.{js,jsx,ts,tsx,md,mdx}',
+  '**/_*/**',
+  '**/*.test.{js,jsx,ts,tsx}',
+  '**/__tests__/**',
+];
+
+type Matcher = (str: string) => boolean;
+
+/**
+ * Creates a matcher that tells if a path is matched by any of the patterns.
+ *
+ * @see {@link createAbsoluteFilePathMatcher}
+ * @param patterns A list of glob patterns. If the list is empty, it defaults to
+ * matching none.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns.
+ */
+export function createMatcher(patterns: string[]): Matcher {
+  if (patterns.length === 0) {
+    // `/(?:)/.test("foo")` is `true`
+    return () => false;
+  }
+  const regexp = new RegExp(
+    patterns.map((pattern) => Micromatch.makeRe(pattern).source).join('|'),
+  );
+  return (str) => regexp.test(str);
+}
+
+/**
+ * We use match patterns like `"** /_* /**"` (ignore the spaces), where `"_*"`
+ * should only be matched within a subfolder. This function would:
+ * - Match `/user/sebastien/website/docs/_partials/xyz.md`
+ * - Ignore `/user/_sebastien/website/docs/partials/xyz.md`
+ *
+ * @param patterns A list of glob patterns.
+ * @param rootFolders A list of root folders to resolve the glob from.
+ * @returns A matcher handle that tells if a file path is matched by any of the
+ * patterns, resolved from the first root folder that contains the path.
+ * @throws Throws when the returned matcher receives a path that doesn't belong
+ * to any of the `rootFolders`.
+ */
+export function createAbsoluteFilePathMatcher(
+  patterns: string[],
+  rootFolders: string[],
+): Matcher {
+  const matcher = createMatcher(patterns);
+
+  function getRelativeFilePath(absoluteFilePath: string) {
+    const rootFolder = rootFolders.find((folderPath) =>
+      ['/', '\\'].some((separator) =>
+        absoluteFilePath.startsWith(
+          folderPath.endsWith(separator) ? folderPath : folderPath + separator,
+        ),
+      ),
+    );
+    if (!rootFolder) {
+      throw new Error(
+        `createAbsoluteFilePathMatcher unexpected error, absoluteFilePath=${absoluteFilePath} was not contained in any of the root folders: ${rootFolders.join(
+          ', ',
+        )}`,
+      );
+    }
+    return path.relative(rootFolder, absoluteFilePath);
+  }
+
+  return (absoluteFilePath: string) =>
+    matcher(getRelativeFilePath(absoluteFilePath));
+}
+
+// Duplicated from @docusaurus/utils to keep this package dependency-free
+// See https://github.com/sindresorhus/slash/blob/main/index.js
+function posixPath(str: string): string {
+  const isExtendedLengthPath = str.startsWith('\\\\?\\');
+  if (isExtendedLengthPath) {
+    return str;
+  }
+  return str.replace(/\\/g, '/');
+}
+
+// Glob that fix Windows path patterns
+// See https://github.com/facebook/docusaurus/pull/4222#issuecomment-795517329
+export async function safeGlob(
+  patterns: string[],
+  options?: GlobOptions,
+): Promise<string[]> {
+  // Required for Windows support, as paths using \ should not be used by glob
+  // (also using the windows hard drive prefix like c: is not a good idea)
+  const globPaths = patterns.map((dirPath) =>
+    posixPath(path.relative(process.cwd(), dirPath)),
+  );
+
+  return glob(globPaths, options);
+}

package/src/index.ts

@@ -0,0 +1,17 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export {
+  glob,
+  type GlobOptions,
+  GlobExcludeDefault,
+  safeGlob,
+  createMatcher,
+  createAbsoluteFilePathMatcher,
+} from './globUtils';
+export {globTranslatableSourceFiles} from './translationUtils';
+export {watch, type Watcher, type WatchOptions} from './watchUtils';

package/src/translationUtils.ts

@@ -0,0 +1,45 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// Awkward to have translation code in this package, but it is consumed by both
+// @docusaurus/core and @docusaurus/theme-translations: this avoids duplication
+
+import path from 'node:path';
+import {safeGlob} from './globUtils';
+
+export const isTranslatableSourceFile: (filePath: string) => boolean = (() => {
+  // We only support extracting source code translations from these extensions
+  const extensionsAllowed = new Set([
+    '.js',
+    '.jsx',
+    '.ts',
+    '.tsx',
+    // TODO support md/mdx too? (may be overkill)
+    // need to compile the MDX to JSX first and remove front matter
+    // '.md',
+    // '.mdx',
+  ]);
+
+  const isBlacklistedFilePath = (filePath: string) => {
+    // We usually extract from ts files, unless they are .d.ts files
+    return filePath.endsWith('.d.ts');
+  };
+
+  return (filePath): boolean => {
+    const ext = path.extname(filePath);
+    return extensionsAllowed.has(ext) && !isBlacklistedFilePath(filePath);
+  };
+})();
+
+export async function globTranslatableSourceFiles(
+  patterns: string[],
+): Promise<string[]> {
+  const filePaths = await safeGlob(patterns, {
+    absolute: true,
+  });
+  return filePaths.filter(isTranslatableSourceFile);
+}

package/src/watchUtils.ts

@@ -0,0 +1,37 @@
+/**
+ * Copyright (c) Facebook, Inc. and its affiliates.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+// Chokidar is the lib we use in Docusaurus to watch files
+
+import * as Chokidar from 'chokidar';
+
+/**
+ * Our own watch options: we only expose the options we actually use, so that
+ * we can upgrade or swap the underlying lib.
+ */
+export type WatchOptions = Pick<
+  Chokidar.WatchOptions,
+  'cwd' | 'usePolling' | 'interval'
+>;
+
+/** Our own file watcher handle, exposing only the APIs we actually use. */
+export type Watcher = Pick<Chokidar.FSWatcher, 'on' | 'close'>;
+
+/**
+ * Watches file system paths for changes.
+ * Only emits events for changes happening after the watcher is created.
+ */
+export function watch(
+  paths: string | string[],
+  options?: WatchOptions,
+): Watcher {
+  return Chokidar.watch(paths, {
+    // Other lib options are still forwarded at runtime for retro-compatibility
+    ...options,
+    ignoreInitial: true,
+  });
+}