@venizia/ignis-docs 0.0.6-0 → 0.0.6-2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (32) hide show
  1. package/package.json +1 -1
  2. package/wiki/best-practices/architectural-patterns.md +0 -2
  3. package/wiki/best-practices/code-style-standards/index.md +0 -1
  4. package/wiki/best-practices/code-style-standards/tooling.md +0 -3
  5. package/wiki/best-practices/contribution-workflow.md +12 -12
  6. package/wiki/best-practices/index.md +4 -14
  7. package/wiki/guides/core-concepts/application/bootstrapping.md +6 -7
  8. package/wiki/guides/core-concepts/dependency-injection.md +3 -4
  9. package/wiki/guides/core-concepts/persistent/datasources.md +4 -5
  10. package/wiki/guides/get-started/5-minute-quickstart.md +4 -5
  11. package/wiki/guides/get-started/philosophy.md +12 -24
  12. package/wiki/guides/index.md +2 -9
  13. package/wiki/guides/reference/mcp-docs-server.md +13 -13
  14. package/wiki/guides/tutorials/building-a-crud-api.md +9 -9
  15. package/wiki/guides/tutorials/complete-installation.md +11 -12
  16. package/wiki/guides/tutorials/ecommerce-api.md +1 -1
  17. package/wiki/guides/tutorials/testing.md +3 -4
  18. package/wiki/index.md +8 -14
  19. package/wiki/references/base/bootstrapping.md +0 -1
  20. package/wiki/references/base/dependency-injection.md +1 -1
  21. package/wiki/references/base/filter-system/default-filter.md +2 -3
  22. package/wiki/references/base/filter-system/index.md +1 -1
  23. package/wiki/references/base/repositories/advanced.md +1 -1
  24. package/wiki/references/base/repositories/mixins.md +2 -3
  25. package/wiki/references/index.md +2 -9
  26. package/wiki/references/src-details/boot.md +0 -379
  27. package/wiki/references/src-details/core.md +0 -263
  28. package/wiki/references/src-details/dev-configs.md +0 -298
  29. package/wiki/references/src-details/docs.md +0 -71
  30. package/wiki/references/src-details/helpers.md +0 -211
  31. package/wiki/references/src-details/index.md +0 -86
  32. package/wiki/references/src-details/inversion.md +0 -340
package/wiki/references/src-details/core.md DELETED
@@ -1,263 +0,0 @@
1
- # Package: `@venizia/ignis`
2
-
3
- Detailed breakdown of the core framework directory structure.
4
-
5
- ## Quick Reference
6
-
7
- **Package:** Core framework with fundamental building blocks, architectural layers, and modular features.
8
-
9
- ### Top-Level Directories
10
-
11
- | Directory | Primary Focus | Key Components |
12
- |-----------|---------------|----------------|
13
- | **`base`** | Core architecture | Applications, Controllers, Repositories, Services, Models |
14
- | **`components`** | Pluggable features | Auth, Swagger, HealthCheck, SocketIO |
15
- | **`helpers`** | Utilities | DI (extended), Re-exports from `@venizia/ignis-helpers` |
16
- | **`common`** | Shared code | Constants, bindings, types, environments |
17
- | **`utilities`** | Pure functions | Crypto, date, parse, performance, schema |
18
- | **`__tests__`** | Tests | Integration and E2E tests |
19
-
20
- ## Project Structure Overview
21
-
22
- Top-level breakdown of the `src` directory:
23
-
24
- | Folder | Purpose |
25
- | :--------------- | :--------------------------------------------------------------------------------------------------------------------- |
26
- | **`__tests__`** | Contains integration and end-to-end tests for the framework's features. |
27
- | **`base`** | The core building blocks and abstract classes of the framework. This is where the fundamental architecture is defined. |
28
- | **`common`** | A directory for code that is shared and used across the entire framework. |
29
- | **`components`** | A collection of ready-to-use, high-level components that can be plugged into an Ignis application. |
30
- | **`helpers`** | Contains core extensions (like Inversion) and re-exports from `@venizia/ignis-helpers`. |
31
- | **`utilities`** | A collection of pure, standalone utility functions. |
32
-
33
- ---
34
-
35
- ## Detailed Sections
36
-
37
- ### `__tests__`
38
-
39
- This directory is dedicated to the framework's test suite.
40
-
41
- | File/Folder | Purpose/Key Details |
42
- | :---------------------- | :------------------------------------------------------------------------------------------------------------------------------- |
43
- | `jwt/` | Contains test cases specifically for the JWT authentication functionality, demonstrating how tokens are generated and validated. |
44
- | `jwt/test-cases/jwt.ts` | Example: defines `TestCase001` to check JWT creation. |
45
-
46
- ### `base`
47
-
48
- This is the foundational layer of Ignis, defining the core architecture and abstract classes that other parts of the framework extend or implement.
49
-
50
- #### `base/applications`
51
-
52
- | File/Folder | Purpose/Key Details |
53
- | :------------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
54
- | `abstract.ts` | Defines `AbstractApplication`, the base class for Ignis applications. Handles core server setup (Hono instance, runtime detection for Bun/Node.js), environment validation, and route inspection. Mandates abstract methods for middleware setup and configuration. |
55
- | `base.ts` | Extends `AbstractApplication` to provide `BaseApplication`, implementing common functionalities like component, controller, service, repository, and datasource registration. Includes default middleware registration (e.g., error handling, favicon, request tracking) and startup information logging. Integrates with `@venizia/ignis-boot` for automatic artifact discovery when `bootOptions` is configured. |
56
- | `types.ts` | Contains interfaces for application configurations (`IApplicationConfigs`), application information (`IApplicationInfo`), and various middleware options (e.g., `ICORSOptions`, `ICSRFOptions`). Now includes `IBootableApplication` interface for boot system integration. |
57
-
58
- #### `base/components`
59
-
60
- | File/Folder | Purpose/Key Details |
61
- | :---------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
62
- | `base.ts` | Defines `BaseComponent`, the abstract class for all pluggable components. Manages component-specific bindings and a `configure()` method for setup logic. |
63
-
64
- #### `base/controllers`
65
-
66
- | File/Folder | Purpose/Key Details |
67
- | :------------ | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
68
- | `abstract.ts` | Defines `AbstractController`, an abstract class providing core controller functionalities like `getRouteConfigs` for standardizing route configurations, and `registerRoutesFromRegistry()` for automatically registering decorator-based routes. |
69
- | `base.ts` | Extends `AbstractController` to provide `BaseController`, an abstract class for handling HTTP requests. Integrates with `@hono/zod-openapi` for route definition and OpenAPI schema generation. Key methods include `defineRoute` and `bindRoute`. |
70
- | `factory/` | Contains the `ControllerFactory` and related helpers for generating controllers. |
71
- | `factory/controller.ts` | Provides `ControllerFactory` to generate pre-configured CRUD controllers from a given entity and repository. |
72
- | `factory/definition.ts` | Exports route definition helpers. |
73
- | `common/` | Contains shared types (`types.ts`) and constants (`constants.ts`) for the controller layer. |
74
-
75
- #### `base/datasources`
76
-
77
- | File/Folder | Purpose/Key Details |
78
- | :---------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
79
- | `base.ts` | Contains `AbstractDataSource` and `BaseDataSource`, abstract classes for managing database connections. They define methods for configuration (`configure()`) and retrieving connection strings. |
80
- | `types.ts` | Defines `IDataSource` interface and `TDataSourceDriver` (e.g., `node-postgres`). |
81
-
82
- #### `base/helpers`
83
-
84
- | File/Folder | Purpose/Key Details |
85
- | :---------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
86
- | `base.ts` | `BaseHelper` is a generic base class providing common utilities like a logger instance and scope management. Many other helpers and components extend this class. |
87
-
88
- #### `base/metadata`
89
-
90
- This directory centralizes the metadata handling for decorators, crucial for Ignis's DI and routing systems.
91
-
92
- | File/Folder | Purpose/Key Details |
93
- | :--------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
94
- | `injectors.ts` | Defines the `@injectable` and `@inject` decorators for dependency injection. |
95
- | `persistents.ts` | Contains `@model` and `@datasource` decorators for marking classes as data models or data sources, respectively. |
96
- | `routes.ts` | Defines the `@controller` decorator for marking classes as API controllers, and the new decorator set (`@api`, `@get`, `@post`, etc.) for defining routes on controller methods. |
97
-
98
- #### `base/middlewares`
99
-
100
- A collection of essential, low-level middlewares used by the application.
101
-
102
- | File/Folder | Purpose/Key Details |
103
- | :-------------------------------- | :------------------------------------------------------------------------------------------------------------- |
104
- | `app-error.middleware.ts` | Global error handling middleware that catches `ApplicationError` instances and formats responses consistently. |
105
- | `emoji-favicon.middleware.ts` | Serves a simple emoji favicon for the application. |
106
- | `not-found.middleware.ts` | Handles 404 Not Found errors. |
107
- | `request-spy.middleware.ts` | Logs incoming requests, parses request body, and adds a unique request ID for tracing. |
108
-
109
- #### `base/mixins`
110
-
111
- Contains mixins to extend the functionality of core classes, particularly `AbstractApplication`.
112
-
113
- | File/Folder | Purpose/Key Details |
114
- | :-------------------- | :------------------------------------------------------- |
115
- | `component.mixin.ts` | Adds `component()` and `registerComponents()` methods. |
116
- | `controller.mixin.ts` | Adds `controller()` and `registerControllers()` methods. |
117
- | `repository.mixin.ts` | Adds `dataSource()` and `repository()` methods. |
118
- | `service.mixin.ts` | Adds `service()` method. |
119
- | `types.ts` | Defines interfaces and types (`TMixinOpts`, `IComponentMixin`, `IControllerMixin`, etc.). |
120
-
121
- All registration methods accept an optional `opts?: TMixinOpts` parameter for custom binding configuration:
122
-
123
- ```typescript
124
- type TMixinOpts<Args extends AnyObject = any> = {
125
- binding: { namespace: string; key: string };
126
- args?: Args;
127
- };
128
-
129
- // Example: Custom binding key
130
- this.controller(UserController, {
131
- binding: { namespace: 'controllers', key: 'CustomUserController' }
132
- });
133
- ```
134
-
135
- #### `base/models`
136
-
137
- Defines base classes and utilities for data models, often used with Drizzle ORM.
138
-
139
- | File/Folder | Purpose/Key Details |
140
- | :--------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
141
- | `base.ts` | Contains `BaseEntity`, a base class for models that wrap Drizzle ORM schemas and provide methods for generating Zod schemas for CRUD operations. |
142
- | `common/` | Contains shared types (`types.ts`) and constants (`constants.ts`) for the model layer, including definitions for `IdType`, `TTableSchemaWithId`, and `SchemaTypes`. |
143
- | `enrichers/` | Sub-directory for functions that add common fields to Drizzle ORM schemas. |
144
- | `enrichers/data-type.enricher.ts` | Adds generic data type columns (number, text, byte, JSON, boolean). |
145
- | `enrichers/id.enricher.ts` | Adds `id` column with number (serial) or string (UUID) types. |
146
- | `enrichers/principal.enricher.ts` | Adds polymorphic fields for associating with different principal types. |
147
- | `enrichers/tz.enricher.ts` | Adds `createdAt` and `modifiedAt` timestamp columns. |
148
- | `enrichers/user-audit.enricher.ts` | Adds `createdBy` and `modifiedBy` fields. Supports `allowAnonymous` option to require or allow anonymous user context. |
149
-
150
- #### `base/providers`
151
-
152
- | File/Folder | Purpose/Key Details |
153
- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
154
- | `base.ts` | Contains `BaseProvider`, an abstract class for creating custom dependency injection providers. Providers are used for dependencies that require complex instantiation logic. |
155
-
156
- #### `base/repositories`
157
-
158
- | File/Folder | Purpose/Key Details |
159
- | :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------- |
160
- | `core/base.ts` | Defines `AbstractRepository`, the abstract base class for all repositories. |
161
- | `core/readable.ts` | Implements `ReadableRepository` for **read-only** data access. |
162
- | `core/persistable.ts` | Implements `PersistableRepository`, extending `ReadableRepository` with write capabilities (`create`, `update`, `delete`). |
163
- | `core/default-crud.ts` | Provides `DefaultCRUDRepository`, the standard full CRUD repository that extends `PersistableRepository`. |
164
- | `common/types.ts` | Defines interfaces for filters (`TFilter`), WHERE clauses (`TWhere`), and repository operations (`IRepository`, `IPersistableRepository`). |
165
-
166
- #### `base/services`
167
-
168
- | File/Folder | Purpose/Key Details |
169
- | :---------- | :------------------------------------------------------------------------ |
170
- | `base.ts` | Defines `BaseService`, the abstract base for all business logic services. |
171
- | `types.ts` | Defines `IService` and `ICrudService` interfaces. |
172
-
173
- ### `common`
174
-
175
- This directory holds various shared definitions and constants used throughout the framework.
176
-
177
- | File/Folder | Purpose/Key Details |
178
- | :---------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
179
- | `bindings.ts` | Defines `BindingNamespaces` (e.g., `COMPONENT`, `SERVICE`) and `BindingKeys` (`APPLICATION_INSTANCE`, `APPLICATION_SERVER`) for the dependency injection container. |
180
- | `constants.ts` | Contains application-wide constants such as `HTTP` methods and status codes, `MimeTypes`, `RuntimeModules` (Bun, Node.js), and `DataTypes`. |
181
- | `environments.ts` | Defines `Environment` types (e.g., `DEVELOPMENT`, `PRODUCTION`) and `EnvironmentKeys` for structured access to environment variables. |
182
- | `statuses.ts` | Defines various status constants like `UserStatuses`, `RoleStatuses`, and `MigrationStatuses`. |
183
- | `types.ts` | Contains general TypeScript utility types like `ValueOrPromise`, `AnyObject`, `IClass`, `TMixinTarget`, and `IProvider`. |
184
-
185
- ### `components`
186
-
187
- This directory contains high-level, pluggable components that encapsulate specific features, extending the application's functionality.
188
-
189
- #### `components/auth/`
190
-
191
- Provides authentication and authorization features.
192
-
193
- | File/Folder | Purpose/Key Details |
194
- | :--------------------------------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------- |
195
- | `authenticate/` | JWT-based authentication. |
196
- | `authenticate/common/` | Constants, keys, and types for authentication. |
197
- | `authenticate/component.ts` | `AuthenticateComponent` registers authentication services and controllers. |
198
- | `authenticate/controllers/factory.ts` | `defineAuthController` creates a pre-configured controller with sign-in, sign-up, change password, and "who am I" routes. |
199
- | `authenticate/services/jwt-token.service.ts` | `JWTTokenService` handles JWT generation, verification, and payload encryption/decryption. |
200
- | `authenticate/strategies/` | Authentication strategies, e.g., `JWTAuthenticationStrategy`. |
201
- | `authenticate/strategies/strategy-registry.ts` | `AuthenticationStrategyRegistry` manages and provides authentication strategies. |
202
- | `models/` | Data models (entities and requests) for authentication, including `User`, `Role`, `Permission`, `SignInRequestSchema`, `SignUpRequestSchema`, etc. |
203
-
204
- #### `components/health-check/`
205
-
206
- Adds a simple `/health` endpoint to the application.
207
-
208
- | File/Folder | Purpose/Key Details |
209
- | :-------------- | :------------------------------------------------------------ |
210
- | `component.ts` | `HealthCheckComponent` registers the `HealthCheckController`. |
211
- | `controller.ts` | `HealthCheckController` defines the `/health` route. |
212
-
213
- #### `components/request-tracker/`
214
-
215
- Logs and traces incoming requests.
216
-
217
- | File/Folder | Purpose/Key Details |
218
- | :------------- | :------------------------------------------------------------------------------------------------------ |
219
- | `component.ts` | `RequestTrackerComponent` integrates `hono/request-id` and `RequestSpyMiddleware` for request tracking. |
220
-
221
- #### `components/socket-io/`
222
-
223
- Integrates Socket.IO for real-time communication.
224
-
225
- | File/Folder | Purpose/Key Details |
226
- | :------------- | :--------------------------------------------------------------------------------------------------------------- |
227
- | `component.ts` | `SocketIOComponent` sets up the Socket.IO server, integrates with Redis for scaling, and handles authentication. |
228
-
229
- #### `components/swagger/`
230
-
231
- Generates interactive OpenAPI documentation.
232
-
233
- | File/Folder | Purpose/Key Details |
234
- | :------------- | :-------------------------------------------------------------------------------------------------------------------------------------- |
235
- | `component.ts` | `SwaggerComponent` configures Swagger UI using `@hono/zod-openapi` and `@hono/swagger-ui`, generating documentation from route schemas. |
236
-
237
- ### `helpers`
238
-
239
- Contains framework extensions and utilities.
240
-
241
- | File/Folder | Purpose/Key Details |
242
- | :---------- | :--------------------------------------------------------------------------------------------------------------------------------------------------------- |
243
- | `inversion/`| **Framework DI Extension**: Extends `@venizia/ignis-inversion` to provide application-aware dependency injection with logging and enhanced metadata support. |
244
- | `index.ts` | Re-exports extensions and utilities from `@venizia/ignis-helpers`. |
245
-
246
- ### `utilities`
247
-
248
- This directory contains pure, standalone utility functions that perform common, stateless operations.
249
-
250
- | File/Folder | Purpose/Key Details |
251
- | :----------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
252
- | `crypto.utility.ts` | Provides a `hash()` function for cryptographic hashing (SHA256, MD5). |
253
- | `date.utility.ts` | Date and time manipulation functions (`dayjs` integration, `sleep`, `isWeekday`, `getDateTz`, `hrTime`). |
254
- | `module.utility.ts` | `validateModule()` to check for module existence at runtime. |
255
- | `parse.utility.ts` | Functions for type checking (`isInt`, `isFloat`), type conversion (`int`, `float`, `toBoolean`), string/object transformation (`toCamel`, `keysToCamel`), array transformations (`parseArrayToRecordWithKey`, `parseArrayToMapWithKey`), and `getUID()` for unique IDs. |
256
- | `performance.utility.ts` | Utilities for measuring code execution time (`executeWithPerformanceMeasure`, `getPerformanceCheckpoint`, `getExecutedPerformance`). |
257
- | `promise.utility.ts` | Helper functions for Promises (`executePromiseWithLimit`, `isPromiseLike`, `transformValueOrPromise`, `getDeepProperty`). |
258
- | `request.utility.ts` | Utilities for handling HTTP request data, such as `parseMultipartBody` for multipart form data. |
259
- | `schema.utility.ts` | Helper functions and predefined schemas for `zod` and `@hono/zod-openapi` (`jsonContent`, `jsonResponse`, `requiredString`, `AnyObjectSchema`, `IdParamsSchema`, `UUIDParamsSchema`). |
260
-
261
- ---
262
-
263
- This detailed breakdown illustrates the modular and layered design of the Ignis framework, emphasizing its extensibility and adherence to robust architectural patterns.
package/wiki/references/src-details/dev-configs.md DELETED
@@ -1,298 +0,0 @@
1
- # Package: `@venizia/dev-configs`
2
-
3
- ## Overview
4
-
5
- The `@venizia/dev-configs` package provides centralized, shared development configurations for all packages in the Venizia/Ignis monorepo. This ensures consistent code style, linting rules, and TypeScript configurations across the entire project.
6
-
7
- ## Package Information
8
-
9
- | Property | Value |
10
- |----------|-------|
11
- | **Package Name** | `@venizia/dev-configs` |
12
- | **Location** | `packages/dev-configs/` |
13
- | **Purpose** | Centralized development configurations |
14
- | **Dependencies** | `@minimaltech/eslint-node` |
15
-
16
- ## Exports
17
-
18
- | Export Path | Type | Description |
19
- |-------------|------|-------------|
20
- | `@venizia/dev-configs` | Module | Named exports: `eslintConfigs`, `prettierConfigs` |
21
- | `@venizia/dev-configs/tsconfig.base.json` | JSON | Base TypeScript configuration |
22
- | `@venizia/dev-configs/tsconfig.common.json` | JSON | Common TypeScript config for packages |
23
-
24
- ### Named Exports
25
-
26
- ```typescript
27
- import { eslintConfigs, prettierConfigs } from '@venizia/dev-configs';
28
- ```
29
-
30
- - **`eslintConfigs`**: `Linter.Config[]` - ESLint flat config array
31
- - **`prettierConfigs`**: `Config` - Prettier configuration object
32
-
33
- ---
34
-
35
- ## ESLint Configuration
36
-
37
- ### Usage
38
-
39
- Create an `eslint.config.mjs` file in your package:
40
-
41
- ```javascript
42
- import { eslintConfigs } from '@venizia/dev-configs';
43
-
44
- export default eslintConfigs;
45
- ```
46
-
47
- ### Extending the Config
48
-
49
- To add package-specific rules:
50
-
51
- ```javascript
52
- import { eslintConfigs } from '@venizia/dev-configs';
53
-
54
- const configs = [
55
- ...eslintConfigs,
56
- {
57
- // Add custom ignores
58
- ignores: ['custom-folder/**'],
59
- },
60
- {
61
- // Add custom rules
62
- rules: {
63
- 'no-console': 'warn',
64
- },
65
- },
66
- ];
67
-
68
- export default configs;
69
- ```
70
-
71
- ### Included Rules
72
-
73
- | Rule | Setting | Description |
74
- |------|---------|-------------|
75
- | `@typescript-eslint/no-explicit-any` | `off` | Allows `any` type usage |
76
- | *Base rules* | *inherited* | All rules from `@minimaltech/eslint-node` |
77
-
78
- ---
79
-
80
- ## Prettier Configuration
81
-
82
- ### Usage
83
-
84
- Create a `.prettierrc.mjs` file in your package:
85
-
86
- ```javascript
87
- import { prettierConfigs } from '@venizia/dev-configs';
88
-
89
- export default prettierConfigs;
90
- ```
91
-
92
- ### Configuration Options
93
-
94
- | Option | Value | Description |
95
- |--------|-------|-------------|
96
- | `bracketSpacing` | `true` | Spaces inside object braces: `{ foo: bar }` |
97
- | `singleQuote` | `false` | Use double quotes (changed from single) |
98
- | `printWidth` | `100` | Maximum line width |
99
- | `tabWidth` | `2` | Spaces per indentation level |
100
- | `trailingComma` | `'all'` | Trailing commas everywhere possible |
101
- | `arrowParens` | `'avoid'` | Omit parens for single arrow function params |
102
- | `semi` | `true` | Add semicolons at statement ends |
103
-
104
- ### Prettier Ignore
105
-
106
- Create a `.prettierignore` file in your package:
107
-
108
- ```
109
- dist
110
- node_modules
111
- *.log
112
- .*-audit.json
113
- ```
114
-
115
- Recommended ignore patterns:
116
- - `dist` - Build output
117
- - `node_modules` - Dependencies
118
- - `*.log` - Log files
119
- - `.*-audit.json` - Audit files
120
- - `coverage` - Test coverage (if applicable)
121
- - `*.min.js` - Minified files (if applicable)
122
-
123
-
124
- ## TypeScript Configuration
125
-
126
- ### Base Configuration (`tsconfig.base.json`)
127
-
128
- The base configuration includes all compiler options suitable for Node.js/Bun TypeScript projects.
129
-
130
- #### Usage
131
-
132
- ```json
133
- {
134
- "$schema": "http://json.schemastore.org/tsconfig",
135
- "extends": "@venizia/dev-configs/tsconfig.base.json",
136
- "compilerOptions": {
137
- "outDir": "dist",
138
- "rootDir": "src"
139
- },
140
- "include": ["src"],
141
- "exclude": ["node_modules", "dist"]
142
- }
143
- ```
144
-
145
- #### Compiler Options Summary
146
-
147
- | Category | Options |
148
- |----------|---------|
149
- | **Target** | ES2022, lib: ES2022 |
150
- | **Modules** | Node16, resolveJsonModule, esModuleInterop |
151
- | **Decorators** | experimentalDecorators, emitDecoratorMetadata |
152
- | **Emit** | declaration, declarationMap, sourceMap |
153
- | **Strict** | strict (with selective relaxations) |
154
- | **Performance** | incremental, skipLibCheck |
155
-
156
- #### Strict Mode Configuration
157
-
158
- | Option | Value | Rationale |
159
- |--------|-------|-----------|
160
- | `strict` | `true` | Enable all strict checks |
161
- | `noImplicitAny` | `false` | Allow implicit any for flexibility |
162
- | `strictNullChecks` | `true` | Enforce null safety |
163
- | `strictPropertyInitialization` | `false` | Allow uninitialized properties (for DI) |
164
- | `useUnknownInCatchVariables` | `false` | Use `any` in catch blocks |
165
-
166
- ### Common Configuration (`tsconfig.common.json`)
167
-
168
- Extends the base config with settings for standard packages:
169
-
170
- ```json
171
- {
172
- "$schema": "http://json.schemastore.org/tsconfig",
173
- "extends": "@venizia/dev-configs/tsconfig.common.json",
174
- "compilerOptions": {
175
- "outDir": "dist",
176
- "rootDir": "src",
177
- "baseUrl": "src",
178
- "paths": {
179
- "@/*": ["./*"]
180
- }
181
- },
182
- "include": ["src"],
183
- "exclude": ["node_modules", "dist"]
184
- }
185
- ```
186
-
187
- **Note:** Path-related options (`outDir`, `rootDir`, `baseUrl`, `paths`, `include`, `exclude`) must be defined in each package's tsconfig.json as they are resolved relative to the config file location.
188
-
189
-
190
- ## Project Structure
191
-
192
- ```
193
- packages/dev-configs/
194
- ├── package.json
195
- ├── tsconfig.json
196
- ├── src/
197
- │ ├── index.ts # Re-exports all configs
198
- │ ├── eslint.ts # ESLint configuration
199
- │ └── prettier.ts # Prettier configuration
200
- ├── tsconfig/
201
- │ ├── tsconfig.base.json # Base TypeScript config
202
- │ └── tsconfig.common.json # Common package config
203
- ├── prettier/
204
- │ └── .prettierignore # Prettier ignore patterns
205
- ├── scripts/
206
- │ ├── build.sh
207
- │ ├── clean.sh
208
- │ └── rebuild.sh
209
- └── dist/ # Built output
210
- ├── index.js / .d.ts
211
- ├── eslint.js / .d.ts
212
- └── prettier.js / .d.ts
213
- ```
214
-
215
-
216
- ## Integration Guide
217
-
218
- ### Adding to a New Package
219
-
220
- 1. Add the dependency to your `package.json`:
221
-
222
- ```json
223
- {
224
- "devDependencies": {
225
- "@venizia/dev-configs": "latest",
226
- "eslint": "^9.36.0",
227
- "prettier": "^3.6.2",
228
- "typescript": "^5.9.3"
229
- }
230
- }
231
- ```
232
-
233
- 2. Create configuration files:
234
-
235
- **`tsconfig.json`:**
236
- ```json
237
- {
238
- "$schema": "http://json.schemastore.org/tsconfig",
239
- "extends": "@venizia/dev-configs/tsconfig.common.json",
240
- "compilerOptions": {
241
- "outDir": "dist",
242
- "rootDir": "src",
243
- "baseUrl": "src",
244
- "paths": { "@/*": ["./*"] }
245
- },
246
- "include": ["src"],
247
- "exclude": ["node_modules", "dist"]
248
- }
249
- ```
250
-
251
- **`eslint.config.mjs`:**
252
- ```javascript
253
- import { eslintConfigs } from '@venizia/dev-configs';
254
-
255
- export default eslintConfigs;
256
- ```
257
-
258
- **`.prettierrc.mjs`:**
259
- ```javascript
260
- import { prettierConfigs } from '@venizia/dev-configs';
261
-
262
- export default prettierConfigs;
263
- ```
264
-
265
- **`.prettierignore`:**
266
- ```
267
- dist
268
- node_modules
269
- *.log
270
- .*-audit.json
271
- ```
272
-
273
- 3. Add lint scripts to `package.json`:
274
-
275
- ```json
276
- {
277
- "scripts": {
278
- "lint": "eslint --report-unused-disable-directives . && prettier \"**/*.{js,ts}\" -l",
279
- "lint:fix": "eslint --report-unused-disable-directives . --fix && prettier \"**/*.{js,ts}\" --write"
280
- }
281
- }
282
- ```
283
-
284
-
285
- ## Building the Package
286
-
287
- ```bash
288
- cd packages/dev-configs
289
-
290
- # Build
291
- bun run build
292
-
293
- # Clean
294
- bun run clean
295
-
296
- # Rebuild (clean + build)
297
- bun run rebuild
298
- ```
package/wiki/references/src-details/docs.md DELETED
@@ -1,71 +0,0 @@
1
- # Package: `@venizia/ignis-docs`
2
-
3
- Documentation package housing guides, references, and MCP server for the Ignis framework.
4
-
5
- ## Quick Reference
6
-
7
- **Package:** Documentation built with VitePress + MCP server for external tool integration.
8
-
9
- ### Main Components
10
-
11
- | Component | Technology | Purpose |
12
- |-----------|------------|---------|
13
- | **Wiki** | VitePress | Main documentation site (guides + references) |
14
- | **MCP Server** | Model Context Protocol | External tool documentation discovery |
15
-
16
- ### Wiki Structure
17
-
18
- | Section | Content |
19
- |---------|---------|
20
- | `guides/` | Tutorials, quickstart, core concepts, best practices |
21
- | `references/` | API reference, components, helpers, base classes |
22
- | `.vitepress/` | Site configuration and theme |
23
-
24
- ## Project Structure Overview
25
-
26
- Top-level breakdown of the `packages/docs/` directory:
27
-
28
- | Folder | Purpose |
29
- | :--------------- | :--------------------------------------------------------------------------------- |
30
- | **`mcp-server`** | Contains the Model Context Protocol (MCP) server implementation for documentation and code search. |
31
- | **`wiki`** | The main documentation content, built using VitePress. |
32
-
33
- ---
34
-
35
- ## Detailed Sections
36
-
37
- ### `mcp-server`
38
-
39
- This directory contains the implementation of a Model Context Protocol (MCP) server, which allows external tools (AI assistants) to discover and read documentation resources, as well as search the source code.
40
-
41
- | File/Folder | Purpose/Key Details |
42
- | :---------- | :------------------ |
43
- | `index.ts` | Server entry point, tool registration, and CLI argument parsing |
44
- | `common/config.ts` | `MCPConfigs` class with server, GitHub, search, and Fuse.js settings |
45
- | `common/paths.ts` | Path resolution for wiki directory |
46
- | `helpers/docs.helper.ts` | `DocsHelper` for documentation loading, caching, and Fuse.js search |
47
- | `helpers/github.helper.ts` | `GithubHelper` for GitHub API integration (code search, file fetching) |
48
- | `helpers/logger.helper.ts` | Logging utilities |
49
- | `tools/base.tool.ts` | Abstract `BaseTool` class for all MCP tools |
50
- | `tools/docs/` | Documentation tools: `searchDocs`, `getDocContent`, `listDocs`, `listCategories`, `getDocMetadata`, `getPackageOverview` |
51
- | `tools/github/` | Code/project tools: `searchCode`, `listProjectFiles`, `viewSourceFile`, `verifyDependencies` |
52
-
53
- For detailed MCP server documentation, see [MCP Server Deep Dive](./mcp-server.md).
54
-
55
- ### `wiki`
56
-
57
- This directory holds the actual documentation content and the VitePress configuration for building the documentation website.
58
-
59
- | File/Folder | Purpose/Key Details |
60
- | :---------------------- | :----------------------------------------------------------------------------------------------------------------------------- |
61
- | `.vitepress/` | VitePress-specific configuration and theme files. |
62
- | `.vitepress/config.mts` | The main configuration file for VitePress, defining the documentation's title, description, navigation, and sidebar structure. |
63
- | `.vitepress/theme/` | Custom theme files for the VitePress documentation. |
64
- | `guides/` | Guides and tutorials for getting started with `Ignis`. |
65
- | `references/` | Detailed reference documentation for various aspects of the framework. |
66
- | `index.md` | The homepage content for the documentation site. |
67
- | `logo.svg` | The logo used in the documentation. |
68
-
69
- ---
70
-
71
- This detailed breakdown illustrates the modular and layered design of the `Ignis` framework, emphasizing its extensibility and adherence to robust architectural patterns.