puglite 1.0.0

package/builders/karma/schema.json

@@ -0,0 +1,260 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Puglite Karma Test Builder",
+  "description": "Karma test runner with Puglite template support",
+  "type": "object",
+  "properties": {
+    "main": {
+      "type": "string",
+      "description": "The name of the main entry-point file."
+    },
+    "tsConfig": {
+      "type": "string",
+      "description": "The name of the TypeScript configuration file."
+    },
+    "karmaConfig": {
+      "type": "string",
+      "description": "The name of the Karma configuration file."
+    },
+    "polyfills": {
+      "description": "A list of polyfills to include in the build.",
+      "oneOf": [
+        {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        {
+          "type": "string"
+        }
+      ]
+    },
+    "assets": {
+      "type": "array",
+      "description": "List of static application assets.",
+      "default": [],
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "glob": {
+                "type": "string",
+                "description": "The pattern to match."
+              },
+              "input": {
+                "type": "string",
+                "description": "The input directory path in which to apply 'glob'."
+              },
+              "output": {
+                "type": "string",
+                "description": "Absolute path within the output."
+              },
+              "ignore": {
+                "description": "An array of globs to ignore.",
+                "type": "array",
+                "items": {
+                  "type": "string"
+                }
+              }
+            },
+            "additionalProperties": false,
+            "required": ["glob", "input", "output"]
+          }
+        ]
+      }
+    },
+    "styles": {
+      "description": "Global styles to be included in the build.",
+      "type": "array",
+      "default": [],
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "input": {
+                "type": "string",
+                "description": "The file to include."
+              },
+              "bundleName": {
+                "type": "string",
+                "pattern": "^[\\w\\-.]*$",
+                "description": "The bundle name for this extra entry point."
+              },
+              "inject": {
+                "type": "boolean",
+                "description": "If the bundle will be referenced in the HTML file.",
+                "default": true
+              }
+            },
+            "additionalProperties": false,
+            "required": ["input"]
+          }
+        ]
+      }
+    },
+    "scripts": {
+      "description": "Global scripts to be included in the build.",
+      "type": "array",
+      "default": [],
+      "items": {
+        "oneOf": [
+          {
+            "type": "string"
+          },
+          {
+            "type": "object",
+            "properties": {
+              "input": {
+                "type": "string",
+                "description": "The file to include."
+              },
+              "bundleName": {
+                "type": "string",
+                "pattern": "^[\\w\\-.]*$",
+                "description": "The bundle name for this extra entry point."
+              },
+              "inject": {
+                "type": "boolean",
+                "description": "If the bundle will be referenced in the HTML file.",
+                "default": true
+              }
+            },
+            "additionalProperties": false,
+            "required": ["input"]
+          }
+        ]
+      }
+    },
+    "sourceMap": {
+      "description": "Output source maps for scripts and styles.",
+      "default": true,
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "object",
+          "properties": {
+            "scripts": {
+              "type": "boolean",
+              "description": "Output source maps for all scripts.",
+              "default": true
+            },
+            "styles": {
+              "type": "boolean",
+              "description": "Output source maps for all styles.",
+              "default": true
+            },
+            "vendor": {
+              "type": "boolean",
+              "description": "Output source maps for vendor libraries.",
+              "default": false
+            }
+          },
+          "additionalProperties": false
+        }
+      ]
+    },
+    "progress": {
+      "type": "boolean",
+      "description": "Log progress to the console while building."
+    },
+    "watch": {
+      "type": "boolean",
+      "description": "Run build when files change."
+    },
+    "poll": {
+      "type": "number",
+      "description": "Enable and define the file watching poll time period in milliseconds."
+    },
+    "preserveSymlinks": {
+      "type": "boolean",
+      "description": "Do not use the real path when resolving modules."
+    },
+    "browsers": {
+      "type": "string",
+      "description": "Override which browsers tests are run against."
+    },
+    "codeCoverage": {
+      "type": "boolean",
+      "description": "Output a code coverage report.",
+      "default": false
+    },
+    "codeCoverageExclude": {
+      "type": "array",
+      "description": "Globs to exclude from code coverage.",
+      "items": {
+        "type": "string"
+      },
+      "default": []
+    },
+    "fileReplacements": {
+      "description": "Replace compilation source files with other compilation source files in the build.",
+      "type": "array",
+      "items": {
+        "oneOf": [
+          {
+            "type": "object",
+            "properties": {
+              "src": {
+                "type": "string",
+                "pattern": "\\.(([cm]?j|t)sx?|json)$"
+              },
+              "replaceWith": {
+                "type": "string",
+                "pattern": "\\.(([cm]?j|t)sx?|json)$"
+              }
+            },
+            "additionalProperties": false,
+            "required": ["src", "replaceWith"]
+          },
+          {
+            "type": "object",
+            "properties": {
+              "replace": {
+                "type": "string",
+                "pattern": "\\.(([cm]?j|t)sx?|json)$"
+              },
+              "with": {
+                "type": "string",
+                "pattern": "\\.(([cm]?j|t)sx?|json)$"
+              }
+            },
+            "additionalProperties": false,
+            "required": ["replace", "with"]
+          }
+        ]
+      },
+      "default": []
+    },
+    "include": {
+      "type": "array",
+      "description": "Globs of files to include, relative to workspace or project root.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "exclude": {
+      "type": "array",
+      "description": "Globs of files to exclude, relative to the workspace or project root.",
+      "items": {
+        "type": "string"
+      }
+    },
+    "webWorkerTsConfig": {
+      "type": "string",
+      "description": "TypeScript configuration for Web Worker modules."
+    }
+  },
+  "additionalProperties": false,
+  "required": ["karmaConfig"]
+}

package/builders/vitest/README.md

@@ -0,0 +1,218 @@
+# Puglite Vitest Builder
+
+Angular builder that runs Vitest with Pug template support.
+
+## Usage
+
+In `angular.json`:
+
+```json
+{
+  "architect": {
+    "test": {
+      "builder": "puglite:vitest",
+      "options": {}
+    }
+  }
+}
+```
+
+Run tests:
+
+```bash
+ng test                  # Run all tests via builder
+npx vitest <file>       # Run specific test file directly
+```
+
+## How It Works
+
+The builder:
+1. Calls Vitest's `startVitest()` API directly
+2. Injects a Vite plugin to transform `.pug` files to HTML strings
+3. Enables `jsdom` environment for browser API support (localStorage, window, etc.)
+
+## Important: You Probably Don't Need Pug Plugin for Tests
+
+**Best practice:** Test component logic only, without importing templates.
+
+```typescript
+// ✅ Test component logic only - NO template imports needed
+describe('UploadImgComponent', () => {
+  let component: UploadImgComponent;
+
+  beforeEach(() => {
+    const mockService = { upload: vi.fn() };
+    component = new UploadImgComponent(mockService);  // No TestBed
+  });
+
+  it('should update state', () => {
+    component.uploadState.set({ status: 'uploading', progress: 50 });
+    expect(component.isUploading()).toBe(true);
+  });
+});
+```
+
+**Template/UI testing happens in E2E:**
+
+```typescript
+// e2e/upload.spec.ts
+test('should display upload progress', async ({ page }) => {
+  await page.goto('/upload');
+  await expect(page.locator('.progress')).toHaveText('50%');
+});
+```
+
+## When You DO Need Pug Plugin
+
+Only if you want to import pug templates in tests (NOT recommended):
+
+```typescript
+import template from './component.pug';  // ← Requires pug plugin
+
+@Component({
+  selector: 'app-test',
+  template: template,  // Inline template from import
+})
+class TestComponent extends RealComponent {}
+
+TestBed.configureTestingModule({ imports: [TestComponent] })
+```
+
+**Why NOT recommended:**
+- Still requires TestBed (complex setup)
+- Adds unnecessary complexity
+- Better separation: logic in Vitest, UI in E2E
+
+## Pug Template Support (Advanced)
+
+If you still want to import pug files in tests, the builder's plugin supports it.
+
+**✅ Works:** Import pug files as ES modules
+
+```typescript
+import template from './component.pug';
+
+@Component({
+  selector: 'app-test',
+  template: template,  // Inline template from import
+})
+class TestComponent extends RealComponent {}
+```
+
+**❌ Doesn't work:** TestBed with external templateUrl
+
+```typescript
+// This will FAIL in Vitest
+@Component({
+  templateUrl: './component.pug'  // External template
+})
+class RealComponent {}
+
+TestBed.configureTestingModule({ imports: [RealComponent] })
+  .compileComponents();  // Error: Component not resolved
+```
+
+See `angular-puglite-demo/src/app/app-templateurl.spec.ts` for a concrete example.
+
+## TestBed Limitation
+
+**TestBed does NOT work with external templates (`.pug` or `.html`) in Vitest.**
+
+### Why?
+
+- **TestBed's `compileComponents()`** expects to **fetch** external templates like a browser (HTTP requests)
+- **Vitest** runs in Node.js with **no dev server** (unlike Karma which runs in real browser)
+- **Vite plugins** transform ES module **imports** (`import x from 'file.pug'`), but TestBed uses file path strings (`templateUrl: 'file.pug'`)
+- These are two different systems that never connect
+
+### Recommended Patterns
+
+**Don't use TestBed in Vitest.** Follow these patterns:
+
+#### 1. Service Tests (✅ Recommended)
+
+```typescript
+describe('MyService', () => {
+  let service: MyService;
+
+  beforeEach(() => {
+    const httpMock = { get: vi.fn(), post: vi.fn() };
+    service = new MyService(httpMock);  // Manual instantiation
+  });
+
+  it('should fetch data', () => {
+    // Test service logic
+  });
+});
+```
+
+#### 2. Component Logic Tests (✅ Recommended)
+
+```typescript
+describe('MyComponent', () => {
+  let component: MyComponent;
+
+  beforeEach(() => {
+    const mockService = { getData: vi.fn() };
+    component = new MyComponent(mockService);  // No TestBed
+  });
+
+  it('should update state', () => {
+    // Test component methods, signals, computed values
+    expect(component.items()).toEqual([]);
+  });
+});
+```
+
+#### 3. Template/UI Tests (✅ Use E2E)
+
+```typescript
+// e2e/my-component.spec.ts (Playwright)
+test('should display items', async ({ page }) => {
+  await page.goto('/my-component');
+  await expect(page.locator('.item')).toBeVisible();
+});
+```
+
+## Alternative: Use Vitest Directly
+
+Instead of using this builder, you can run Vitest directly:
+
+**package.json:**
+```json
+{
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:ui": "vitest --ui"
+  }
+}
+```
+
+**vitest.config.ts:**
+```typescript
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'jsdom',
+    globals: true,
+    setupFiles: ['src/test-setup.ts']
+  }
+});
+```
+
+**No pug plugin needed** - just test component logic with `new Component()`.
+
+## Summary
+
+| What | Vitest (logic) | E2E (Playwright) |
+|------|----------------|------------------|
+| Service logic | ✅ `new Service()` | ❌ |
+| Component logic | ✅ `new Component()` | ❌ |
+| Template rendering | ❌ | ✅ |
+| User interactions | ❌ | ✅ |
+| DOM assertions | ❌ | ✅ |
+| Pug plugin needed | ❌ No | N/A |
+
+**Recommended: Use Vitest for logic, E2E for UI. No pug plugin needed.**

package/builders/vitest/index.js

@@ -0,0 +1,98 @@
+/**
+ * Puglite Vitest Builder
+ *
+ * Angular builder that runs Vitest with Pug template transformation.
+ *
+ * Features:
+ * - Transforms .pug files to HTML strings via Vite plugin
+ * - Enables jsdom environment for browser API support
+ * - Supports file filters for running specific tests
+ *
+ * Limitation:
+ * - TestBed with external templates does NOT work in Vitest
+ * - See README.md for recommended testing patterns
+ */
+
+const path = require('path');
+const { createRequire } = require('module');
+const { readFileSync } = require('fs');
+const debug = require('util').debuglog('puglite');
+
+const projectRequire = createRequire(path.join(process.cwd(), 'package.json'));
+
+async function* buildVitest(options, context) {
+  debug('buildVitest() called');
+  const { startVitest } = projectRequire('vitest/node');
+
+  // Get file filters from CLI args
+  const cliArgs = process.argv.slice(2).filter(arg => !arg.startsWith('--') && arg.endsWith('.spec.ts'));
+  const filters = options.include || cliArgs;
+
+  // Load puglite compiler modules
+  const libPath = path.resolve(__dirname, '../../lib');
+  const lex = require(`${libPath}/lexer`);
+  const parse = require(`${libPath}/parser`);
+  const generateCode = require(`${libPath}/code-gen`);
+  const stripComments = require(`${libPath}/strip-comments`);
+  const runtimeWrap = require(`${libPath}/runtime-wrap`);
+
+  // Vite plugin: Transform .pug imports to HTML strings
+  const pugVitePlugin = {
+    name: 'puglite-vitest',
+    enforce: 'pre',
+    load(id) {
+      const cleanId = id.split('?')[0];
+      if (!cleanId.endsWith('.pug')) return null;
+
+      try {
+        const pugSource = readFileSync(cleanId, 'utf-8');
+        const tokens = lex(pugSource, { filename: cleanId });
+        const strippedTokens = stripComments(tokens, { filename: cleanId });
+        const ast = parse(strippedTokens, { filename: cleanId, src: pugSource });
+        const js = generateCode(ast, {
+          compileDebug: false,
+          pretty: false,
+          inlineRuntimeFunctions: false,
+          templateName: 'template'
+        });
+        const templateFn = runtimeWrap(js);
+        const html = templateFn();
+
+        return `export default ${JSON.stringify(html)};`;
+      } catch (error) {
+        console.error(`[puglite] Error compiling ${cleanId}:`, error);
+        throw error;
+      }
+    }
+  };
+
+  const vitestConfig = {
+    run: true,
+    plugins: [pugVitePlugin],
+    test: {
+      globals: true,
+      environment: 'jsdom'
+    }
+  };
+
+  try {
+    const vitest = await startVitest('test', filters, vitestConfig);
+
+    if (!vitest) {
+      yield { success: false };
+      return;
+    }
+
+    await vitest.close();
+
+    const hasFailures = vitest.state.getCountOfFailedTests() > 0;
+    yield { success: !hasFailures };
+  } catch (error) {
+    console.error('[puglite] Vitest error:', error);
+    yield { success: false, error: error.message };
+  }
+}
+
+const { createBuilder } = projectRequire('@angular-devkit/architect');
+module.exports = createBuilder(buildVitest);
+module.exports.default = module.exports;

package/builders/vitest/schema.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema",
+  "title": "Puglite Vitest Builder",
+  "description": "Vitest test runner with Puglite template support",
+  "type": "object",
+  "properties": {},
+  "additionalProperties": true
+}

package/builders.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "./node_modules/@angular-devkit/architect/src/builders-schema.json",
+  "builders": {
+    "browser": {
+      "implementation": "./builders/browser",
+      "schema": "./builders/browser/schema.json",
+      "description": "Build browser application with Puglite template support"
+    },
+    "dev-server": {
+      "implementation": "./builders/dev-server",
+      "schema": "./builders/dev-server/schema.json",
+      "description": "Development server with Puglite template support"
+    },
+    "karma": {
+      "implementation": "./builders/karma",
+      "schema": "./builders/karma/schema.json",
+      "description": "Karma test runner with Puglite template support"
+    },
+    "vitest": {
+      "implementation": "./builders/vitest",
+      "schema": "./builders/vitest/schema.json",
+      "description": "Vitest test runner with Puglite template support"
+    }
+  }
+}