@mnaoumov/typescript-dev-toolkit 0.0.0 → 1.1.0

package/dist/lib/esm/linters/markdownlint-types/@types/markdownlint-cli2.d.mts

@@ -0,0 +1,67 @@
+/// <reference path="../../../library-references.d.mts" />
+/**
+ * @file
+ *
+ * The types for `markdownlint-cli2`'s programmatic entry point, which the package itself describes in JSDoc
+ * and ships no declaration for. Vendored here, beside the configuration-schema types, for the same reason.
+ *
+ * Only the parameters {@link lintMarkdownContent} passes are declared. The full parameter object also carries
+ * `argv`, `allowStdin`, `fileContents`, `fs`, `noImport` and `optionsOverride`, none of which a caller linting
+ * one in-memory document has any use for — and declaring an option nobody passes is a claim about a shape
+ * nothing here ever checks.
+ */
+
+declare module 'markdownlint-cli2' {
+  /**
+   * The parameters of {@link main}.
+   */
+  interface MarkdownlintCli2Parameters {
+    /**
+     * The directory whose `markdownlint-cli2` configuration applies, and the base every reported path is
+     * relative to.
+     *
+     * @default `process.cwd()`
+     */
+    readonly directory?: string | undefined;
+
+    /**
+     * Called once per finding, with the line the default output formatter would have printed.
+     */
+    readonly logError?: ((message: string) => void) | undefined;
+
+    /**
+     * Called with the banner and the progress lines — everything that is not a finding.
+     */
+    readonly logMessage?: ((message: string) => void) | undefined;
+
+    /**
+     * Whether to skip glob expansion entirely, including the `globs` the configuration declares. Set it when
+     * the only input is {@link nonFileContents}, so the run cannot wander into the repository's own files.
+     *
+     * @default `false`
+     */
+    readonly noGlobs?: boolean | undefined;
+
+    /**
+     * Content to lint that is not read from disk, keyed by the POSIX path it is linted AS. The path decides
+     * which directory's configuration applies and how the path-relative rules (such as `relative-links`)
+     * resolve, so it should be the path the content is destined for.
+     */
+    readonly nonFileContents?: Record<string, string> | undefined;
+
+    /**
+     * The options the discovered configuration is merged OVER — a base, not an override. `config` is merged
+     * key by key and every other option is replaced wholesale, so anything the repository states itself wins.
+     */
+    readonly optionsDefault?: import('./markdownlint-cli2-config-schema.d.mjs').MarkdownlintCli2ConfigurationSchema | undefined;
+  }
+
+  /**
+   * Runs `markdownlint-cli2`.
+   *
+   * @param parameters - The {@link MarkdownlintCli2Parameters}.
+   * @returns A {@link Promise} that resolves to the process exit code: `0` when nothing was reported, `1`
+   * when something was, `2` when the run itself failed.
+   */
+  export function main(parameters: MarkdownlintCli2Parameters): Promise<number>;
+}

package/dist/lib/esm/linters/markdownlint.d.mts

@@ -0,0 +1,32 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * Lint markdown documentation using `markdownlint-cli2` and `linkinator`.
+ */
+/**
+ * Parameters for the {@link lint} function.
+ */
+export interface LintOptions {
+    /**
+     * The configuration file copied to the project root when the project has none. Without it,
+     * `markdownlint-cli2` runs with its own defaults.
+     */
+    readonly defaultConfigFilePath?: string | undefined;
+    /**
+     * Optional file paths to lint. If omitted, lints the entire project.
+     */
+    readonly paths?: string[] | undefined;
+    /**
+     * Whether to fix linting issues automatically.
+     *
+     * @default `false`
+     */
+    readonly shouldFix?: boolean | undefined;
+}
+/**
+ * Lint markdown documentation using `markdownlint-cli2` and `linkinator`.
+ *
+ * @param options - The {@link LintOptions}.
+ */
+export declare function lint(options?: LintOptions): Promise<void>;

package/dist/lib/esm/linters/markdownlint.mjs

@@ -0,0 +1,124 @@
+/*
+THIS IS A GENERATED/BUNDLED FILE BY ESBUILD
+if you want to view the source, please visit the github repository of this plugin
+*/
+
+(function () {
+function ensureDisposeSymbols(symbolConstructor = Symbol) {
+  symbolConstructor.asyncDispose ??= symbolConstructor.for('Symbol.asyncDispose');
+  symbolConstructor.dispose ??= symbolConstructor.for('Symbol.dispose');
+}
+
+function ensureBrowserProcess() {
+  const browserProcess = {
+    browser: true,
+    cwd() {
+      return '/';
+    },
+    env: {},
+    platform: 'android'
+  };
+
+  const existingProcess = globalThis.process;
+
+  if (!existingProcess) {
+    globalThis.process = browserProcess;
+    return;
+  }
+
+  if (existingProcess.versions?.node) {
+    return;
+  }
+
+  const existingProcessRecord = existingProcess;
+
+  for (const [key, value] of Object.entries(browserProcess)) {
+    existingProcessRecord[key] ??= value;
+  }
+
+  existingProcessRecord['browser'] = true;
+}
+
+(function initEsm() {
+  ensureDisposeSymbols();
+  ensureBrowserProcess();
+})();
+})();
+
+import { toArray } from "@mnaoumov/typescript-lib/async";
+import { getLibDebugger } from "@mnaoumov/typescript-lib/debug";
+import { basename } from "@mnaoumov/typescript-lib/path";
+import { existsSync } from "node:fs";
+import {
+  cp,
+  glob
+} from "node:fs/promises";
+import { relative } from "node:path";
+import { getNonIgnoredFiles } from "../git.mjs";
+import { resolveToolCommand } from "../package-manager.mjs";
+import { RepoPaths } from "../repo-paths.mjs";
+import {
+  execFromRoot,
+  getRootFolder,
+  resolvePathFromRootSafe
+} from "../root.mjs";
+import {
+  checkIsInNodeModules,
+  NODE_MODULES_IGNORE_GLOB
+} from "./markdownlint-ignores.mjs";
+async function lint(options) {
+  const { defaultConfigFilePath, paths, shouldFix = false } = options ?? {};
+  const configFiles = [
+    RepoPaths.MarkdownlintCli2ConfigJsonc,
+    RepoPaths.MarkdownlintCli2ConfigYaml,
+    RepoPaths.MarkdownlintCli2ConfigCjs,
+    RepoPaths.MarkdownlintCli2ConfigMjs,
+    RepoPaths.MarkdownlintConfigJsonc,
+    RepoPaths.MarkdownlintConfigJson,
+    RepoPaths.MarkdownlintConfigYaml,
+    RepoPaths.MarkdownlintConfigYml,
+    RepoPaths.MarkdownlintConfigCjs,
+    RepoPaths.MarkdownlintConfigMjs
+  ];
+  const doesConfigFileExist = configFiles.some((configFile) => {
+    const configFilePath = resolvePathFromRootSafe({ path: configFile });
+    return existsSync(configFilePath);
+  });
+  if (!doesConfigFileExist && defaultConfigFilePath) {
+    getLibDebugger("markdownlint:lint")("markdownlint configuration file not found. Creating default config...");
+    await cp(defaultConfigFilePath, resolvePathFromRootSafe({ path: basename(defaultConfigFilePath) }));
+  }
+  const targets = paths?.length ? paths : [RepoPaths.CurrentFolder];
+  await execFromRoot([...resolveToolCommand({ tool: "markdownlint-cli2" }), ...shouldFix ? ["--fix"] : [], { batchedArguments: targets }]);
+  const rootFolder = getRootFolder() ?? process.cwd();
+  const mdFiles = paths?.length ? paths.map((p) => relative(rootFolder, p).replaceAll("\\", "/") || p) : await getMarkdownFiles();
+  await execFromRoot([
+    ...resolveToolCommand({ tool: "linkinator" }),
+    "--retry",
+    "--retry-errors",
+    "--retry-errors-count",
+    "3",
+    "--retry-errors-jitter",
+    "5",
+    "--url-rewrite-search",
+    String.raw`https://www\.npmjs\.com/package/`,
+    "--url-rewrite-replace",
+    "https://registry.npmjs.org/",
+    { batchedArguments: mdFiles }
+  ]);
+}
+const MARKDOWN_PATHSPEC = "*.md";
+async function getMarkdownFiles() {
+  const nonIgnoredFiles = await getNonIgnoredFiles({ patterns: [MARKDOWN_PATHSPEC] });
+  return nonIgnoredFiles ? nonIgnoredFiles.filter((path) => !checkIsInNodeModules(path)) : await toArray(glob(["**/*.md"], {
+    exclude: [
+      ".git/**",
+      "dist/**",
+      NODE_MODULES_IGNORE_GLOB
+    ]
+  }));
+}
+export {
+  lint
+};
+//# sourceMappingURL=data:application/json;base64,ewogICJ2ZXJzaW9uIjogMywKICAic291cmNlcyI6IFsiLi4vLi4vLi4vLi4vc3JjL2xpbnRlcnMvbWFya2Rvd25saW50LnRzIl0sCiAgInNvdXJjZXNDb250ZW50IjogWyIvKipcbiAqIEBmaWxlXG4gKlxuICogTGludCBtYXJrZG93biBkb2N1bWVudGF0aW9uIHVzaW5nIGBtYXJrZG93bmxpbnQtY2xpMmAgYW5kIGBsaW5raW5hdG9yYC5cbiAqL1xuXG5pbXBvcnQgeyB0b0FycmF5IH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL2FzeW5jJztcbmltcG9ydCB7IGdldExpYkRlYnVnZ2VyIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL2RlYnVnJztcbmltcG9ydCB7IGJhc2VuYW1lIH0gZnJvbSAnQG1uYW91bW92L3R5cGVzY3JpcHQtbGliL3BhdGgnO1xuaW1wb3J0IHsgZXhpc3RzU3luYyB9IGZyb20gJ25vZGU6ZnMnO1xuaW1wb3J0IHtcbiAgY3AsXG4gIGdsb2Jcbn0gZnJvbSAnbm9kZTpmcy9wcm9taXNlcyc7XG5pbXBvcnQgeyByZWxhdGl2ZSB9IGZyb20gJ25vZGU6cGF0aCc7XG5cbmltcG9ydCB7IGdldE5vbklnbm9yZWRGaWxlcyB9IGZyb20gJy4uL2dpdC50cyc7XG5pbXBvcnQgeyByZXNvbHZlVG9vbENvbW1hbmQgfSBmcm9tICcuLi9wYWNrYWdlLW1hbmFnZXIudHMnO1xuaW1wb3J0IHsgUmVwb1BhdGhzIH0gZnJvbSAnLi4vcmVwby1wYXRocy50cyc7XG5pbXBvcnQge1xuICBleGVjRnJvbVJvb3QsXG4gIGdldFJvb3RGb2xkZXIsXG4gIHJlc29sdmVQYXRoRnJvbVJvb3RTYWZlXG59IGZyb20gJy4uL3Jvb3QudHMnO1xuaW1wb3J0IHtcbiAgY2hlY2tJc0luTm9kZU1vZHVsZXMsXG4gIE5PREVfTU9EVUxFU19JR05PUkVfR0xPQlxufSBmcm9tICcuL21hcmtkb3dubGludC1pZ25vcmVzLnRzJztcblxuLyoqXG4gKiBQYXJhbWV0ZXJzIGZvciB0aGUge0BsaW5rIGxpbnR9IGZ1bmN0aW9uLlxuICovXG5leHBvcnQgaW50ZXJmYWNlIExpbnRPcHRpb25zIHtcbiAgLyoqXG4gICAqIFRoZSBjb25maWd1cmF0aW9uIGZpbGUgY29waWVkIHRvIHRoZSBwcm9qZWN0IHJvb3Qgd2hlbiB0aGUgcHJvamVjdCBoYXMgbm9uZS4gV2l0aG91dCBpdCxcbiAgICogYG1hcmtkb3dubGludC1jbGkyYCBydW5zIHdpdGggaXRzIG93biBkZWZhdWx0cy5cbiAgICovXG4gIHJlYWRvbmx5IGRlZmF1bHRDb25maWdGaWxlUGF0aD86IHN0cmluZyB8IHVuZGVmaW5lZDtcblxuICAvKipcbiAgICogT3B0aW9uYWwgZmlsZSBwYXRocyB0byBsaW50LiBJZiBvbWl0dGVkLCBsaW50cyB0aGUgZW50aXJlIHByb2plY3QuXG4gICAqL1xuICByZWFkb25seSBwYXRocz86IHN0cmluZ1tdIHwgdW5kZWZpbmVkO1xuXG4gIC8qKlxuICAgKiBXaGV0aGVyIHRvIGZpeCBsaW50aW5nIGlzc3VlcyBhdXRvbWF0aWNhbGx5LlxuICAgKlxuICAgKiBAZGVmYXVsdCBgZmFsc2VgXG4gICAqL1xuICByZWFkb25seSBzaG91bGRGaXg/OiBib29sZWFuIHwgdW5kZWZpbmVkO1xufVxuXG4vKipcbiAqIExpbnQgbWFya2Rvd24gZG9jdW1lbnRhdGlvbiB1c2luZyBgbWFya2Rvd25saW50LWNsaTJgIGFuZCBgbGlua2luYXRvcmAuXG4gKlxuICogQHBhcmFtIG9wdGlvbnMgLSBUaGUge0BsaW5rIExpbnRPcHRpb25zfS5cbiAqL1xuZXhwb3J0IGFzeW5jIGZ1bmN0aW9uIGxpbnQob3B0aW9ucz86IExpbnRPcHRpb25zKTogUHJvbWlzZTx2b2lkPiB7XG4gIGNvbnN0IHsgZGVmYXVsdENvbmZpZ0ZpbGVQYXRoLCBwYXRocywgc2hvdWxkRml4ID0gZmFsc2UgfSA9IG9wdGlvbnMgPz8ge307XG4gIGNvbnN0IGNvbmZpZ0ZpbGVzID0gW1xuICAgIFJlcG9QYXRocy5NYXJrZG93bmxpbnRDbGkyQ29uZmlnSnNvbmMsXG4gICAgUmVwb1BhdGhzLk1hcmtkb3dubGludENsaTJDb25maWdZYW1sLFxuICAgIFJlcG9QYXRocy5NYXJrZG93bmxpbnRDbGkyQ29uZmlnQ2pzLFxuICAgIFJlcG9QYXRocy5NYXJrZG93bmxpbnRDbGkyQ29uZmlnTWpzLFxuICAgIFJlcG9QYXRocy5NYXJrZG93bmxpbnRDb25maWdKc29uYyxcbiAgICBSZXBvUGF0aHMuTWFya2Rvd25saW50Q29uZmlnSnNvbixcbiAgICBSZXBvUGF0aHMuTWFya2Rvd25saW50Q29uZmlnWWFtbCxcbiAgICBSZXBvUGF0aHMuTWFya2Rvd25saW50Q29uZmlnWW1sLFxuICAgIFJlcG9QYXRocy5NYXJrZG93bmxpbnRDb25maWdDanMsXG4gICAgUmVwb1BhdGhzLk1hcmtkb3dubGludENvbmZpZ01qc1xuICBdO1xuXG4gIGNvbnN0IGRvZXNDb25maWdGaWxlRXhpc3QgPSBjb25maWdGaWxlcy5zb21lKChjb25maWdGaWxlKSA9PiB7XG4gICAgY29uc3QgY29uZmlnRmlsZVBhdGggPSByZXNvbHZlUGF0aEZyb21Sb290U2FmZSh7IHBhdGg6IGNvbmZpZ0ZpbGUgfSk7XG4gICAgcmV0dXJuIGV4aXN0c1N5bmMoY29uZmlnRmlsZVBhdGgpO1xuICB9KTtcblxuICBpZiAoIWRvZXNDb25maWdGaWxlRXhpc3QgJiYgZGVmYXVsdENvbmZpZ0ZpbGVQYXRoKSB7XG4gICAgZ2V0TGliRGVidWdnZXIoJ21hcmtkb3dubGludDpsaW50JykoJ21hcmtkb3dubGludCBjb25maWd1cmF0aW9uIGZpbGUgbm90IGZvdW5kLiBDcmVhdGluZyBkZWZhdWx0IGNvbmZpZy4uLicpO1xuICAgIGF3YWl0IGNwKGRlZmF1bHRDb25maWdGaWxlUGF0aCwgcmVzb2x2ZVBhdGhGcm9tUm9vdFNhZmUoeyBwYXRoOiBiYXNlbmFtZShkZWZhdWx0Q29uZmlnRmlsZVBhdGgpIH0pKTtcbiAgfVxuXG4gIC8qIHY4IGlnbm9yZSBzdGFydCAtLSBUaGUgcGF0aHMtcHJvdmlkZWQgYnJhbmNoZXMgYXJlIG9ubHkgZXhlcmNpc2VkIGJ5IGNvbnN1bWVyIHByb2plY3RzIHBhc3NpbmcgZmlsZSBsaXN0cy4gKi9cbiAgY29uc3QgdGFyZ2V0cyA9IHBhdGhzPy5sZW5ndGggPyBwYXRocyA6IFtSZXBvUGF0aHMuQ3VycmVudEZvbGRlcl07XG4gIC8qIHY4IGlnbm9yZSBzdG9wICovXG4gIGF3YWl0IGV4ZWNGcm9tUm9vdChbLi4ucmVzb2x2ZVRvb2xDb21tYW5kKHsgdG9vbDogJ21hcmtkb3dubGludC1jbGkyJyB9KSwgLi4uKHNob3VsZEZpeCA/IFsnLS1maXgnXSA6IFtdKSwgeyBiYXRjaGVkQXJndW1lbnRzOiB0YXJnZXRzIH1dKTtcblxuICAvKiB2OCBpZ25vcmUgc3RhcnQgLS0gVGhlIHBhdGhzLXByb3ZpZGVkIGJyYW5jaCBpcyBvbmx5IGV4ZXJjaXNlZCBieSBjb25zdW1lciBwcm9qZWN0cyBwYXNzaW5nIGZpbGUgbGlzdHMuICovXG4gIGNvbnN0IHJvb3RGb2xkZXIgPSBnZXRSb290Rm9sZGVyKCkgPz8gcHJvY2Vzcy5jd2QoKTtcbiAgY29uc3QgbWRGaWxlcyA9IHBhdGhzPy5sZW5ndGhcbiAgICA/IHBhdGhzLm1hcCgocCkgPT4gcmVsYXRpdmUocm9vdEZvbGRlciwgcCkucmVwbGFjZUFsbCgnXFxcXCcsICcvJykgfHwgcClcbiAgICA6IGF3YWl0IGdldE1hcmtkb3duRmlsZXMoKTtcbiAgLyogdjggaWdub3JlIHN0b3AgKi9cbiAgYXdhaXQgZXhlY0Zyb21Sb290KFtcbiAgICAuLi5yZXNvbHZlVG9vbENvbW1hbmQoeyB0b29sOiAnbGlua2luYXRvcicgfSksXG4gICAgJy0tcmV0cnknLFxuICAgICctLXJldHJ5LWVycm9ycycsXG4gICAgJy0tcmV0cnktZXJyb3JzLWNvdW50JyxcbiAgICAnMycsXG4gICAgJy0tcmV0cnktZXJyb3JzLWppdHRlcicsXG4gICAgJzUnLFxuICAgICctLXVybC1yZXdyaXRlLXNlYXJjaCcsXG4gICAgU3RyaW5nLnJhd2BodHRwczovL3d3d1xcLm5wbWpzXFwuY29tL3BhY2thZ2UvYCxcbiAgICAnLS11cmwtcmV3cml0ZS1yZXBsYWNlJyxcbiAgICAnaHR0cHM6Ly9yZWdpc3RyeS5ucG1qcy5vcmcvJyxcbiAgICB7IGJhdGNoZWRBcmd1bWVudHM6IG1kRmlsZXMgfVxuICBdKTtcbn1cblxuLyoqXG4gKiBUaGUgZ2l0IHBhdGhzcGVjIG1hdGNoaW5nIGV2ZXJ5IG1hcmtkb3duIGZpbGUgaW4gdGhlIHJlcG9zaXRvcnksIGF0IGFueSBkZXB0aC5cbiAqL1xuY29uc3QgTUFSS0RPV05fUEFUSFNQRUMgPSAnKi5tZCc7XG5cbi8qKlxuICogTGlzdHMgdGhlIG1hcmtkb3duIGZpbGVzIHRvIGhhbmQgdG8gYGxpbmtpbmF0b3JgLlxuICpcbiAqIGBsaW5raW5hdG9yYCB0YWtlcyBhIGZpbGUgbGlzdCByYXRoZXIgdGhhbiBhbiBpZ25vcmUgY29uZmlndXJhdGlvbiwgc28gdGhlIGdpdGlnbm9yZWQgZmlsZXMgaGF2ZSB0byBiZVxuICogZHJvcHBlZCBiZWZvcmUgaXQgaXMgaW52b2tlZC4gR2l0IGl0c2VsZiBhbnN3ZXJzIHRoYXQgKG5lc3RlZCBpZ25vcmUgZmlsZXMsIGAhYCBuZWdhdGlvbnMgYW5kIGFsbCk7IHRoZVxuICogaGFuZC1tYWludGFpbmVkIGdsb2IgZXhjbHVzaW9ucyBiZWxvdyBhcmUgb25seSB0aGUgZmFsbGJhY2sgZm9yIGEgY2hlY2tvdXQgd2l0aG91dCBnaXQsIGFuZCB0aGV5IGFyZSB0aGVcbiAqIHZlcnkgbGlzdHMgdGhpcyBpbmRpcmVjdGlvbiBleGlzdHMgdG8gc3RvcCBmcm9tIGRyaWZ0aW5nLlxuICpcbiAqIFRoZSBgbm9kZV9tb2R1bGVzYCBmaWx0ZXIgaXMgYXBwbGllZCB0byB0aGUgZ2l0LWRlcml2ZWQgbGlzdCB0b28sIGFuZCBkZWxpYmVyYXRlbHkgc286IGdpdCBvbmx5IHNraXBzXG4gKiB3aGF0IHRoZSByZXBvc2l0b3J5IGFza2VkIGl0IHRvIHNraXAsIGFuZCBhIHJlcG9zaXRvcnkgY2FuIGRlbGliZXJhdGVseSBUUkFDSyBhIHZlbmRvcmVkIGBub2RlX21vZHVsZXNgXG4gKiB0cmVlLiBUaGF0IGlzIHRoZSBvbmUgZXhjbHVzaW9uIGAuZ2l0aWdub3JlYCBjYW5ub3QgYW5zd2VyIFx1MjAxNCBzZWUgYG1hcmtkb3dubGludC1pZ25vcmVzLnRzYC4gQXBwbHlpbmcgaXRcbiAqIGhlcmUga2VlcHMgYGxpbmtpbmF0b3JgIGluIHN0ZXAgd2l0aCB0aGUgbWFya2Rvd25saW50IGhhbGYsIHdoaWNoIGlnbm9yZXMgdGhlIHNhbWUgcGF0aHMgYnkgZ2xvYi5cbiAqXG4gKiBAcmV0dXJucyBBIHtAbGluayBQcm9taXNlfSB0aGF0IHJlc29sdmVzIHdpdGggdGhlIG1hcmtkb3duIGZpbGUgcGF0aHMsIHJlbGF0aXZlIHRvIHRoZSByb290IGZvbGRlci5cbiAqL1xuYXN5bmMgZnVuY3Rpb24gZ2V0TWFya2Rvd25GaWxlcygpOiBQcm9taXNlPHN0cmluZ1tdPiB7XG4gIGNvbnN0IG5vbklnbm9yZWRGaWxlcyA9IGF3YWl0IGdldE5vbklnbm9yZWRGaWxlcyh7IHBhdHRlcm5zOiBbTUFSS0RPV05fUEFUSFNQRUNdIH0pO1xuICByZXR1cm4gbm9uSWdub3JlZEZpbGVzXG4gICAgPyBub25JZ25vcmVkRmlsZXMuZmlsdGVyKChwYXRoKSA9PiAhY2hlY2tJc0luTm9kZU1vZHVsZXMocGF0aCkpXG4gICAgOiAoYXdhaXQgdG9BcnJheShnbG9iKFsnKiovKi5tZCddLCB7XG4gICAgICBleGNsdWRlOiBbXG4gICAgICAgICcuZ2l0LyoqJyxcbiAgICAgICAgJ2Rpc3QvKionLFxuICAgICAgICBOT0RFX01PRFVMRVNfSUdOT1JFX0dMT0JcbiAgICAgIF1cbiAgICB9KSkpO1xufVxuIl0sCiAgIm1hcHBpbmdzIjogIjs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7Ozs7QUFNQSxTQUFTLGVBQWU7QUFDeEIsU0FBUyxzQkFBc0I7QUFDL0IsU0FBUyxnQkFBZ0I7QUFDekIsU0FBUyxrQkFBa0I7QUFDM0I7QUFBQSxFQUNFO0FB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

package/dist/lib/esm/linters/over-exposure.d.mts

@@ -0,0 +1,357 @@
+/// <reference path="../library-references.d.mts" />
+/**
+ * @file
+ *
+ * Over-exposure analyzer.
+ *
+ * Finds declarations exposed more broadly than their references require, so the exposure can be
+ * tightened:
+ *
+ * - `export`ed symbols referenced only within their own file — the `export` can be dropped.
+ * - `public` class members referenced only inside their own class — they can be `private`.
+ * - `public` class members referenced only inside their own class and its subclasses — they can be
+ *   `protected`.
+ * - `protected` class members referenced only inside their own class — they can be `private`.
+ *
+ * The analysis is whole-program and type-aware: it uses the TypeScript language service's
+ * find-all-references to locate every use of each declaration, then classifies the tightest
+ * exposure that still covers all references. Because `findReferences` does not link a string-literal
+ * argument back to a member declaration when the parameter is a conditional/mapped key type (e.g.
+ * `bind(component, 'someSetting')` where the key is typed `ConditionalKeys<Settings, …>`), member
+ * analysis additionally treats a string literal whose text equals the member name as a reference —
+ * but only when its contextual type is a string-literal type (or union of them) all of whose members
+ * are keys of the declaring class, so incidental same-named strings (`console.log('name')`) are not
+ * miscounted. Members invoked by the framework via registration
+ * rather than by visible references (Obsidian lifecycle hooks, settings-tab `display`, etc.) are
+ * excluded via {@link LIFECYCLE_ALLOWLIST}, as are `override` and `static` members whose exposure is
+ * constrained by a base declaration. ECMAScript hard-private members (`#name`) are also excluded —
+ * they are already maximally private and cannot carry a visibility modifier. A declaration carrying
+ * a TSDoc (`/** … *\/`) documentation comment is likewise excluded — whether a top-level `export` or
+ * a class member, documenting it is a deliberate signal that it is part of the intended public API,
+ * regardless of where it currently happens to be referenced.
+ *
+ * A member referenced only from test files is reported with {@link OverExposureFinding.isForcedByTestOnly}
+ * set, surfacing members widened purely for testability — the canonical case for extracting logic
+ * into an independently testable component instead.
+ *
+ * Beyond reporting, passing `shouldFix` to {@link findOverExposure} / {@link analyzeOverExposure}
+ * rewrites the source in place: dropping the `export` keyword, or replacing/inserting a `private`
+ * or `protected` modifier. Each finding then carries {@link OverExposureFinding.wasFixed} /
+ * {@link OverExposureFinding.skipReason}. Changes that cannot be safely automated — those forced
+ * only by test references, decorated members, or an `export` shared with a still-exported sibling —
+ * are reported as skipped and left untouched.
+ *
+ * Additionally passing `shouldForce` (only meaningful together with `shouldFix`) tightens the
+ * declarations held wide purely by test references too — the production half of the canonical
+ * test-only migration: the member becomes `private` / the `export` is dropped, leaving only the
+ * test to switch to a cast-based access. Decorated members and exports shared with a still-exported
+ * sibling stay skipped even under `shouldForce`, because no edit can be applied safely.
+ */
+import type { CompilerOptions, LanguageService, LanguageServiceHost } from 'typescript';
+/**
+ * Parameters for {@link analyzeOverExposure}.
+ */
+export interface AnalyzeOverExposureParams {
+    /**
+    The language service to query for references and types.
+     */
+    readonly languageService: LanguageService;
+    /**
+     * Optional callback invoked once per analyzed source file, before that file is processed. The
+     * whole-program reference analysis is slow, so this lets callers report live progress instead of
+     * appearing to hang.
+     */
+    readonly onProgress?: (progress: OverExposureProgress) => void;
+    /**
+     * When `true`, each fixable finding is tightened in place via {@link writeFile} (which must then
+     * be provided), and the returned findings carry {@link OverExposureFinding.wasFixed} /
+     * {@link OverExposureFinding.skipReason}. When `false` or omitted, the analysis only reports.
+     *
+     * @default `false`
+     */
+    readonly shouldFix?: boolean | undefined;
+    /**
+     * When `true` (only meaningful together with {@link shouldFix}), declarations held wide purely by
+     * test references are tightened too, instead of being skipped with a `test-only`
+     * {@link OverExposureFinding.skipReason}. Decorated members and exports shared with a
+     * still-exported sibling stay skipped regardless, because no edit can be applied safely.
+     *
+     * @default `false`
+     */
+    readonly shouldForce?: boolean | undefined;
+    /**
+     * Absolute (canonical) path of the project's `src` folder. Only declarations in non-test files
+     * under this folder are analyzed; declarations elsewhere (test files, dependencies) are ignored
+     * but still counted as reference sites.
+     */
+    readonly srcFolder: string;
+    /**
+     * Writes the tightened contents of a changed file back to disk. Required when {@link shouldFix}
+     * is `true`; ignored otherwise.
+     *
+     * @param path - Absolute path of the file to write (original casing, as stored in the program).
+     * @param content - The full new file contents.
+     */
+    readonly writeFile?: (path: string, content: string) => void;
+}
+/**
+ * Parameters for {@link createLanguageServiceHost}.
+ */
+export interface CreateLanguageServiceHostParams {
+    /**
+    The compiler options.
+     */
+    readonly compilerOptions: CompilerOptions;
+    /**
+    The files to include in the program.
+     */
+    readonly fileNames: readonly string[];
+    /**
+    The file-system operations used to read sources.
+     */
+    readonly fileSystem: OverExposureFileSystem;
+}
+/**
+ * Parameters for {@link createProjectLanguageService}.
+ */
+export interface CreateProjectLanguageServiceParams {
+    /**
+    Absolute path to the project's `tsconfig.json`.
+     */
+    readonly tsConfigPath: string;
+}
+/**
+ * The exposure level a declaration currently has.
+ */
+export type CurrentExposure = 'export' | 'protected' | 'public';
+/**
+ * Parameters for {@link findOverExposure}.
+ */
+export interface FindOverExposureParams {
+    /**
+     * Optional callback invoked once per analyzed source file, for live progress reporting. Forwarded
+     * to {@link analyzeOverExposure}.
+     */
+    readonly onProgress?: (progress: OverExposureProgress) => void;
+    /**
+    Absolute path to the project root (the folder containing `tsconfig.json` and `src`).
+     */
+    readonly projectFolder: string;
+    /**
+     * When `true`, fixable findings are tightened in place on disk (the `export` keyword is dropped,
+     * or a `private` / `protected` modifier is inserted/replaced). When `false` or omitted, the
+     * project is only analyzed.
+     *
+     * @default `false`
+     */
+    readonly shouldFix?: boolean | undefined;
+    /**
+     * When `true` (only meaningful together with {@link shouldFix}), declarations held wide purely by
+     * test references are tightened too, instead of being skipped. Decorated members and exports
+     * shared with a still-exported sibling stay skipped regardless. Forwarded to
+     * {@link analyzeOverExposure}.
+     *
+     * @default `false`
+     */
+    readonly shouldForce?: boolean | undefined;
+}
+/**
+ * Options for {@link formatOverExposureFindings}.
+ */
+export interface FormatOverExposureFindingsOptions {
+    /**
+     * When set, file paths in the report are rendered relative to this folder (typically the current
+     * working directory) instead of as absolute paths. Paths outside the folder stay absolute.
+     */
+    readonly baseFolder?: string;
+}
+/**
+ * The subset of file-system operations the language-service host needs. Injecting this (rather than
+ * always using `typescript`'s `sys`) lets tests drive the analyzer against in-memory sources with no
+ * real file-system access.
+ */
+export interface OverExposureFileSystem {
+    /**
+     * Checks whether a directory exists.
+     *
+     * @param path - Directory path.
+     * @returns `true` when the directory exists.
+     */
+    directoryExists: (path: string) => boolean;
+    /**
+     * Checks whether a file exists.
+     *
+     * @param path - File path.
+     * @returns `true` when the file exists.
+     */
+    fileExists: (path: string) => boolean;
+    /**
+     * Resolves the directory that relative paths are resolved against.
+     *
+     * @returns The current working directory.
+     */
+    getCurrentDirectory: () => string;
+    /**
+     * Lists the immediate subdirectories of a directory.
+     *
+     * @param path - Directory path.
+     * @returns The immediate subdirectory names.
+     */
+    getDirectories: (path: string) => string[];
+    /**
+     * Lists the files under a directory, filtered by extension and include/exclude patterns.
+     *
+     * @param path - Root directory.
+     * @param extensions - Extensions to include.
+     * @param exclude - Patterns to exclude.
+     * @param include - Patterns to include.
+     * @param depth - Maximum recursion depth.
+     * @returns The matching file paths.
+     */
+    readDirectory: (path: string, extensions?: readonly string[], exclude?: readonly string[], include?: readonly string[], depth?: number) => string[];
+    /**
+     * Reads a file as text.
+     *
+     * @param path - File path.
+     * @returns The file contents, or `undefined` when absent.
+     */
+    readFile: (path: string) => string | undefined;
+}
+/**
+ * A single over-exposed declaration.
+ */
+export interface OverExposureFinding {
+    /**
+    1-based column of the declaration's name.
+     */
+    readonly column: number;
+    /**
+    The current exposure level.
+     */
+    readonly currentExposure: CurrentExposure;
+    /**
+    Absolute path of the file declaring the symbol.
+     */
+    readonly filePath: string;
+    /**
+    `true` when the declaration has no references at all (besides itself).
+     */
+    readonly hasNoReferences: boolean;
+    /**
+     * `true` when the declaration would qualify for a tighter exposure if not for references coming
+     * exclusively from test files — i.e. it is exposed purely for testability.
+     */
+    readonly isForcedByTestOnly: boolean;
+    /**
+    `true` for a class member, `false` for a top-level export.
+     */
+    readonly isMember: boolean;
+    /**
+    1-based line of the declaration's name.
+     */
+    readonly line: number;
+    /**
+    The declared name.
+     */
+    readonly name: string;
+    /**
+     * In a fix run, why this finding was left untouched instead of tightened; `null` when it was
+     * fixed or when the analysis only reported (`shouldFix` off).
+     */
+    readonly skipReason: null | OverExposureSkipReason;
+    /**
+    The exposure the declaration could be tightened to.
+     */
+    readonly suggestedExposure: SuggestedExposure;
+    /**
+    `true` when a fix run tightened this declaration in place. Always `false` in a report run.
+     */
+    readonly wasFixed: boolean;
+}
+/**
+ * Progress reported while analyzing a project, one event per analyzed source file.
+ */
+export interface OverExposureProgress {
+    /**
+    Number of source files fully analyzed before the current one (0-based).
+     */
+    readonly analyzedFileCount: number;
+    /**
+    Absolute (canonical) path of the source file about to be analyzed.
+     */
+    readonly currentFilePath: string;
+    /**
+    Total number of source files that will be analyzed.
+     */
+    readonly totalFileCount: number;
+}
+/**
+ * Why a fix run left a finding untouched:
+ *
+ * - `decorated` — the member carries a decorator, so the modifier insertion point is ambiguous.
+ * - `shared-export` — the `export` keyword is shared with a still-exported sibling declarator.
+ * - `test-only` — the declaration is exposed purely for tests, so tightening would break the test.
+ */
+export type OverExposureSkipReason = 'decorated' | 'shared-export' | 'test-only';
+/**
+ * The (tighter) exposure level a declaration could be reduced to.
+ */
+export type SuggestedExposure = 'file-local' | 'private' | 'protected';
+/**
+ * Lifecycle and framework members invoked by Obsidian or a base class via registration rather than
+ * by references the language service can see. Tightening these would break the framework contract,
+ * so they are never reported.
+ */
+export declare const LIFECYCLE_ALLOWLIST: ReadonlySet<string>;
+/**
+ * Analyzes a project (already loaded into a language service) for over-exposed declarations, and —
+ * when {@link AnalyzeOverExposureParams.shouldFix} is set — tightens every fixable finding in place
+ * via {@link AnalyzeOverExposureParams.writeFile}. Findings that cannot be safely automated (exposed
+ * only for tests, decorated, or sharing an `export` keyword with a still-exported sibling) carry a
+ * {@link OverExposureFinding.skipReason} and are left untouched — unless
+ * {@link AnalyzeOverExposureParams.shouldForce} is set, which additionally tightens the test-only
+ * findings (decorated and shared-export ones still stay skipped).
+ *
+ * @param params - The {@link AnalyzeOverExposureParams}.
+ * @returns The over-exposed declarations, in discovery order.
+ */
+export declare function analyzeOverExposure(params: AnalyzeOverExposureParams): OverExposureFinding[];
+/**
+ * Builds a {@link LanguageServiceHost} backed by an explicit file list and file system.
+ *
+ * @param params - The {@link CreateLanguageServiceHostParams}.
+ * @returns The language-service host.
+ */
+export declare function createLanguageServiceHost(params: CreateLanguageServiceHostParams): LanguageServiceHost;
+/**
+ * Builds a language service over every file in a project's `tsconfig.json`.
+ *
+ * @param params - The {@link CreateProjectLanguageServiceParams}.
+ * @returns A language service ready for {@link analyzeOverExposure}.
+ */
+export declare function createProjectLanguageService(params: CreateProjectLanguageServiceParams): LanguageService;
+/**
+ * Finds over-exposed declarations in a project on disk. When
+ * {@link FindOverExposureParams.shouldFix} is set, each fixable finding is also tightened in place
+ * (rewriting the affected source files via `typescript`'s `sys.writeFile`).
+ *
+ * @param params - The {@link FindOverExposureParams}.
+ * @returns The over-exposed declarations.
+ */
+export declare function findOverExposure(params: FindOverExposureParams): OverExposureFinding[];
+/**
+ * Formats over-exposure findings as a human-readable report, using the grouped layout of ESLint's
+ * `stylish` formatter. Findings are grouped by file and sorted by line: each file is rendered as a
+ * `path` header line, followed by one indented `  line:column  change -- reason` row per finding (the
+ * `line:column` is right-padded so the rows align within a file). Terminals such as VS Code render
+ * each indented `line:column` as a clickable link — resolved against the file header above it — that
+ * jumps straight to the declaration. File groups are separated by a blank line. In a fix run (findings
+ * carrying {@link OverExposureFinding.wasFixed} / {@link OverExposureFinding.skipReason}) each change
+ * row is suffixed with `[fixed]` or `[skipped: …]`, and the trailing summary appends the fixed/skipped
+ * counts.
+ *
+ * @param findings - The findings to format.
+ * @param options - The {@link FormatOverExposureFindingsOptions}.
+ * @returns The report text. Empty-finding input yields a single "no findings" line.
+ */
+export declare function formatOverExposureFindings(findings: readonly OverExposureFinding[], options?: FormatOverExposureFindingsOptions): string;