@fairfox/polly 0.1.0 → 0.1.2

package/README.md

@@ -1,4 +1,4 @@
-# @fairfox/web-ext
+# @fairfox/polly
 
 **Build Chrome extensions with reactive state and zero boilerplate.**
 
@@ -36,16 +36,16 @@ This framework fixes all of that:
 
 ```bash
 # Using Bun (recommended)
-bun add @fairfox/web-ext
+bun add @fairfox/polly
 
 # Using npm
-npm install @fairfox/web-ext
+npm install @fairfox/polly
 
 # Using pnpm
-pnpm add @fairfox/web-ext
+pnpm add @fairfox/polly
 
 # Using yarn
-yarn add @fairfox/web-ext
+yarn add @fairfox/polly
 ```
 
 ### Create Extension
@@ -54,7 +54,7 @@ yarn add @fairfox/web-ext
 
 ```typescript
 // src/shared/state.ts
-import { $sharedState } from '@fairfox/web-ext/state'
+import { $sharedState } from '@fairfox/polly/state'
 
 export const counter = $sharedState('counter', 0)
 export const settings = $sharedState('settings', { theme: 'dark' })
@@ -83,7 +83,7 @@ render(<Popup />, document.getElementById('root')!)
 
 ```typescript
 // src/background/index.ts
-import { createBackground } from '@fairfox/web-ext/background'
+import { createBackground } from '@fairfox/polly/background'
 
 const bus = createBackground()
 ```
@@ -95,7 +95,7 @@ const bus = createBackground()
 **4. Build and load**:
 
 ```bash
-bunx web-ext build
+polly build
 ```
 
 Load `dist/` folder in Chrome → **Done!** 🎉
@@ -319,4 +319,4 @@ MIT © 2024
 
 ---
 
-**[View Examples](./examples/)** · **[Read Docs](./docs/)** · **[Report Issue](https://github.com/fairfox/web-ext/issues)**
+**[View Examples](https://github.com/AlexJeffcott/polly/tree/main/packages/examples)** · **[Read Docs](https://github.com/AlexJeffcott/polly/tree/main/packages/polly/docs)** · **[Report Issue](https://github.com/AlexJeffcott/polly/issues)**

package/cli/polly.ts

@@ -111,7 +111,10 @@ async function dev() {
  * Verify command - delegate to @fairfox/web-ext-verify
  */
 async function verify() {
-  const verifyCli = `${__dirname}/../../verify/src/cli.ts`;
+  // Try vendor directory first (published package), then monorepo
+  const vendorCli = `${__dirname}/../vendor/verify/src/cli.ts`;
+  const monorepoCli = `${__dirname}/../../verify/src/cli.ts`;
+  const verifyCli = (await Bun.file(vendorCli).exists()) ? vendorCli : monorepoCli;
 
   const proc = Bun.spawn(["bun", verifyCli, ...commandArgs], {
     cwd,
@@ -127,10 +130,13 @@ async function verify() {
 }
 
 /**
- * Visualize command - delegate to @fairfox/web-ext-visualize
+ * Visualize command - delegate to @fairfox/polly-visualize
  */
 async function visualize() {
-  const visualizeCli = `${__dirname}/../../visualize/src/cli.ts`;
+  // Try vendor directory first (published package), then monorepo
+  const vendorCli = `${__dirname}/../vendor/visualize/src/cli.ts`;
+  const monorepoCli = `${__dirname}/../../visualize/src/cli.ts`;
+  const visualizeCli = (await Bun.file(vendorCli).exists()) ? vendorCli : monorepoCli;
 
   const proc = Bun.spawn(["bun", visualizeCli, ...commandArgs], {
     cwd,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fairfox/polly",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "description": "Multi-execution-context framework with reactive state and cross-context messaging for Chrome extensions, PWAs, and worker-based applications",
@@ -44,7 +44,7 @@
       "types": "./dist/shared/types/messages.d.ts"
     }
   },
-  "files": ["dist", "README.md", "LICENSE"],
+  "files": ["dist", "cli", "vendor", "README.md", "LICENSE"],
   "scripts": {
     "dev": "bun run build.ts --watch",
     "build": "bun run build.ts",

package/vendor/analysis/src/extract/adr.ts

@@ -0,0 +1,212 @@
+// ADR (Architecture Decision Record) extractor
+// Parses ADRs from markdown files following Michael Nygard's format
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ADR, ADRStatus, ADRLink, ADRCollection } from "../types/adr";
+
+export class ADRExtractor {
+  private projectRoot: string;
+
+  constructor(projectRoot: string) {
+    this.projectRoot = projectRoot;
+  }
+
+  /**
+   * Extract ADRs from docs/adr directory
+   */
+  extract(): ADRCollection {
+    const adrDir = this.findADRDirectory();
+
+    if (!adrDir || !fs.existsSync(adrDir)) {
+      return {
+        adrs: [],
+        directory: adrDir || path.join(this.projectRoot, "docs", "adr"),
+      };
+    }
+
+    const files = fs
+      .readdirSync(adrDir)
+      .filter((file) => file.endsWith(".md"))
+      .map((file) => path.join(adrDir, file));
+
+    const adrs: ADR[] = [];
+
+    for (const file of files) {
+      try {
+        const adr = this.parseADR(file);
+        if (adr) {
+          adrs.push(adr);
+        }
+      } catch (error) {
+        console.warn(`Failed to parse ADR: ${file}`, error);
+      }
+    }
+
+    // Sort by ID
+    adrs.sort((a, b) => a.id.localeCompare(b.id));
+
+    return {
+      adrs,
+      directory: adrDir,
+    };
+  }
+
+  /**
+   * Find ADR directory
+   */
+  private findADRDirectory(): string | null {
+    const candidates = [
+      path.join(this.projectRoot, "docs", "adr"),
+      path.join(this.projectRoot, "docs", "architecture", "decisions"),
+      path.join(this.projectRoot, "adr"),
+      path.join(this.projectRoot, "architecture", "decisions"),
+    ];
+
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) {
+        return candidate;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Parse ADR from markdown file
+   */
+  private parseADR(filePath: string): ADR | null {
+    const content = fs.readFileSync(filePath, "utf-8");
+    const fileName = path.basename(filePath, ".md");
+
+    // Extract ID from filename (e.g., "0001-use-preact.md" → "0001")
+    const idMatch = fileName.match(/^(\d+)/);
+    const id = idMatch ? idMatch[1] : fileName;
+
+    // Extract title from first heading
+    const titleMatch = content.match(/^#\s+(.+)$/m);
+    const title = titleMatch ? titleMatch[1].trim() : fileName;
+
+    // Extract status
+    const status = this.extractStatus(content);
+
+    // Extract date
+    const date = this.extractDate(content);
+
+    // Extract sections
+    const context = this.extractSection(content, "Context");
+    const decision = this.extractSection(content, "Decision");
+    const consequences = this.extractSection(content, "Consequences");
+
+    // Extract alternatives (if present)
+    const alternativesSection = this.extractSection(content, "Alternatives");
+    const alternatives = alternativesSection
+      ? alternativesSection
+          .split("\n")
+          .filter((line) => line.trim().startsWith("-"))
+          .map((line) => line.replace(/^-\s*/, "").trim())
+      : undefined;
+
+    // Extract links
+    const links = this.extractLinks(content);
+
+    if (!context || !decision || !consequences) {
+      // Not a valid ADR format
+      return null;
+    }
+
+    return {
+      id,
+      title,
+      status,
+      date,
+      context,
+      decision,
+      consequences,
+      alternatives,
+      links,
+      source: filePath,
+    };
+  }
+
+  /**
+   * Extract status from content
+   */
+  private extractStatus(content: string): ADRStatus {
+    const statusMatch = content.match(/Status:\s*(\w+)/i);
+    if (!statusMatch) return "accepted";
+
+    const status = statusMatch[1].toLowerCase();
+    if (["proposed", "accepted", "deprecated", "superseded"].includes(status)) {
+      return status as ADRStatus;
+    }
+
+    return "accepted";
+  }
+
+  /**
+   * Extract date from content
+   */
+  private extractDate(content: string): string {
+    // Try to find date in various formats
+    const dateMatch =
+      content.match(/Date:\s*(\d{4}-\d{2}-\d{2})/i) || content.match(/(\d{4}-\d{2}-\d{2})/i);
+
+    return dateMatch ? dateMatch[1] : new Date().toISOString().split("T")[0];
+  }
+
+  /**
+   * Extract section content
+   */
+  private extractSection(content: string, sectionName: string): string {
+    // Match section heading and capture content until next heading or end
+    const regex = new RegExp(`##\\s+${sectionName}\\s*\\n([\\s\\S]*?)(?=\\n##|$)`, "i");
+    const match = content.match(regex);
+
+    return match ? match[1].trim() : "";
+  }
+
+  /**
+   * Extract links to other ADRs
+   */
+  private extractLinks(content: string): ADRLink[] {
+    const links: ADRLink[] = [];
+
+    // Look for supersedes/superseded-by links
+    const supersedesMatch = content.match(/Supersedes:\s*ADR-(\d+)/gi);
+    if (supersedesMatch) {
+      for (const match of supersedesMatch) {
+        const idMatch = match.match(/ADR-(\d+)/);
+        if (idMatch) {
+          links.push({
+            type: "supersedes",
+            adrId: idMatch[1],
+          });
+        }
+      }
+    }
+
+    const supersededByMatch = content.match(/Superseded by:\s*ADR-(\d+)/gi);
+    if (supersededByMatch) {
+      for (const match of supersededByMatch) {
+        const idMatch = match.match(/ADR-(\d+)/);
+        if (idMatch) {
+          links.push({
+            type: "superseded-by",
+            adrId: idMatch[1],
+          });
+        }
+      }
+    }
+
+    return links;
+  }
+}
+
+/**
+ * Extract ADRs from project
+ */
+export function extractADRs(projectRoot: string): ADRCollection {
+  const extractor = new ADRExtractor(projectRoot);
+  return extractor.extract();
+}

package/vendor/analysis/src/extract/architecture.ts

@@ -0,0 +1,160 @@
+// Architecture analysis - main orchestrator
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import type { ArchitectureAnalysis, ContextInfo } from "../types/architecture";
+import { ManifestParser } from "./manifest";
+import { ContextAnalyzer } from "./contexts";
+import { FlowAnalyzer } from "./flows";
+import { IntegrationAnalyzer } from "./integrations";
+import { HandlerExtractor } from "./handlers";
+import { extractADRs } from "./adr";
+
+export interface ArchitectureAnalysisOptions {
+  /** Path to tsconfig.json */
+  tsConfigPath: string;
+
+  /** Project root directory (where manifest.json is) */
+  projectRoot: string;
+
+  /** Optional: Override detected contexts */
+  contexts?: string[];
+}
+
+/**
+ * Comprehensive architecture analyzer
+ */
+export class ArchitectureAnalyzer {
+  private options: ArchitectureAnalysisOptions;
+
+  constructor(options: ArchitectureAnalysisOptions) {
+    this.options = options;
+  }
+
+  /**
+   * Perform complete architecture analysis
+   */
+  async analyze(): Promise<ArchitectureAnalysis> {
+    // 1. Parse manifest.json
+    const manifestParser = new ManifestParser(this.options.projectRoot);
+    const manifest = manifestParser.parse();
+    const entryPoints = manifestParser.getContextEntryPoints();
+
+    // 2. Extract message handlers
+    const handlerExtractor = new HandlerExtractor(this.options.tsConfigPath);
+    const { handlers } = handlerExtractor.extractHandlers();
+
+    // 3. Analyze each context
+    const contextAnalyzer = new ContextAnalyzer(this.options.tsConfigPath);
+    const contexts: Record<string, ContextInfo> = {};
+
+    for (const [contextType, entryPoint] of Object.entries(entryPoints)) {
+      try {
+        const contextInfo = contextAnalyzer.analyzeContext(contextType, entryPoint, handlers);
+        contexts[contextType] = contextInfo;
+      } catch (error) {
+        console.warn(`Failed to analyze context ${contextType}: ${error}`);
+      }
+    }
+
+    // 4. Analyze message flows
+    const flowAnalyzer = new FlowAnalyzer(this.options.tsConfigPath, handlers);
+    const messageFlows = flowAnalyzer.analyzeFlows();
+
+    // 5. Analyze external integrations
+    const integrationAnalyzer = new IntegrationAnalyzer(this.options.tsConfigPath);
+    const integrations = integrationAnalyzer.analyzeIntegrations();
+
+    // 6. Merge external API calls into context info
+    this.mergeExternalAPIsIntoContexts(contexts, integrations);
+
+    // 7. Extract ADRs (Architecture Decision Records)
+    const adrs = extractADRs(this.options.projectRoot);
+
+    // 8. Extract repository info
+    const repository = this.extractRepositoryInfo();
+
+    return {
+      system: {
+        name: manifest.name,
+        version: manifest.version,
+        description: manifest.description,
+      },
+      manifest,
+      contexts,
+      messageFlows,
+      integrations,
+      adrs: adrs.adrs.length > 0 ? adrs : undefined,
+      repository,
+    };
+  }
+
+  /**
+   * Merge external API calls into their respective contexts
+   */
+  private mergeExternalAPIsIntoContexts(
+    contexts: Record<string, ContextInfo>,
+    integrations: ExternalIntegration[]
+  ): void {
+    for (const integration of integrations) {
+      if (integration.calls) {
+        for (const call of integration.calls) {
+          // Find which context this call belongs to
+          for (const [contextType, contextInfo] of Object.entries(contexts)) {
+            if (call.location.file.includes(`/${contextType}/`)) {
+              contextInfo.externalAPIs.push(call);
+              break;
+            }
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Extract repository information from package.json
+   */
+  private extractRepositoryInfo(): ArchitectureAnalysis["repository"] {
+    const packageJsonPath = path.join(this.options.projectRoot, "package.json");
+
+    if (!fs.existsSync(packageJsonPath)) {
+      return undefined;
+    }
+
+    try {
+      const content = fs.readFileSync(packageJsonPath, "utf-8");
+      const packageJson = JSON.parse(content);
+
+      if (packageJson.repository) {
+        if (typeof packageJson.repository === "string") {
+          return {
+            url: packageJson.repository,
+            type: "git",
+          };
+        }
+
+        return {
+          url: packageJson.repository.url || packageJson.repository,
+          type: packageJson.repository.type || "git",
+        };
+      }
+    } catch (error) {
+      console.warn(`Failed to parse package.json: ${error}`);
+    }
+
+    return undefined;
+  }
+}
+
+/**
+ * Convenience function to analyze architecture
+ */
+export async function analyzeArchitecture(
+  options: ArchitectureAnalysisOptions
+): Promise<ArchitectureAnalysis> {
+  const analyzer = new ArchitectureAnalyzer(options);
+  return analyzer.analyze();
+}
+
+// Fix: Import ExternalIntegration type
+import type { ExternalIntegration } from "../types/architecture";