@citestyle/compiler 0.0.2 → 1.0.1

package/README.md

@@ -1,90 +1,128 @@
 # @citestyle/compiler
 
-Build-time compiler that transforms [CSL](https://citationstyles.org/) XML files into lightweight JavaScript modules.
+Transform any [CSL](https://citationstyles.org/) style into a lightweight JavaScript module at build time. The compiled output is a self-contained ES module (~3-5KB) that formats citations and bibliographies as pure function calls — no XML parsing, no runtime interpreter, no dependencies beyond `@citestyle/core`.
+
+This is a **build tool**. Install it as a dev dependency, compile your styles once, and ship only the tiny output modules to production.
 
 ## Installation
 
 ```bash
-npm install @citestyle/compiler
+npm install -D @citestyle/compiler
 ```
 
-## CLI Usage
+## CLI
 
 ### Compile a style
 
 ```bash
-# Single file to stdout
-citestyle compile apa.csl
-
-# Single file to output
-citestyle compile apa.csl -o apa.js
+# Compile to a file
+npx citestyle compile apa.csl -o apa.js
 
-# Batch compile all .csl files in a directory
-citestyle compile styles/*.csl -o dist/
+# Compile with a specific locale
+npx citestyle compile apa.csl --locale fr-FR -o apa-fr.js
 
-# With a specific locale
-citestyle compile apa.csl --locale fr-FR -o apa-fr.js
+# Batch compile every .csl file in a directory
+npx citestyle compile styles/*.csl -o dist/
 
-# Multi-locale (outputs one file per locale)
-citestyle compile apa.csl --locale en-US,fr-FR -o dist/
+# Multi-locale (one output file per locale)
+npx citestyle compile apa.csl --locale en-US,fr-FR -o dist/
 
 # CommonJS output
-citestyle compile apa.csl --format cjs -o apa.cjs
+npx citestyle compile apa.csl --format cjs -o apa.cjs
+
+# Print to stdout (pipe to other tools)
+npx citestyle compile apa.csl
 ```
 
-### Validate a style
+### Validate without compiling
 
 ```bash
-# Check without compiling — reports warnings
-citestyle check apa.csl
+# Check a style for warnings without generating output
+npx citestyle check apa.csl
 
 # Batch validate
-citestyle check styles/*.csl
+npx citestyle check styles/*.csl
 ```
 
-### CLI Options
+### CLI options
 
 | Option | Description | Default |
 |---|---|---|
 | `-o, --output <path>` | Output file or directory | stdout |
-| `--locale <lang>` | Target locale, comma-separated for multi-locale | `en-US` |
+| `--locale <lang>` | Target locale(s), comma-separated | `en-US` |
 | `--format <esm\|cjs>` | Output module format | `esm` |
 
+## Using a compiled style
+
+The compiled module exports pure functions. No registry needed for basic formatting:
+
+```javascript
+import * as apa from './apa.js'
+
+const item = {
+  id: '1',
+  type: 'article-journal',
+  title: 'Deep learning for citation analysis',
+  author: [{ family: 'Smith', given: 'Jane' }],
+  issued: { 'date-parts': [[2024]] },
+  'container-title': 'Nature',
+  volume: '620',
+  page: '100-108',
+  DOI: '10.1038/example',
+}
+
+// Bibliography entry — returns structured output, not a flat string
+const entry = apa.bibliography(item)
+entry.text  // Smith, J. (2024). Deep learning for citation analysis. Nature, 620, 100–108.
+entry.html  // Semantic HTML with <i>, CSS classes (.csl-author, .csl-title, ...), linked DOI
+entry.parts // { authors, year, title, container, doi, ... }
+entry.links // { doi: 'https://doi.org/10.1038/example' }
+
+// Inline citation
+const cite = apa.citation([{ item }])
+cite.text   // (Smith, 2024)
+
+// Style metadata
+apa.meta.title  // "American Psychological Association 7th edition"
+apa.meta.class  // "in-text"
+```
+
+For documents with multiple citations (where you need numbering, disambiguation, and sorting), use [`@citestyle/registry`](../registry).
+
 ## Programmatic API
 
-```js
+```javascript
 import { compile, parse, resolveLocale, generate } from '@citestyle/compiler'
 ```
 
 ### `compile(cslXml, options?)`
 
-Full pipeline: XML string to JavaScript module.
+Full pipeline: CSL XML string to JavaScript module source.
 
-```js
-import { readFileSync } from 'node:fs'
+```javascript
+import { readFileSync, writeFileSync } from 'node:fs'
+import { compile } from '@citestyle/compiler'
 
 const cslXml = readFileSync('apa.csl', 'utf-8')
 const { code, meta } = compile(cslXml, { locale: 'en-US' })
 
+writeFileSync('apa.js', code)
+
 console.log(meta.title) // "American Psychological Association 7th edition"
 console.log(meta.class) // "in-text"
-
-// `code` is a complete ES module string — write it to a file
-writeFileSync('apa.js', code)
 ```
 
-**Parameters:**
-- `cslXml` (string) -- CSL XML source
-- `options.locale` (string) -- Target locale (default: style's default or `'en-US'`)
-- `options.format` (`'esm'` | `'cjs'`) -- Output format (default: `'esm'`)
+**Options:**
+- `locale` (string) — Target locale (default: style's default or `'en-US'`)
+- `format` (`'esm'` | `'cjs'`) — Output format (default: `'esm'`)
 
 **Returns:** `{ code: string, meta: { id, title, class, version, defaultLocale } }`
 
 ### `parse(cslXml)`
 
-Parse CSL XML into an AST. Useful for validation or inspection without code generation.
+Parse CSL XML into an AST without generating code. Useful for validation, inspection, or building custom tooling.
 
-```js
+```javascript
 const ast = parse(cslXml)
 console.log(ast.info.title)
 console.log(Object.keys(ast.macros))
@@ -92,47 +130,36 @@ console.log(Object.keys(ast.macros))
 
 ### `resolveLocale(locale, overrides?)`
 
-Resolve locale data by merging: style-level overrides, locale XML file, and en-US fallback.
+Resolve locale data by merging: style-level term overrides → locale XML file → en-US fallback.
 
-```js
+```javascript
 const locale = resolveLocale('fr-FR', ast.localeOverrides)
 ```
 
 ### `generate(ast, locale, options?)`
 
-Generate JavaScript module source from a parsed AST and resolved locale.
+Generate JavaScript module source from a parsed AST and resolved locale. Use this when you need control over the parse and locale resolution steps separately.
 
-```js
+```javascript
 const ast = parse(cslXml)
 const locale = resolveLocale('en-US', ast.localeOverrides)
 const code = generate(ast, locale, { format: 'esm' })
 ```
 
-## Using a Compiled Style
+## What gets compiled
 
-```js
-import * as apa from './apa.js'
+Every CSL construct maps directly to JavaScript:
 
-const item = {
-  id: '1',
-  type: 'article-journal',
-  title: 'Deep learning for citation analysis',
-  author: [{ family: 'Smith', given: 'Jane' }],
-  issued: { 'date-parts': [[2024]] },
-  'container-title': 'Nature',
-  volume: '620',
-  page: '100-108',
-  DOI: '10.1038/example',
-}
+| CSL XML | Compiled output |
+|---|---|
+| `<macro name="author">` | `function macro_author(item, ctx) { ... }` |
+| `<choose><if type="article-journal">` | `if (item.type === 'article-journal')` |
+| `<names variable="author">` | `formatNames(item.author, { /* config baked in */ })` |
+| `<group delimiter=", ">` | Array collect → filter empties → join |
+| Locale terms (`"et al."`, `"Retrieved from"`) | Inlined string constants |
 
-// Format a bibliography entry
-const entry = apa.bibliography(item)
-console.log(entry.text)
-// Smith, J. (2024). Deep learning for citation analysis. Nature, 620, 100–108.
-console.log(entry.html)
-// Semantic HTML with <i>, CSS classes, linked DOI
-
-// Format an inline citation
-const citation = apa.citation([{ item }])
-console.log(citation.text) // (Smith, 2024)
-```
+The result is a module that exports `bibliography()`, `citation()`, `bibliographySort()`, and `meta` — pure functions with no XML, no interpretation, and no runtime locale resolution.
+
+## Compatibility
+
+44 styles from the [official CSL repository](https://github.com/citation-style-language/styles) have been compiled and verified, spanning author-date, numeric, note, and label citation formats across English, German, Portuguese, French, and Spanish locales.

package/package.json

@@ -1,7 +1,22 @@
 {
   "name": "@citestyle/compiler",
-  "version": "0.0.2",
+  "version": "1.0.1",
   "description": "Build-time compiler: CSL XML → JavaScript modules",
+  "author": "Uniweb",
+  "homepage": "https://github.com/uniweb/csl/tree/main/packages/compiler",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/uniweb/csl.git",
+    "directory": "packages/compiler"
+  },
+  "keywords": [
+    "csl",
+    "citation",
+    "compiler",
+    "citation-style-language",
+    "bibliography",
+    "build-tool"
+  ],
   "type": "module",
   "exports": {
     ".": {
@@ -19,7 +34,7 @@
     "README.md"
   ],
   "dependencies": {
-    "@citestyle/types": "0.0.2",
+    "@citestyle/types": "1.0.1",
     "@xmldom/xmldom": "^0.8.11"
   },
   "devDependencies": {
@@ -30,7 +45,6 @@
   },
   "license": "MIT",
   "scripts": {
-    "test": "vitest run",
-    "lint": "echo 'TODO: configure linter'"
+    "test": "vitest run"
   }
 }