feat: document eslint-config, alt-gen, and naomiai (#54)

Reviewed-on: https://codeberg.org/nhcarrigan/docs/pulls/54
Co-authored-by: Naomi Carrigan <commits@nhcarrigan.com>
Co-committed-by: Naomi Carrigan <commits@nhcarrigan.com>

.cspell.json

@@ -26,5 +26,9 @@
     "technomancer",
     "Wofi",
     "Dunst",
+    "SonarQube",
+    "Grype",
+    "Syft",
+    "Ghostty"
   ]
 }

astro.config.mjs

@@ -11,10 +11,10 @@ export default defineConfig({
       ThemeSelect: "./src/components/ThemeSelect.astro",
       ThemeProvider: "./src/components/ThemeProvider.astro",
     },
-    title: "Naomi's Documentation",
+    title: "NHCarrigan Docs",
     sidebar: navigation,
     tableOfContents: { minHeadingLevel: 2, maxHeadingLevel: 4},
-    description: "Helpful documentation we want to share with everyone.",
+    description: "This site contains all of the documentation related to NHCarrigan, its Policies, and its Projects.",
     editLink: {
       baseUrl: "https://codeberg.org/nhcarrigan/docs/_edit/main/",
       label: "Edit this page on Codeberg"

src/components/navigation.ts

@@ -114,6 +114,11 @@ export const navigation = [
   {
     label: "Project Documentation",
     items: [
+      {
+        label: "ESLint Config",
+        link: "/projects/eslint-config",
+        badge: { text: "v5.1.0", variant: "tip"}
+      },
       {
         label: "Task Bot",
         link: "/projects/task-bot",
@@ -123,8 +128,18 @@ export const navigation = [
         label: "Translation Bot",
         link: "/projects/translation-bot",
         badge: { text: "v1.0.0", variant: "tip"}
+      },
+      {
+        label: "NaomiAI",
+        link: "/projects/naomiai",
+        badge: { text: "v1.0.0", variant: "tip"}
+      },
+      {
+        label: "AltGenerator",
+        link: "/projects/alt-gen",
+        badge: { text: "v1.0.0", variant: "tip"}
       }
-    ]
+    ].sort((a, b) => a.label.localeCompare(b.label))
   },
   {
     label: "Staff Guidelines",

src/content/docs/dev/style.md

@@ -190,7 +190,7 @@ These rules apply to all TypeScript code, and will run on files in `src/**/*.ts`
 - Variables within the same declaration block must be sorted alphabetically.
 - If using the `Symbol` function, you must include a description.
 - Do not compare to `NaN`, use `Number.isNaN()`.
-- `typeof` comparators must be a vaild return type of `typeof`.
+- `typeof` comparators must be a valid return type of `typeof`.
 - Conditions should always start with the variable, not the constant.
 
 ### 2.1.2. `typescript-eslint` Enforced Rules
@@ -442,7 +442,7 @@ These rules apply to TSX, and will run on files in `src/**/*.tsx`.
 - If a radio button or checkbox is checked, it must be `readonly` or have an `onChange` handler.
 - Default properties should match the property types.
 - Properties, state, and context should always be destructured.
-- Components must always have a nmae.
+- Components must always have a name.
 - A component cannot consume another component's propTypes.
 - PropTypes cannot use `any`, `array`, or `object`.
 - `forwardRef` components must use `ref`.

src/content/docs/intro.mdx

@@ -1,14 +1,14 @@
 ---
-title: Naomi's Documentation
-description: This site contains various information that Naomi felt would be helpful to share.
+title: NHCarrigan Docs
+description: This site contains all of the documentation related to NHCarrigan, its Policies, and its Projects.
 template: splash
 hero:
   tagline:
-    This site contains various information that Naomi felt would be helpful to share.
+    This site contains all of the documentation related to NHCarrigan, its Policies, and its Projects.
   actions:
     - text: Mission Statement
       link: /about/mission/
-      variant: primary
+      variant: secondary
     - text: Code of Conduct
       link: /community/coc/
       variant: secondary

src/content/docs/projects/_template.md

@@ -0,0 +1,37 @@
+---
+title: <app name>
+---
+
+<app name> (hereinafter the "Application") is <description>
+
+## 1. User Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for those interacting with a live instance of the Application.
+
+## 2. Technical Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for those interested in running their own instance of the Application.
+
+## 3. Legal Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for expansions to our legal policies specific to the Application.
+
+## 4. Contributing Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for documentation related to contributing to the Application's codebase.

src/content/docs/projects/alt-gen.md

@@ -0,0 +1,89 @@
+---
+title: AltGenerator
+---
+
+AltGenerator (hereinafter the "Application") is a wrapper around Anthropic's Claude model that allows you to sumbit an image to the LLM and receive descriptive alt-text.
+
+## 1. User Documentation
+
+:::caution[Note]
+We offer free access to this bot within [our Discord server](https://chat.nhcarrigan.com).
+
+For the bot to respond to you in other servers, or via DMs, you will need to subscribe.
+:::
+
+This section is for those interacting with a live instance of the Application.
+
+To interact with the Application, you must send a message (in a server channel it can see and respond to, or in a direct message with the bot). The content of your message **must start with** a mention (or ping) of the bot.
+
+If you are using the Application outside of our server, and have not subscribed, you will be met with a prompt to subscribe:
+
+![](/images/alt-gen/no-subscription.png)
+
+Otherwise, the bot will respond to your query. Note that the bot does NOT look at the text content of your message, only image attachments. 
+
+![](/images/alt-gen/response.png)
+
+To cut down on costs and provide this service at an affordable rate to you, the Application does not track any conversation history. Each message you send is treated as an isolated query and receives a response independent of any prior interactions.
+
+## 2. Technical Documentation
+
+This section is for those interested in running their own instance of the Application.
+
+In order to host your own instance of this application, you will need to complete a few steps.
+
+### 2.1. Discord Application
+
+First, you will need to go through the [Discord Developer Portal](https://discord.com/developers/applications) to set up a new Discord Bot account. The bot will not need any privileged intents.
+
+Once you have the bot set up, save the token in 1password and update the `DISCORD_TOKEN` secret reference in `prod.env`.
+
+You'll also need to set up a Discord webhook for debug logs. Save the URL in 1password and update the `DEBUG_HOOK` secret reference in `prod.env`.
+
+### 2.2. Anthropic
+
+You will need to register for an [Anthropic API account](https://console.anthropic.com). Note that this is NOT the same as a paid Claude account - they are independent services with independent billing.
+
+Under the `Billing` tab, you'll need to load some credits. There is no free tier for this API.
+
+Under the `API Keys` tab, generate an API key for your workspace. Save the key in 1password and update the `ANTHROPIC_TOKEN` secret reference in `prod.env`.
+
+### 2.3. Monetisation
+
+Whether you wish to enable monetisation or not, you'll want to update the logic in `src/index.ts` around line 239 to reflect the behaviour and values relevant to your instance.
+
+For example, you may need to update the SKU in the button with the SKU for your application, or remove the entitlement logic entirely and offer the service for free.
+
+### 2.4. Running the Application
+
+Once you have the Application on a [configured server](/dev/servers), you'll need to run the following commands:
+
+```bash
+pnpm install #install the dependencies
+pnpm build #compile the typescript into javascript
+OP_SERVICE_ACCOUNT_TOKEN=<key> pm2 start 'pnpm start' --name 'naomiai' #start the app as a PM2 process
+```
+
+If you have configured everything correctly, you'll be all set!
+
+## 3. Legal Documentation
+
+This section is for expansions to our legal policies specific to the Application.
+
+### 3.1. Privacy Policy
+
+The Application does not use Discord's Message Content intent. This means that it cannot see the content of ANY message you send unless you explicitly ping the bot (or have DMed the bot directly).
+
+We do not store any data related to the use of this Application.
+
+The image files you consensually submit to the Application as part of normal usage are sent to Anthropic to generate the LLM response. Messages are sent anonymously, and not tied to your user account. However, the files may be processed in accordance with Anthropic's Terms and Privacy Policies.
+
+Your UUID is logged in our support server, with the quantity and cost of tokens consumed in your interaction with the Application. No message content or other information is logged, and these data are solely used to track usage metrics and identify a need to adjust costs.
+
+## 4. Contributing Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for documentation related to contributing to the Application's codebase.

src/content/docs/projects/eslint-config.mdx

@@ -0,0 +1,184 @@
+---
+title: ESLint Config
+---
+
+import { Tabs, TabItem } from "@astrojs/starlight/components";
+
+ESLint Config (hereinafter the "Application") is an `npm` package containing our highly customised set of ESLint rules. Every rule has been explicitly set - there are no default configurations loaded.
+
+## 1. User Documentation
+
+This section is for those interacting with a live instance of the Application.
+
+### 1.1. Installation
+
+To use this linter configuration in your own project, you must be using Node.js. Install the package and the necessary dependency:
+
+<Tabs>
+  <TabItem label="npm">
+    ```bash
+    npm install -D eslint @nhcarrigan/eslint-config
+    ```
+  </TabItem>
+  <TabItem label="yarn">
+    ```bash
+    yarn add --dev eslint @nhcarrigan/eslint-config
+    ```
+  </TabItem>
+  <TabItem label="pnpm">
+    ```bash
+    pnpm install --save-dev eslint @nhcarrigan/eslint-config
+    ```
+  </TabItem>
+</Tabs>
+
+:::caution[Warning!]
+This package requires ESLint v9 and uses a flat config!
+:::
+
+### 1.2. Usage
+
+To begin using this package, you'll need to create an `eslint.config.js` file in the root of your project. To load our configuration exactly as is with no changes, you can copy-paste this snippet:
+
+```js
+import NaomisConfig from "@nhcarrigan/eslint-config";
+
+export default [...NaomisConfig];
+```
+
+Then, to run it, you'll likely want to define a `package.json` script that covers your files. Our configuration can run against:
+
+- `src/**/*.ts`
+- `src/**/*.tsx`
+- `e2e/**/*.spec.ts` (These should be Playwright tests)
+- `test/**/*.spec.ts` (These should be Vitest tests)
+
+An example script for all of these might be:
+
+```json
+{
+  "lint": "eslint src e2e test --max-warnings 0"
+}
+```
+
+### 1.3. Overriding Rules
+
+You may need to tweak some of the rules to fit your needs. It is *highly* recommended that you only adjust rules on a per-file basis. You can extend the configuration by adding your rules *after* you spread our config:
+
+```js
+import NaomisConfig from "@nhcarrigan/eslint-config";
+
+export default [
+  ...NaomisConfig,
+  {
+    files: ["test/**/*.spec.ts"],
+    rules: {
+      "import/no-extraneous-dependencies": "off",
+      "max-nested-callbacks": "off",
+      "@typescript-eslint/consistent-type-assertions": "off",
+      "max-lines-per-function": "off",
+    },
+  },
+];
+```
+
+Note that the `files` key allows you to specify which files receive the rules updates. If omitted, the rule changes will apply to *all* of your files (including those that our configuration might not check!).
+
+## 2. Technical Documentation
+
+This section is for those interested in running their own instance of the Application.
+
+This section is not applicable to this project.
+
+## 3. Legal Documentation
+
+This section is for expansions to our legal policies specific to the Application.
+
+This section is not applicable to this project.
+
+## 4. Contributing Documentation
+
+This section is for documentation related to contributing to the Application's codebase.
+
+:::danger[WAIT!]
+The addition of new rules or packages MUST be discussed on an issue and approved by the NHCarrigan team *before* a pull request is submitted. Pull requests without a related issue will be systematically closed.
+:::
+
+### 4.1. Adding or Updating Rules
+
+When adding new rules to an existing plugin, or changing existing rules, you should find the appropriate file for that plugin within the `src/rules` directory. Each plugin has its own file.
+
+Most of these should be self-explanatory, but there are a couple of caveats:
+
+- The `eslint.ts` file has a `disabledEslintRules` object. This is the **only** place where rules are explicitly turned off, and these are the rules that conflict with an enabled `@typescript-eslint` rule. If you are adding a new `@typescript-eslint` rule that has a documented conflict, be sure to add the relevant `eslint` rule here.
+- The `typescriptEslint.ts` file has a `typescriptEslintRulesWithTypes` object. Certain `@typescript-eslint` rules require type definitions to be generated. However, our project structure excludes tests from being compiled (because they are not production code), so those do not get type definitions. As such, rules that *need* type definitions must go in this object so that they can be run only on `src/**/*.ts`.
+
+### 4.2. Adding Plugins
+
+Adding a new plugin is a much more ambitious change. First, ensure that you are using `pnpm` and you install the plugin **as a pinned dependency**:
+
+```bash
+pnpm install --save-exact <plugin>
+```
+
+Additionally, if the plugin relies on another tool (such as Vitest), add that to the peer dependencies restricted to greater than the current major version.
+
+Once your plugin is installed, you will need to create the rules file in `src/rules` for that plugin. Define a rules object named `<plugin name>Rules`, annotate it as `Linter.RulesRecord`, and export it. This is where your rules will go. HOWEVER:
+
+Before you start adding rules, navigate to the `src/index.ts` file. Import your new rules object, **and** import the newly installed plugin.
+
+Find the appropriate region for the *type* of files your plugin should run on (e.g. TypeScript, Playwright). The plugin will need to be added to the `plugins` property of that object, and here's the catch:
+
+:::tip
+The key name you assign your plugin in the `config.plugins` object will become the key prefix for **all of the plugin rules**.
+
+Say you install a package called `@naomi/eslint-plugin-example`, and it has a rule called `test-rule`. You might load the plugin in the config like so:
+
+```json
+{
+    "example": naomisExamplePlugin
+}
+```
+
+THIS MEANS THAT ALL RULES FOR THIS PLUGIN ARE PREFIXED WITH `example`! Our `test-rule` would then be added to the new ruleset as `example/test-rule`.
+:::
+
+Add your rules to the `rules` property of the same config object you added the plugin to.
+
+If your new plugin should run on multiple file-sets, you'll need to add it to each of the objects for that file set.
+
+### 4.3. Error or Warn?
+
+As a general principle, we want:
+
+- "Error" for rules that should not be violated even in development for temporary testing
+- "Warn" for rules that are safe to ignore while working on the code, but should not be checked in to `main`.
+
+There are a couple of caveats:
+
+- Stylistic rules should always be "warn".
+- Test rules should always be "warn".
+
+With the exception of the `disabledEslintRules` object mentioned earlier, **no rule should be set to `off`**. We do not load any default configurations, so every rule is off by default.
+
+### 4.4. Adding Tests
+
+If you have not added a new plugin, the tests *should* be flexible enough to continue passing as is. If you HAVE added a new plugin:
+
+- If it is a plugin that falls under the "all rules are warn" category, you'll need to create a `<plugin>.spec.ts` file and assert that all rules are set to "warn". You can refer to `playwright.spec.ts` for an example of this.
+- If it is a plugin that runs on all file sets, an assertion for it will need to be added to the `baseProperties` function in `config.spec.ts`.
+- If it is a plugin that runs on a subset of files, an assertion for it will need to be added to the appropriate `it` block for the file subset configs.
+
+In any case, you will likely need to update the number of assertions and the length of the plugins objects.
+
+### 4.5. Testing Changes
+
+Your very first step is to confirm that `pnpm lint` works. This will start by compiling the TypeScript so it can load the updated configuration.
+
+It will then run the new linter configuration *against* the linter project. If your configuration *works*, you should either see a successful run, or a failed run with specific linter issues.
+
+If you instead see a failed run with ESlint errors (not linter errors, but package errors), your configuration has failed to parse and will need to be adjusted.
+
+Once that has passed successfully (including resolving any linter flags), you can proceed to running `pnpm test` to ensure the existing unit tests pass (and any tests you added to cover new plugins).
+
+As always, feel free to reach out to us in [Discord](https://chat.nhcarrigan.com) if you have any questions!~

src/content/docs/projects/naomiai.md

@@ -0,0 +1,89 @@
+---
+title: NaomiAI
+---
+
+NaomiAI, also known as Anthropic Bot, (hereinafter the "Application") is a wrapper around Anthropic's Claude model that allows you to ask questions to the LLM directly through Discord. The Application is designed to respond as if it was a magical girl.
+
+## 1. User Documentation
+
+:::caution[Note]
+We offer free access to this bot within [our Discord server](https://chat.nhcarrigan.com).
+
+For the bot to respond to you in other servers, or via DMs, you will need to subscribe.
+:::
+
+This section is for those interacting with a live instance of the Application.
+
+To interact with the Application, you must send a message (in a server channel it can see and respond to, or in a direct message with the bot). The content of your message **must start with** a mention (or ping) of the bot.
+
+If you are using the Application outside of our server, and have not subscribed, you will be met with a prompt to subscribe:
+
+![](/images/naomiai/no-subscription.png)
+
+Otherwise, the bot will respond to your query:
+
+![](/images/naomiai/response.png)
+
+To cut down on costs and provide this service at an affordable rate to you, the Application does not track any conversation history. Each message you send is treated as an isolated query and receives a response independent of any prior interactions.
+
+## 2. Technical Documentation
+
+This section is for those interested in running their own instance of the Application.
+
+In order to host your own instance of this application, you will need to complete a few steps.
+
+### 2.1. Discord Application
+
+First, you will need to go through the [Discord Developer Portal](https://discord.com/developers/applications) to set up a new Discord Bot account. The bot will not need any privileged intents.
+
+Once you have the bot set up, save the token in 1password and update the `DISCORD_TOKEN` secret reference in `prod.env`.
+
+You'll also need to set up a Discord webhook for debug logs. Save the URL in 1password and update the `DEBUG_HOOK` secret reference in `prod.env`.
+
+### 2.2. Anthropic
+
+You will need to register for an [Anthropic API account](https://console.anthropic.com). Note that this is NOT the same as a paid Claude account - they are independent services with independent billing.
+
+Under the `Billing` tab, you'll need to load some credits. There is no free tier for this API.
+
+Under the `API Keys` tab, generate an API key for your workspace. Save the key in 1password and update the `ANTHROPIC_TOKEN` secret reference in `prod.env`.
+
+### 2.3. Monetisation
+
+Whether you wish to enable monetisation or not, you'll want to update the logic in `src/index.ts` around line 239 to reflect the behaviour and values relevant to your instance.
+
+For example, you may need to update the SKU in the button with the SKU for your application, or remove the entitlement logic entirely and offer the service for free.
+
+### 2.4. Running the Application
+
+Once you have the Application on a [configured server](/dev/servers), you'll need to run the following commands:
+
+```bash
+pnpm install #install the dependencies
+pnpm build #compile the typescript into javascript
+OP_SERVICE_ACCOUNT_TOKEN=<key> pm2 start 'pnpm start' --name 'naomiai' #start the app as a PM2 process
+```
+
+If you have configured everything correctly, you'll be all set!
+
+## 3. Legal Documentation
+
+This section is for expansions to our legal policies specific to the Application.
+
+### 3.1. Privacy Policy
+
+The Application does not use Discord's Message Content intent. This means that it cannot see the content of ANY message you send unless you explicitly ping the bot (or have DMed the bot directly).
+
+We do not store any data related to the use of this Application.
+
+The messages you consensually submit to the Application as part of normal usage are sent to Anthropic to generate the LLM response. Messages are sent anonymously, and not tied to your user account. However, the content of the message may be processed in accordance with Anthropic's Terms and Privacy Policies.
+
+Your UUID is logged in our support server, with the quantity and cost of tokens consumed in your interaction with the Application. No message content or other information is logged, and these data are solely used to track usage metrics and identify a need to adjust costs.
+
+## 4. Contributing Documentation
+
+:::note
+This section is coming soon!
+:::
+
+This section is for documentation related to contributing to the Application's codebase.