-
-
Notifications
You must be signed in to change notification settings - Fork 15
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
- Loading branch information
1 parent
2351301
commit 91d221b
Showing
4 changed files
with
177 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,63 @@ | ||
// Core Project Context and Principles | ||
description "walkerOS core principles and context" | ||
|
||
# Core Principles and Guidelines | ||
|
||
## Overview | ||
|
||
This document outlines the core principles and guidelines for the walkerOS project, focusing on package interaction, event processing, and overall project goals. | ||
|
||
## Package Interaction and Event Processing | ||
|
||
### Types Package | ||
- **Purpose:** Provides a unified typing system to ensure consistency across all packages. | ||
- **Guideline:** All packages must use the types defined here to ensure seamless integration and consistent data structures. | ||
|
||
### Utils Package | ||
- **Purpose:** Contains shared utility functions to avoid code duplication. | ||
- **Guideline:** Utilize functions from this package to maintain standardized and reliable implementations across packages. | ||
|
||
### Sources Package | ||
- **Purpose:** Designed for specific environments to create and manage `WalkerOS.Events`. | ||
- **Guideline:** Sources must handle state management, initialize triggers, manage consent, and enrich event context. Events should be sent to destinations using the `push` function. | ||
|
||
### Destinations Package | ||
- **Purpose:** Receives and processes events, potentially translating them for third-party tools. | ||
- **Guideline:** Implement the `push` interface to receive events in the `WalkerOS.Events` format and process them according to the destination's requirements. | ||
|
||
## Event Schema and Structure | ||
|
||
- **Schema Influence:** Follow the descriptive framework provided in `event-model.mdx` for understanding the purpose and meaning of each event key. | ||
- **Dynamic Creation:** Use `eventGenerator.ts` as a reference for creating events that reflect real-world scenarios. | ||
|
||
## Integration and Interaction | ||
|
||
- **Consistency:** Ensure all packages use the `types` package to maintain a consistent structure. | ||
- **Event Flow:** Events should be created in sources, configured, and then sent to destinations for processing. | ||
|
||
## Specific Format Requirements | ||
|
||
- **Standardization:** Events must be created in the `WalkerOS.Events` format to allow for standardized processing, mapping, and validation. | ||
- **Rules and Constraints:** Adhere to the defined types to ensure proper event creation and processing. | ||
|
||
## Core Principles | ||
|
||
- **Type Safety:** Never use the `any` type; explicit typing is required to ensure type safety. | ||
- **Efficiency:** Write lean, efficient code with minimal dependencies. | ||
- **Best Practices:** Follow the DRY principle and ensure full test coverage. | ||
- **Environment Separation:** Maintain clear separation between web and node environments. | ||
- **Adaptability:** Be open to adapting new technologies and methodologies. | ||
|
||
## Expertise and Focus | ||
|
||
- **Role:** Senior TypeScript Developer | ||
- **Expertise Areas:** | ||
- Data collection systems | ||
- Event handling | ||
- Type safety | ||
- Performance optimization | ||
- Critical thinking | ||
|
||
## Conclusion | ||
|
||
By following these guidelines, the system will maintain a high level of consistency, reliability, and flexibility, ensuring that events are accurately created, processed, and utilized across different environments and tools. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,36 @@ | ||
// Package Structure and Organization | ||
description "walkerOS package organization and naming conventions" | ||
|
||
# Package Structure and Organization | ||
|
||
## Overview | ||
|
||
This document provides guidelines for the organization and naming conventions of packages within the walkerOS project, ensuring clarity and consistency. | ||
|
||
## Package Naming Conventions | ||
|
||
- **walker.js:** `packages/sources/walkerjs/` | ||
- **Web Destinations:** `packages/destinations/web/*` | ||
- **Node Destinations:** `packages/destinations/node/*` | ||
- **Web Sources:** `packages/sources/web/*` | ||
- **Node Sources:** `packages/sources/node/*` | ||
- **Utils:** `packages/utils` | ||
- **Types:** `packages/types` | ||
|
||
## Rules and Guidelines | ||
|
||
### Environment Separation | ||
- **Path:** `packages/**/src/**/*.ts` | ||
- **Guideline:** Maintain clear separation between web and node code. Use only available environment APIs. | ||
|
||
### Utils Organization | ||
- **Path:** `packages/utils/**/*.ts` | ||
- **Guideline:** Separate utils into `code/`, `web/`, and `node/` folders. Check for shared patterns before implementing new utilities. | ||
|
||
### Interdependencies | ||
- **Path:** `packages/*` | ||
- **Guideline:** Document interdependencies and shared utilities. Ensure compatibility across packages. | ||
|
||
## Conclusion | ||
|
||
By adhering to these guidelines, the walkerOS project will maintain a well-organized and consistent package structure, facilitating easier maintenance and development. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,45 @@ | ||
// File Priorities and Patterns | ||
description "Priority levels for different file types" | ||
|
||
# File Priorities and Patterns | ||
|
||
## Overview | ||
|
||
This document outlines the priority levels assigned to different file types within the project, ensuring that critical files receive the attention they deserve. | ||
|
||
## High Priority (1.0-0.9) | ||
|
||
### Core Type Definitions | ||
- **Path:** `packages/types/src/**/*.ts` | ||
- **Priority:** 1.0 | ||
- **Guideline:** These files contain core type definitions. It's crucial to avoid using the `any` type to maintain type safety and consistency. | ||
|
||
### Package Source Code | ||
- **Path:** `packages/*/src/**/*.{ts,tsx}` | ||
- **Priority:** 0.9 | ||
- **Guideline:** Source code for packages should have explicit typing to ensure clarity and maintainability. | ||
|
||
## Medium Priority (0.7-0.6) | ||
|
||
### Package Functionality Tests | ||
- **Path:** `packages/*/__tests__/**/*.{ts,tsx}` | ||
- **Priority:** 0.7 | ||
- **Guideline:** Focus on testing package functionality rather than granular function testing to ensure comprehensive coverage. | ||
|
||
## Lower Priority (0.4) | ||
|
||
### Shared Configurations | ||
- **Path:** `packages/config/**/*` | ||
- **Priority:** 0.4 | ||
- **Guideline:** These files contain shared configurations and are less critical than core type definitions and source code. | ||
|
||
## Exclusions | ||
|
||
- **Paths:** | ||
- `**/.turbo/**` | ||
- `**/dist/**` | ||
- `**/node_modules/**` | ||
- `**/coverage/**` | ||
- `**/*.log` | ||
- `**/*.map` | ||
- **Guideline:** These paths are excluded from priority considerations as they contain generated or non-essential files. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,33 @@ | ||
// Code and Documentation Standards | ||
description "walkerOS coding and documentation standards" | ||
|
||
# Overview | ||
|
||
This document provides the coding and documentation standards to be followed across the walkerOS project, ensuring consistency and quality. | ||
|
||
## Coding Standards | ||
|
||
- **Type Definitions:** Start with proper type definitions from `@elbwalker/types` to ensure type safety. | ||
- **Shared Functionality:** Check the `utils` package before implementing new shared functionality to avoid duplication. | ||
- **Testing Focus:** Focus on package functionality in tests to ensure comprehensive coverage. | ||
- **Implementation Preference:** Prefer vanilla implementations over external dependencies to reduce complexity. | ||
- **Coding Patterns:** Include examples of preferred coding patterns to guide developers. | ||
|
||
## Documentation Standards | ||
|
||
- **README Files:** Maintain `README.md` files for package context, including purpose, usage examples, and API documentation. | ||
- **Usage Examples:** Include usage examples in documentation to aid understanding. | ||
- **Type Documentation:** Document type definitions thoroughly to ensure clarity. | ||
- **Data Flow Explanation:** Explain complex data flow patterns to provide insight into system operations. | ||
- **Documentation Styles:** Provide examples of documentation styles to maintain consistency. | ||
|
||
## Patterns | ||
|
||
### README Files | ||
- **Path:** `packages/*/README.md` | ||
- **Enforcement:** Include package purpose, usage examples, and API documentation. | ||
|
||
### Source Files | ||
- **Path:** `packages/*/src/**/*.ts` | ||
- **Enforcement:** Include JSDoc comments for public APIs. | ||
- **Validation:** No `any` types allowed to maintain type safety. |