@ai-pip/csl 0.1.0

package/layers/csl/adapters/input/DOMAdapter.ts

@@ -0,0 +1,236 @@
+import { Origin, Segment } from '../../domain'
+import { OriginType } from '../../types';
+
+/**
+ * DOMAdapter adapts DOM elements to domain entities (Segment[]).
+ * 
+ * @remarks
+ * This adapter is responsible for extracting content from the DOM and converting it
+ * into Segment entities that can be processed by the CSL pipeline. It analyzes DOM
+ * elements to determine their visibility and assigns appropriate Origin types.
+ * 
+ * **Key Responsibilities:**
+ * - Extracts text content from DOM elements using TreeWalker
+ * - Determines element visibility (visible vs hidden)
+ * - Filters out non-processable nodes (script, style, etc.)
+ * - Creates Segment entities with appropriate Origin types
+ * - Assigns DOM_VISIBLE or DOM_HIDDEN based on CSS visibility
+ * 
+ * **Origin Assignment:**
+ * - **DOM_VISIBLE**: Content from elements that are visible to the user
+ * - **DOM_HIDDEN**: Content from elements hidden via CSS (display:none, visibility:hidden, etc.)
+ * 
+ * **Filtered Elements:**
+ * The adapter automatically filters out content from:
+ * - `<script>`, `<style>`, `<meta>`, `<link>`, `<noscript>`, `<iframe>`
+ * - Elements with `contenteditable="false"`
+ * 
+ * **Usage in Pipeline:**
+ * This adapter is used by SegmentationService to extract segments from the DOM
+ * before they go through the classification, normalization, and analysis pipeline.
+ * 
+ * @example
+ * ```typescript
+ * const domAdapter = new DOMAdapter()
+ * 
+ * // Adapt entire document
+ * const segments = domAdapter.adapt(document)
+ * 
+ * // Adapt specific element
+ * const formElement = document.getElementById('user-form')
+ * const segments = domAdapter.adapt(formElement)
+ * 
+ * // Segments are ready for classification
+ * segments.forEach(segment => {
+ *   console.log(segment.origin.type) // 'DOM_VISIBLE' or 'DOM_HIDDEN'
+ * })
+ * ```
+ */
+export class DOMAdapter {
+
+    /**
+     * Adapts a DOM element or document to an array of Segment entities.
+     * 
+     * @param root - The Document or HTMLElement to extract content from.
+     *               If Document is provided, it processes document.body.
+     *               If HTMLElement is provided, it processes that specific element.
+     * 
+     * @returns An array of Segment entities extracted from the DOM.
+     *          Each segment contains:
+     *          - Unique ID (UUID)
+     *          - Text content from the DOM
+     *          - Origin (DOM_VISIBLE or DOM_HIDDEN based on visibility)
+     *          - MIME type (text/plain)
+     *          - Timestamp (when the segment was created)
+     *          - Source identifier (element ID, name, className, or tagName)
+     * 
+     * @example
+     * ```typescript
+     * // Extract segments from entire document
+     * const segments = domAdapter.adapt(document)
+     * console.log(`Extracted ${segments.length} segments`)
+     * 
+     * // Extract segments from specific container
+     * const container = document.querySelector('.content')
+     * const segments = domAdapter.adapt(container)
+     * 
+     * // Process segments
+     * segments.forEach(segment => {
+     *   if (segment.origin.type === OriginType.DOM_VISIBLE) {
+     *     // Handle visible content
+     *   }
+     * })
+     * ```
+     */
+    adapt(root: Document | HTMLElement): Segment[] {
+        const segments: Segment[] = [];
+
+        const walker = document.createTreeWalker(
+            root instanceof Document ? root.body : root,
+            NodeFilter.SHOW_TEXT
+        );
+
+        let node: Node | null;
+        while ((node = walker.nextNode())) {
+            const text = node.textContent?.trim();
+            if (!text) continue;
+
+            // Ignore nodes inside script/style/meta/etc.
+            if (!this.isProcessableNode(node)) continue;
+
+            const parent = node.parentElement;
+            if (!parent) continue;
+
+            const visible = this.isVisible(parent);
+
+            const origin = new Origin(
+                visible ? OriginType.DOM_VISIBLE : OriginType.DOM_HIDDEN
+            );
+
+            const segment = new Segment({
+                id: crypto.randomUUID(),
+                content: text,
+                origin,
+                mime: "text/plain",
+                timestamp: Date.now(),
+                source: this.resolveSource(parent)
+            });
+
+            segments.push(segment);
+        }
+
+        return segments;
+    }
+
+    /**
+     * Determines if a node should be processed based on its parent element.
+     * 
+     * @remarks
+     * This method filters out nodes that should not be processed, such as:
+     * - Scripts and styles (security and noise reduction)
+     * - Meta tags and links (not user-visible content)
+     * - Iframes and noscript (external or conditional content)
+     * - Elements with contenteditable="false" (non-editable content)
+     * 
+     * @param node - The text node to check
+     * 
+     * @returns `true` if the node should be processed, `false` otherwise
+     * 
+     * @example
+     * ```typescript
+     * const node = document.createTextNode('Hello')
+     * if (domAdapter.isProcessableNode(node)) {
+     *   // Process this node
+     * }
+     * ```
+     */
+    private isProcessableNode(node: Node): boolean {
+        const parent = node.parentElement;
+        if (!parent) return false;
+
+        const tag = parent.tagName.toLowerCase();
+
+        // Ignore content from non-textual or potentially dangerous elements
+        if (["script", "style", "meta", "link", "noscript", "iframe"].includes(tag))
+            return false;
+
+        // Ignore contenteditable="false" elements
+        if (parent.getAttribute("contenteditable") === "false")
+            return false;
+
+        return true;
+    }
+
+    /**
+     * Determines if an HTML element is visible to the user.
+     * 
+     * @remarks
+     * This method checks multiple CSS properties to determine visibility:
+     * - `display: none` - Element is not displayed
+     * - `visibility: hidden` - Element is hidden but takes up space
+     * - `opacity: 0` - Element is transparent (effectively invisible)
+     * - `hidden` attribute - HTML5 hidden attribute
+     * 
+     * **Note:** This checks computed styles, so it accounts for CSS inheritance
+     * and inline styles. Elements hidden by parent elements may still return
+     * `true` if the element itself is not explicitly hidden.
+     * 
+     * @param element - The HTMLElement to check for visibility
+     * 
+     * @returns `true` if the element is visible, `false` if it's hidden
+     * 
+     * @example
+     * ```typescript
+     * const element = document.getElementById('my-element')
+     * const visible = domAdapter.isVisible(element)
+     * // Returns true if element is visible, false if hidden
+     * ```
+     */
+    private isVisible(element: HTMLElement): boolean {
+        const style = getComputedStyle(element);
+        return (
+            style.display !== "none" &&
+            style.visibility !== "hidden" &&
+            style.opacity !== "0" &&
+            !element.hasAttribute("hidden")
+        );
+    }
+
+    /**
+     * Resolves a source identifier for an element to track where content came from.
+     * 
+     * @remarks
+     * This method attempts to find a meaningful identifier for the element in
+     * the following priority order:
+     * 1. Element ID (most specific)
+     * 2. Name attribute (for form elements)
+     * 3. Class name (for styled elements)
+     * 4. Tag name (fallback)
+     * 
+     * The source identifier is used in Segment entities for traceability and
+     * debugging purposes.
+     * 
+     * @param element - The HTMLElement to get the source identifier from
+     * 
+     * @returns A string identifier for the element, used as the Segment source
+     * 
+     * @example
+     * ```typescript
+     * const element = document.getElementById('user-input')
+     * const source = domAdapter.resolveSource(element)
+     * // Returns: 'user-input' (the element ID)
+     * 
+     * const div = document.querySelector('.content')
+     * const source = domAdapter.resolveSource(div)
+     * // Returns: 'content' (the class name) or 'DIV' (tag name as fallback)
+     * ```
+     */
+    private resolveSource(element: HTMLElement): string {
+        return (
+            element.id ||
+            element.getAttribute("name") ||
+            element.className ||
+            element.tagName
+        );
+    }
+}

package/layers/csl/adapters/output/ConsoleLogger.ts

@@ -0,0 +1,34 @@
+import type { LoggerPort } from "../../ports";
+import { ColorMap } from "../../utils/colors";
+
+
+export class ConsoleLogger implements LoggerPort {
+
+    private timestamp(): string {
+        return new Date().toISOString()
+    }
+    private buildMessage(level: string, emoji: string,msg:string): string {
+        return `[${this.timestamp()}] ${emoji} ${level}: ${msg}`;
+    }
+    info(msg: string): void {
+        console.log(ColorMap.Info(this.buildMessage("INFO", "ℹ️", msg)));
+      }
+    
+      warn(msg: string): void {
+        console.log(ColorMap.Warning(this.buildMessage("WARN", "⚠️", msg)));
+      }
+    
+      error(msg: string): void {
+        console.log(ColorMap.Error(this.buildMessage("ERROR", "❌", msg)));
+      }
+    
+      debug(msg: string): void {
+        const trace = new Error("Debug trace").stack?.split("\n")[2]?.trim() ?? "";
+        const traceFormatted = ColorMap.Neutral(`(${trace})`);
+        const enriched = `${msg}  ${traceFormatted}`;
+    
+        console.log(ColorMap.Debug(
+          this.buildMessage("DEBUG", "🐛", enriched)
+        ));
+      }
+}

package/layers/csl/adapters/output/CryptoHashGenerator.ts

@@ -0,0 +1,29 @@
+import type { HashGeneratorPort, HashAlgorithm } from "../../ports";
+import crypto from 'node:crypto'
+
+
+export class CryptoHashGenerator implements HashGeneratorPort {
+    
+    private readonly DEFAULT_ALGORITHM: HashAlgorithm = 'sha512';
+    
+    generate(content: string, algorithm: HashAlgorithm = this.DEFAULT_ALGORITHM): Promise<string> {
+       const hash = crypto.createHash(algorithm).update(content).digest('hex')
+       return Promise.resolve(hash)
+    }
+    
+    compare(content: string, hash: string, algorithm: HashAlgorithm = this.DEFAULT_ALGORITHM): Promise<boolean> {
+        const contentHash = crypto.createHash(algorithm).update(content).digest('hex')
+        return Promise.resolve(contentHash ===  hash)
+    }
+
+    generateHMAC(content: string, secretKey: string, algorithm: HashAlgorithm = this.DEFAULT_ALGORITHM): Promise<string> {
+        const hmac = crypto.createHmac(algorithm, secretKey).update(content).digest('hex');
+        return Promise.resolve(hmac);
+    }
+
+    compareHMAC(content: string, hash: string, secretKey: string, algorithm: HashAlgorithm = this.DEFAULT_ALGORITHM): Promise<boolean> {
+        const contentHMAC = crypto.createHmac(algorithm, secretKey).update(content).digest('hex');
+        return Promise.resolve(contentHMAC === hash);
+    }
+
+}

package/layers/csl/adapters/output/InMemoryPolicyRepository.ts

@@ -0,0 +1,135 @@
+import { PolicyRule } from '../../domain/value-objects'
+import type { PolicyRepositoryPort } from '../../ports/output/PolicyRepository'
+
+/**
+ * InMemoryPolicyRepository is an in-memory implementation of PolicyRepositoryPort.
+ * 
+ * @remarks
+ * This adapter stores policies in memory, making it suitable for:
+ * - Testing and development
+ * - Single-process applications
+ * - Temporary policy storage
+ * 
+ * **Limitations:**
+ * - Policies are lost when the process terminates
+ * - Not suitable for distributed systems
+ * - No persistence layer
+ * 
+ * @example
+ * ```typescript
+ * const repository = new InMemoryPolicyRepository()
+ * const policy = new PolicyRule(...)
+ * await repository.savePolicy(policy)
+ * 
+ * const activePolicy = await repository.getActivePolicy()
+ * ```
+ */
+export class InMemoryPolicyRepository implements PolicyRepositoryPort {
+  private readonly policies: Map<string, PolicyRule> = new Map()
+  private activePolicyVersion: string | null = null
+
+  /**
+   * Saves a policy to the repository
+   * 
+   * @param policy - The policy rule to save
+   * 
+   * @example
+   * ```typescript
+   * await repository.savePolicy(policy)
+   * ```
+   */
+  async savePolicy(policy: PolicyRule): Promise<void> {
+    if (!policy || !(policy instanceof PolicyRule)) {
+      throw new TypeError('InMemoryPolicyRepository.savePolicy: policy must be a PolicyRule instance')
+    }
+
+    this.policies.set(policy.version, policy)
+
+    // If this is the first policy or no active policy is set, make it active
+    this.activePolicyVersion ??= policy.version
+  }
+
+  /**
+   * Sets the active policy version
+   * 
+   * @param version - The version to set as active
+   * @throws Error if the version doesn't exist
+   * 
+   * @example
+   * ```typescript
+   * await repository.setActivePolicy('1.0')
+   * ```
+   */
+  async setActivePolicy(version: string): Promise<void> {
+    if (!this.policies.has(version)) {
+      throw new Error(`InMemoryPolicyRepository: Policy version '${version}' not found`)
+    }
+
+    this.activePolicyVersion = version
+  }
+
+  /**
+   * Get the currently active policy
+   * 
+   * @returns The active PolicyRule
+   * @throws Error if no active policy is set
+   */
+  async getActivePolicy(): Promise<PolicyRule> {
+    if (this.activePolicyVersion === null) {
+      throw new Error('InMemoryPolicyRepository: No active policy is set')
+    }
+
+    const policy = this.policies.get(this.activePolicyVersion)
+    if (!policy) {
+      throw new Error(`InMemoryPolicyRepository: Active policy version '${this.activePolicyVersion}' not found`)
+    }
+
+    return policy
+  }
+
+  /**
+   * Get a policy by its version
+   * 
+   * @param version - The version of the policy to retrieve
+   * @returns The PolicyRule for the specified version, or null if not found
+   */
+  async getPolicyByVersion(version: string): Promise<PolicyRule | null> {
+    if (!version || typeof version !== 'string') {
+      throw new TypeError('InMemoryPolicyRepository.getPolicyByVersion: version must be a non-empty string')
+    }
+
+    const policy = this.policies.get(version)
+    return policy ?? null
+  }
+
+  /**
+   * Get all available policies
+   * 
+   * @returns An array of all available PolicyRule instances
+   */
+  async getAllPolicies(): Promise<PolicyRule[]> {
+    return Array.from(this.policies.values())
+  }
+
+  /**
+   * Clears all policies from the repository
+   * 
+   * @example
+   * ```typescript
+   * repository.clear()
+   * ```
+   */
+  clear(): void {
+    this.policies.clear()
+    this.activePolicyVersion = null
+  }
+
+  /**
+   * Gets the active policy version
+   * 
+   * @returns The active policy version, or null if none is set
+   */
+  getActiveVersion(): string | null {
+    return this.activePolicyVersion
+  }
+}

package/layers/csl/adapters/output/SystemTimestampProvider.ts

@@ -0,0 +1,9 @@
+import type { TimeStampProviderPort } from "../../ports";
+
+
+
+export class SystemTimestamProvider implements TimeStampProviderPort {
+    now(): number {
+        return Date.now()
+    }
+}