longmo-unplugin-info 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 XLor
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,508 @@
+# unplugin-info
+
+[![Demo](https://img.shields.io/badge/unplugin--info-demo-00CCAA)](https://yjl9903.github.io/unplugin-info/)
+[![version](https://img.shields.io/npm/v/unplugin-info?label=unplugin-info)](https://www.npmjs.com/package/unplugin-info)
+[![install size](https://packagephobia.com/badge?p=unplugin-info)](https://packagephobia.com/result?p=unplugin-info)
+[![GitHub License](https://img.shields.io/github/license/yjl9903/unplugin-info)](https://github.com/yjl9903/unplugin-info/blob/main/LICENSE)
+[![CI](https://github.com/yjl9903/unplugin-info/actions/workflows/ci.yml/badge.svg)](https://github.com/yjl9903/unplugin-info/actions/workflows/ci.yml)
+
+Export build information as virutal module.
+
+This plugin helps you add **build timestamp** / **commit SHA** / **CI environment** / `package.json` / ... to your application. So you can easily check whether the production version meets your expectations, or config your application.
+
+> **Migration from v0 to v1**
+>
+> + Move git related information from `~build/info` to `~build/git`
+> + Move CI related information from `~build/info` to `~build/ci`
+> + Remove `commitsSinceLastTag` from `~build/git`
+
+## Installation
+
+```bash
+npm i -D unplugin-info
+```
+
+<details>
+<summary>Vite</summary><br>
+
+```ts
+// vite.config.ts
+
+import Info from 'unplugin-info/vite';
+
+export default defineConfig({
+  plugins: [
+    Info()
+  ]
+});
+```
+
+Full example is located at [examples/vite](https://github.com/yjl9903/unplugin-info/blob/main/examples/vite).
+
+<br></details>
+
+<details>
+<summary>Rollup</summary><br>
+
+```ts
+// rollup.config.js
+
+import Info from 'unplugin-info/rollup';
+
+export default {
+  plugins: [
+    Info()
+  ]
+};
+```
+
+<br></details>
+
+<details>
+<summary>Webpack</summary><br>
+
+```ts
+// webpack.config.js
+
+module.exports = {
+  /* ... */
+  plugins: [
+    require('unplugin-info/webpack')()
+  ]
+};
+```
+
+Full example is located at [examples/webpack](https://github.com/yjl9903/unplugin-info/blob/main/examples/webpack).
+
+<br></details>
+
+<details>
+<summary>Nuxt</summary><br>
+
+```ts
+// nuxt.config.ts
+
+export default defineNuxtConfig({
+  modules: ['unplugin-info/nuxt'],
+  info: {
+    // Your unplugin-info options ...
+  }
+});
+```
+
+Full example is located at [examples/nuxt](https://github.com/yjl9903/unplugin-info/blob/main/examples/nuxt).
+
+<br></details>
+
+<details>
+<summary>Vue CLI</summary><br>
+
+```ts
+// vue.config.js
+
+module.exports = {
+  configureWebpack: {
+    plugins: [
+      require('unplugin-info/webpack')()
+    ]
+  }
+};
+```
+
+<br></details>
+
+<details>
+<summary>Quasar</summary><br>
+
+```ts
+// quasar.conf.js [Vite]
+module.exports = {
+  vitePlugins: [
+    [
+      'unplugin-info/vite',
+      {
+        /* options */
+      }
+    ]
+  ]
+};
+```
+
+```ts
+// quasar.conf.js [Webpack]
+const Info = require('unplugin-info/webpack');
+
+module.exports = {
+  build: {
+    chainWebpack(chain) {
+      chain.plugin('unplugin-info').use(
+        Info()
+      );
+    }
+  }
+};
+```
+
+<br></details>
+
+<details>
+<summary>esbuild</summary><br>
+
+```ts
+// esbuild.config.js
+import { build } from 'esbuild';
+
+build({
+  /* ... */
+  plugins: [
+    require('unplugin-info/esbuild')({
+      /* options */
+    }),
+  ],
+});
+```
+
+<br>
+</details>
+
+<details>
+<summary>Astro</summary><br>
+
+```ts
+// astro.config.mjs
+
+import Info from 'unplugin-info/astro';
+
+export default defineConfig({
+  integrations: [
+    Info()
+  ],
+});
+```
+
+<br>
+</details>
+
+### TypeScript
+
+To make the TypeScript work, you can add `unplugin-info/client` to your corresponding `tsconfig.json`.
+
+```json5
+{
+  "compilerOptions": {
+    // ...
+    "types": [
+      "unplugin-info/client"
+    ],
+  },
+  // ...
+}
+```
+
+Or you can add TypeScript [triple-slash directives](https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html) to your `.d.ts` (i.e. for projects initialized by Vite, it may be `src/env.d.ts`).
+
+```ts
+// Your .d.ts file
+
+/// <reference types="unplugin-info/client" />
+```
+
+Or if you did some advanced modification (see below), you can just copy and paste [client.d.ts](https://github.com/yjl9903/unplugin-info/blob/main/client.d.ts) to your project, and then do anything you want.
+
+## Usage
+
+`unplugin-info` creates several virtual modules, `~build/time`, `~build/git`, `~build/svn`, `~build/ci`, `~build/console`, `~build/meta`, `~build/env`, and `~build/package`.
+
+You can just import these modules as usual, and do anything with them. Common use cases may be like:
+
+```ts
+// main.ts
+
+import now from '~build/time'
+import { sha } from '~build/git'
+import { revision } from '~build/svn'
+
+// console log the build info
+console.log(`Build ${sha} at ${now}`)
+console.log(`SVN Revision: ${revision}`)
+```
+
+```tsx
+// App.tsx
+
+import now from '~build/time'
+
+// Render it in your app
+function App() {
+  return <span>{now.toLocaleString()}</span>
+}
+```
+
+### ~build/time
+
+It exports the timestamp when the vite started.
+
+```ts
+import now from '~build/time'
+
+console.log(now)
+// There will be a log like "Fri Jun 24 2022 16:30:30 GMT+0800 (中国标准时间)"
+```
+
+### ~build/git
+
+It exports the infomation about the current git repo, which is powered by [simple-git](https://www.npmjs.com/package/simple-git).
+
+```ts
+import {
+  github,
+  sha,
+  abbreviatedSha,
+  tag,
+  lastTag,
+  committer,
+  committerEmail,
+  committerDate,
+  author,
+  authorEmail,
+  authorDate,
+  commitMessage
+} from '~build/git';
+
+// ...
+```
+
+> [!NOTE]
+>
+> From `unplugin-info@0.6.0`, the original virtual module called `~build/info` will be renamed to `~build/git`, and the CI/CD related information will be moved to another virtual module called `~build/ci`.
+
+You can even **custom or override the exported git information**.
+
+All the functions will be executed during the generation of `~build/git`, and the return result with its corresponding field name will be merged into `~build/git`. The following example adds another `isClean` field to `~build/git`.
+
+```ts
+// vite.config.ts
+
+import Info from 'unplugin-info/vite';
+
+export default defineConfig({
+  plugins: [
+    Info({
+      git: {
+        // Gets whether this represents a clean working branch.
+        isClean: async (git) => {
+          const status = await git.status()
+          return status.isClean()
+        }
+      }
+    })
+  ]
+});
+```
+
+Full example is located at [examples/vite](https://github.com/yjl9903/unplugin-info/blob/main/examples/vite/vite.config.ts).
+
+### ~build/svn
+
+It exports the information about the current SVN repo, which is powered by executing SVN commands.
+
+```ts
+import {
+  url,
+  repositoryRoot,
+  repositoryUuid,
+  revision,
+  nodeKind,
+  lastChangedRev,
+  lastChangedDate,
+  lastChangedAuthor,
+  sha,
+  abbreviatedSha,
+  commitMessage,
+  author,
+  authorDate,
+  authorEmail,
+  branch,
+  tag,
+  tags,
+  lastTag,
+  describe
+} from '~build/svn';
+
+// ...
+```
+
+> [!NOTE]
+>
+> This module is only available when the project is under SVN version control. If not in an SVN repo, all exported fields will be `null`.
+
+You can also **custom or override the exported SVN information**.
+
+The following example adds another custom field to `~build/svn`.
+
+```ts
+// vite.config.ts
+
+import Info from 'unplugin-info/vite';
+
+export default defineConfig({
+  plugins: [
+    Info({
+      svn: {
+        // Add custom field
+        customInfo: async () => {
+          return 'Custom SVN info';
+        }
+      }
+    })
+  ]
+});
+```
+
+### ~build/ci
+
+It exports the current CI/CD environment information, which is powered by [ci-info](https://github.com/watson/ci-info).
+
+```ts
+import { isCI, isPR, name } from '~build/ci'
+```
+
+### ~build/console
+
+It will print some helpful logs in your browser.
+
+```ts
+import '~build/console';
+```
+
+### ~build/meta
+
+It exports some meta data from the options of the plugin.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    BuildInfo({
+      meta: { message: 'This is set from vite.config.ts' }
+    })
+  ]
+})
+```
+
+You can also generate meta data lazily.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    BuildInfo({
+      meta: async () => ({ message: 'This is set from vite.config.ts' })
+    })
+  ]
+})
+```
+
+Then you can import them in your app.
+
+```ts
+import { message } from '~build/meta'
+
+console.log(message)
+// This is set from vite.config.ts
+```
+
+> [!NOTE]
+>
+> Meta data will be serialized to JSON format, so you should gen it in you `vite.config.ts` and pass the result object.
+
+To get TypeScript support, you can add type declaration in your `env.d.ts` (It is include in the [official Vite project template](https://vitejs.dev/guide/#scaffolding-your-first-vite-project)).
+
+```ts
+declare module '~build/meta' {
+  export const message: string;
+}
+```
+
+Full example is located at [examples/vite](https://github.com/yjl9903/unplugin-info/blob/main/examples/vite/vite.config.ts).
+
+### ~build/env
+
+> [!NOTE]
+>
+> Now it only suports for Vite.
+
+It exports some environment data from the options of the plugin.
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    BuildInfo({
+      env: { BUILD_MESSAGE: 'This is a default value set from vite.config.ts' }
+    })
+  ]
+})
+```
+
+Compared with `~build/meta`, `~build/env` is targeted at accessing environment variables for the SSR runtime (like Nuxt, Remix, Astro, and so on).
+
+Then you can import them in your Vite app.
+
+```ts
+import { BUILD_MESSAGE } from '~build/env'
+
+console.log(BUILD_MESSAGE)
+```
+
+In the client-side, this will always output `This is a default value set from vite.config.ts`.
+
+But in the server-side, the output log is determined by the corresponding environment variable `process.env.BUILD_MESSAGE`.
+
+To get TypeScript support, you can add type declaration in your `env.d.ts` (It is include in the [official Vite project template](https://vitejs.dev/guide/#scaffolding-your-first-vite-project)).
+
+```ts
+declare module '~build/env' {
+  export const BUILD_MESSAGE: string;
+}
+```
+
+### ~build/package
+
+It exports the information of the current `package.json`.
+
+```ts
+import { name, version } from '~build/package';
+```
+
+You can also **control which fields should be exported**. By default, we only export fields name, version, description, keywords, license, author from your package.json.
+
+```ts
+// vite.config.ts
+
+import Info from 'unplugin-info/vite';
+
+export default defineConfig({
+  plugins: [
+    Info({
+      package: {
+        dependencies: true
+      }
+    })
+  ]
+});
+```
+
+Full example is located at [examples/vite](https://github.com/yjl9903/unplugin-info/blob/main/examples/vite/vite.config.ts).
+
+## Relationship with [vite-plugin-info](https://www.npmjs.com/package/vite-plugin-info)
+
+This pacakge was initially called [vite-plugin-info](https://www.npmjs.com/package/vite-plugin-info). It has been refactored using [unplugin](https://www.npmjs.com/package/unplugin) to support additional tools, including Webpack and so on.
+
+We recommend migrating from [vite-plugin-info](https://www.npmjs.com/package/vite-plugin-info) to [unplugin-info](https://www.npmjs.com/package/unplugin-info), as [unplugin-info](https://www.npmjs.com/package/unplugin-info) will continue to be maintained and new features will be added.
+
+However, you can still use [vite-plugin-info](https://www.npmjs.com/package/vite-plugin-info), as it works fine. Thanks to Vite's compatibility, and the source code of [vite-plugin-info](https://www.npmjs.com/package/vite-plugin-info) can be founded [here](https://github.com/yjl9903/unplugin-info/tree/vite-plugin-info).
+
+## License
+
+MIT License © 2023 [XLor](https://github.com/yjl9903)

package/client.d.ts

@@ -0,0 +1,106 @@
+declare module '~build/time' {
+  const time: Date;
+
+  export = time;
+}
+
+declare module '~build/git' {
+  /** Github repo url */
+  export const github: string | null;
+
+  /** The current branch */
+  export const branch: string;
+
+  /** SHA of the current commit */
+  export const sha: string;
+
+  /** The first 10 chars of the current SHA */
+  export const abbreviatedSha: string;
+
+  /** The tag for the current SHA (or `null` if no tag exists) */
+  export const tag: string | null;
+
+  /** The tags for the current SHA */
+  export const tags: string[] | null;
+
+  /** Tag for the closest tagged ancestor (or `null` if no ancestor is tagged) */
+  export const lastTag: string | null;
+
+  /** Output of `git describe --always` for the current commit */
+  export const describe: string;
+
+  /** The committer of the current SHA */
+  export const committer: string;
+
+  /** The committer email of the current SHA */
+  export const committerEmail: string;
+
+  /** The commit date of the current SHA */
+  export const committerDate: string;
+
+  /** The author for the current SHA */
+  export const author: string;
+
+  /** The author email for the current SHA */
+  export const authorEmail: string;
+
+  /** The authored date for the current SHA */
+  export const authorDate: string;
+
+  /** The commit message for the current SHA */
+  export const commitMessage: string;
+}
+
+declare module '~build/ci' {
+  /**
+   * Returns a boolean. Will be `true` if the code is running on a CI server,
+   * otherwise `false`.
+   *
+   * Some CI servers not listed here might still trigger the `ci.isCI`
+   * boolean to be set to `true` if they use certain vendor neutral environment
+   * variables. In those cases `ci.name` will be `null` and no vendor specific
+   * boolean will be set to `true`.
+   */
+  export const isCI: boolean;
+
+  /**
+   * Returns a boolean if PR detection is supported for the current CI server.
+   * Will be `true` if a PR is being tested, otherwise `false`. If PR detection is
+   * not supported for the current CI server, the value will be `null`.
+   */
+  export const isPR: boolean | null;
+
+  /** CI environment name */
+  export const name: string | null;
+}
+
+declare module '~build/console' {
+  /**
+   * Print build info
+   */
+  export const print: () => void;
+}
+
+declare module '~build/meta' {}
+
+declare module '~build/env' {}
+
+declare module '~build/package' {
+  /** Package name */
+  export const name: string;
+
+  /** Package version */
+  export const version: string;
+
+  /** Package description */
+  export const description: string;
+
+  /** Package keywords */
+  export const keywords: string[];
+
+  /** Package license */
+  export const license: string;
+
+  /** Package author */
+  export const author: string;
+}

package/dist/astro.cjs

@@ -0,0 +1,25 @@
+'use strict';
+
+const vite = require('./vite.cjs');
+require('./shared/longmo-unplugin-info.D5mpeSYM.cjs');
+require('node:path');
+require('node:process');
+require('unplugin');
+require('ci-info');
+require('simple-git');
+require('git-url-parse');
+require('node:child_process');
+require('node:util');
+require('node:fs');
+
+const astro = (options = {}) => ({
+  name: "unplugin-info",
+  hooks: {
+    "astro:config:setup": async (astro) => {
+      astro.config.vite.plugins ||= [];
+      astro.config.vite.plugins.push(vite(options));
+    }
+  }
+});
+
+module.exports = astro;

package/dist/astro.d.cts

@@ -0,0 +1,11 @@
+import { O as Options } from './shared/longmo-unplugin-info.zS6I--Tu.cjs';
+import 'simple-git';
+
+declare const _default: (options?: Options) => {
+    name: string;
+    hooks: {
+        'astro:config:setup': (astro: any) => Promise<void>;
+    };
+};
+
+export = _default;

package/dist/astro.d.mts

@@ -0,0 +1,11 @@
+import { O as Options } from './shared/longmo-unplugin-info.zS6I--Tu.mjs';
+import 'simple-git';
+
+declare const _default: (options?: Options) => {
+    name: string;
+    hooks: {
+        'astro:config:setup': (astro: any) => Promise<void>;
+    };
+};
+
+export { _default as default };

package/dist/astro.d.ts

@@ -0,0 +1,11 @@
+import { O as Options } from './shared/longmo-unplugin-info.zS6I--Tu.js';
+import 'simple-git';
+
+declare const _default: (options?: Options) => {
+    name: string;
+    hooks: {
+        'astro:config:setup': (astro: any) => Promise<void>;
+    };
+};
+
+export = _default;