@pwrs/cem 0.1.7 → 0.1.9

package/README.md

@@ -1,44 +1,28 @@
 # cem
 
-**cem** is a command-line tool for generating [Custom Elements Manifest](https://github.com/webcomponents/custom-elements-manifest) (CEM) files from TypeScript sources. It analyzes your codebase and generates rich metadata for your custom elements, facilitating documentation, tooling, and integration.
+**cem** is a command-line tool for generating [Custom Elements Manifest][cem]
+(CEM) files from TypeScript sources. It analyzes your codebase and generates
+rich metadata for your custom elements, facilitating documentation, tooling, and
+integration.
+
+> [!NOTE]
+> `cem` currently supports LitElements written in idiomatic style with
+> TypeScript decorators. If you need something more specific,
+> [open an issue][issuenew].
 
 ## Features
 
 ### `cem generate`
 
-- **Generates CEM files** from source code using syntax analysis powered by [go](https://go.dev) and [tree-sitter](https://tree-sitter.github.io/tree-sitter/).
+- **Generates CEM files** from source code using syntax analysis powered by
+[go][go] and [tree-sitter][treesitter].
 - Identifies custom elements, classes, variables, functions, and exports.
-- Supports elements written in idiomatic Lit typescript style, with a `@customElement` decorator, and `@property` decorators on class fields.
-
-#### HTML Template Analysis for Slots and Parts
-
-- **Automatically detects `<slot>` and `part` attributes in your element’s `render()` template.**
-- Extracts slot names and CSS shadow parts directly from HTML templates returned by the `render()` method.
-- **Supports documenting slots and parts inline in your template HTML** using HTML comments with YAML blocks. For example:
-  ```html
-  <!--
-    summary: The main slot for content
-    description: |
-      This slot displays user-provided content.
-      Supports multiline **markdown**.
-    deprecated: true
-  -->
-  <slot></slot>
-  ```
-- You can document named slots, default slots, and CSS parts:
-  ```html
-  <!-- slot:
-        summary: Named slot summary
-     part:
-        summary: Part summary
-  -->
-  <slot name="info" part="info-part"></slot>
-  ```
-- The tool merges slot and part information found in templates with any provided via JSDoc, ensuring comprehensive documentation in the generated manifest.
-- **Deprecation and other metadata** for slots and parts can be specified via YAML in HTML comments.
+- Supports elements written in idiomatic Lit typescript style, with a
+`@customElement` decorator, and `@property` decorators on class fields.
 
 #### JSDoc
-Use JSDoc comments to add metadata to your element classes, similar to other tools
+Use JSDoc comments to add metadata to your element classes, similar to other
+tools.
 
 - `@attr` / `@attribute` — Custom element attributes
 - `@csspart` — CSS shadow parts
@@ -49,26 +33,67 @@ Use JSDoc comments to add metadata to your element classes, similar to other too
 - `@slot` — Named or default slots
 - `@summary` — Short summary for documentation
 
+#### HTML Template Analysis for Slots and Parts
+
+- **Automatically detects `<slot>` elements and `part` attributes in your element’s
+`render()` template.**
+- Merges slot and part information found in templates with any provided
+via JSDoc, ensuring comprehensive documentation in the generated manifest.
+- **Deprecation and other metadata** for slots and parts can be specified via
+YAML in HTML comments.
+- **Supports documenting slots and parts inline in your template HTML** using
+HTML comments with YAML blocks.
+- YAML comments are not necessary to detect slots and parts, but help in
+documenting them for your users.
+
+##### Examples
+```html
+<!--
+  summary: The main slot for content
+  description: |
+    This slot displays user-provided content.
+    Supports multiline **markdown**.
+  deprecated: true
+-->
+<slot></slot>
+<!-- slot:
+       summary: Named slot summary
+     part:
+       summary: Part summary
+-->
+<slot name="info" part="info-part"></slot>
+```
+
 #### CSS Custom Properties
 Supports CSS Custom Properties by scanning css files and css tagged-template-literals
 
-- Custom properties beginning with `_` will be ignored (treated as "private") e.g. `var(--_private)`
-- If you provide a [Design Tokens Community 
-Group](https://tr.designtokens.org/format/) format module (JSON) to `cem` via the `--design-tokens` flag,
-`cem` will add metadata from your design system to any matching css variables it finds in your elements
-- You can use jsdoc-like comment syntax before each var call to document your 
-  variables
-  ```css
-  :host {
-    color:
-      /**
-       * custom color for use in this element
-       * @summary color
-       * @deprecated just use the `color` property
-       */
-      var(--custom-color);
-  }
-  ```
+- Custom properties beginning with `_` will be ignored (treated as "private")
+e.g. `var(--_private)`
+- If you provide a [Design Tokens Community Group][dtcg] format module (JSON) to
+`cem` via the `--design-tokens` flag,
+`cem` will add metadata from your design system to any matching css variables it
+finds in your elements
+- You can use jsdoc-like comment syntax before each var call to document your
+variables
+
+##### Example
+
+```css
+:host {
+  color:
+    /**
+     * custom color for use in this element
+     * @summary color
+     * @deprecated just use the `color` property
+     */
+    var(--custom-color);
+  border:
+    1px
+    solid
+    /** Border color of the element */
+    var(--border-color);
+}
+```
 
 ## Installation
 
@@ -103,17 +128,36 @@ cem generate \
   --output custom-elements.json
 ```
 
-for npm projects you can use `npx @pwrs/cem generate ...`, just be sure to
-install the package first.
+For npm projects you can use `npx @pwrs/cem generate ...`.
+### Arguments
+| Argument                     | Type               | Description                                                                                       |
+| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------------- |
+| `<files or globs>`           | positional (array) | Files or glob patterns to include                                                                 |
+| `--exclude, -e`              | array              | Files or glob patterns to exclude                                                                 |
+| `--design-tokens, -t`        | string             | Path or npm specifier for DTCG-format design tokens                                               |
+| `--design-tokens-prefix, -p` | string             | CSS custom property prefix for design tokens                                                      |
+| `--output, -o`               | string             | Write the manifest to this file instead of stdout                                                 |
+| `--no-default-excludes`      | bool               | Do not exclude files by default (e.g., `.d.ts` files will be included unless excluded explicitly) |
 
-- `generate`: Command to start manifest generation.
-- Accepts file paths and glob patterns.
-- `--design-tokens`: path to tokens file or npm:package specifier
-- `--exclude` / `-e`: Specify patterns to exclude from the manifest.
-- `--output` / `-o`: Write the manifest to a file instead of stdout.
+By default, some files (like `.d.ts` TypeScript declaration files) are excluded from the manifest.
+Use `--no-default-excludes` if you want to include all matching files and manage excludes yourself.
+
+## Contributing
+
+For information on building and testing, please see
+[CONTRIBUTING.md][contributingmd].
 
 ## License
 
-This program is free software: you can redistribute it and/or modify it under the terms of the [GNU General Public License v3.0](https://www.gnu.org/licenses/gpl-3.0.html).
+This program is free software: you can redistribute it and/or modify it under
+the terms of the [GNU General Public License v3.0][gpl3].
 
 &copy; 2025 Benny Powers <web@bennypowers.com>
+
+[cem]: https://github.com/webcomponents/custom-elements-manifest
+[dtcg]: https://tr.designtokens.org/format/
+[go]: https://go.dev
+[treesitter]: https://tree-sitter.github.io/tree-sitter/
+[gpl3]: https://www.gnu.org/licenses/gpl-3.0.html
+[contributingmd]: ./CONTRIBUTING.md
+[issuenew]: https://github.com/bennypowers/cem/issues/new

package/bin/cem.js

@@ -9,8 +9,8 @@ const supportedTargets = new Set([
   "linux-arm64",
   "darwin-x64",
   "darwin-arm64",
-  // "win32-x64",
-  // "win32-arm64",
+  "win32-x64",
+  "win32-arm64",
 ]);
 
 const target = `${platform()}-${arch()}`
@@ -22,14 +22,9 @@ if (!supportedTargets.has(target)) {
 
 let binPath;
 try {
-  let pkgPath = `@pwrs/cem-${target}/bin/cem`
-  if (platform() === "win32" ? ".exe" : "") {
-    pkgPath += '.exe'
-  }
-  binPath = require.resolve(pkgPath);
-  console.log(pkgPath);
+  binPath = require.resolve(`@pwrs/cem-${target}/cem${platform() === 'win32' ? '.exe' : ''}`);
 } catch {
-  console.error(`cem: Platform binary package ${subpkg} not installed. Was there an install error?`);
+  console.error(`cem: Platform binary package @pwrs/cem-${target} not installed. Was there an install error?`);
   process.exit(1);
 }
 

package/install-platform-binary.js

@@ -6,6 +6,8 @@ const pkg = {
   "darwin-arm64": "@pwrs/cem-darwin-arm64",
   "linux-x64": "@pwrs/cem-linux-x64",
   "linux-arm64": "@pwrs/cem-linux-arm64"
+  "win32-x64": "@pwrs/cem-win32-x64",
+  "win32-arm64": "@pwrs/cem-win32-arm64"
 }[`${platform}-${arch}`];
 
 if (!pkg) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pwrs/cem",
-  "version": "0.1.7",
+  "version": "0.1.9",
   "description": "CLI tool for generating and working with Custom Elements Manifests",
   "type": "module",
   "engines": {
@@ -13,10 +13,12 @@
     "postinstall": "node ./install-platform-binary.js"
   },
   "optionalDependencies": {
-    "@pwrs/cem-linux-x64": "0.1.7",
-    "@pwrs/cem-linux-arm64": "0.1.7",
-    "@pwrs/cem-darwin-x64": "0.1.7",
-    "@pwrs/cem-darwin-arm64": "0.1.7"
+    "@pwrs/cem-linux-x64": "0.1.9",
+    "@pwrs/cem-linux-arm64": "0.1.9",
+    "@pwrs/cem-darwin-x64": "0.1.9",
+    "@pwrs/cem-darwin-arm64": "0.1.9",
+    "@pwrs/cem-win32-x64": "0.1.9",
+    "@pwrs/cem-win32-arm64": "0.1.9"
   },
   "files": [
     "bin/cem.js",