@animus-ui/extract 0.1.9 → 0.1.12

package/README.md

@@ -2,7 +2,7 @@
 
 Rust/NAPI static CSS extraction pipeline for Animus. Analyzes TypeScript source files using OXC, resolves builder chains against serialized system config, and emits layered CSS.
 
-This package is consumed by [`@animus-ui/vite-plugin`](../vite-plugin) and [`@animus-ui/next-plugin`](../next-plugin). You typically don't install it directly — the bundler plugins depend on it.
+This package is the shared home of extraction: the `./session` subpath exports the one `ExtractionSession` that every driver drives, and `./pipeline` exports the shared config/option core. It is consumed by [`@animus-ui/vite-plugin`](../vite-plugin), [`@animus-ui/next-plugin`](../next-plugin), the [`@animus-ui/unplugin`](../unplugin) transform host, and the [`animus` CLI](../cli). You typically don't install it directly — the drivers depend on it. For the consumer-facing contract of the standalone drivers (module ids, artifact set, exit codes), see the [standalone extraction contract](https://github.com/codecaaron/animus/blob/main/docs/standalone-extraction.md).
 
 ## Platforms
 
@@ -31,6 +31,53 @@ const manifest = engine.analyze(fileEntriesJson);
 const { code, hasComponents } = JSON.parse(engine.transformFile(path));
 ```
 
+### Source corpus
+
+Every driver (the Vite plugin, the extraction session behind the Next
+plugin, the CLI, and unplugin) analyzes one source corpus, owned by
+`createSourceCorpus` in `@animus-ui/extract/pipeline` (`prepare` →
+analyze → `publish`; `published` is the parser-ready projection of the last
+successful pass — see the module's own doc comments for the contract).
+
+The Vite plugin and the extraction session are two drivers, not one driver
+holding a copy of the other: the session publishes artifacts to disk for
+cross-process readers, the Vite context answers virtual modules from memory.
+The raw file cache stays with each driver: the Vite context mutates its
+cache incrementally under its analysis lock, the session rebinds its cache
+wholesale on publish. The ingestion policy point (`createSourceIngestor`) is
+not exported from the pipeline barrel; its one production call site is
+inside the corpus, asserted by `tests/source-corpus.test.ts`.
+
+## Driver and host obligations
+
+Obligations a driver or host carries that no exported type expresses.
+
+### Hosts and sessions
+
+- `onExternalRootResolved` fires for each admitted root during collection, before that root is walked, so a watching host can open its handle with no blind gap between scan and watch. `onExternalRootsCommitted` fires once after a successful publication with the complete admitted root set; a failed pipeline never fires it, so the host rolls back whatever it opened.
+- Every host projects ownership at the same point — after ingestion and before the analysis result is enforced — so that two hosts cannot raise different diagnostics for the same external package. An original that leaves the corpus takes its projected children with it, so no owner outlives the file it described.
+- Integrations consume the published replacement epoch rather than deriving their own; pass the served system-props artifact's content as `servedDependencyWitness` so an offline change to that artifact moves the epoch and invalidates persistent-cache snapshots referencing the old one. Absence and an empty string are distinct witness values.
+
+### Ingestion
+
+- A payload that is not a corpus throws, naming the refusing reader, because an empty corpus is indistinguishable from "no files" and would publish an empty stylesheet. Callers with their own documented failure channel translate the throw into it; none may swallow it.
+- Keyframes collections are keyed by export name, and a `name.property` reference resolves against whatever local name binds that collection. The binding may arrive either through a cross-file import or through an export in the same file.
+
+### Options
+
+- The `exclude` dialect — globs versus substrings, and the structural exclusions that always apply and cannot be re-admitted — is defined in the [standalone extraction contract](https://github.com/codecaaron/animus/blob/main/docs/standalone-extraction.md#changed-plugin-behavior-release-notes-callout), which every driver shares.
+
+### Assets
+
+- Asset copies are content-addressed and never overwritten, so a revised asset leaves its previous revision in `assets/` until pruning removes it. Choose `staleAssetPruning: 'full-pipeline'` when the driver serves the directory in place (an already-loaded page still requests the old url) and `'every-cycle'` when it republishes the whole directory each cycle.
+- Asset urls are emitted relative to the session's `styles.css`, which sits beside `assets/`, so the host's own CSS pipeline applies its publicPath and output hashing to them. A specifier that cannot be substituted warns and is emitted literally, and fails the build in strict mode.
+
+### Engine
+
+- `transformSourcesJson` is the only channel for transforms that ship inside an installed package: `configJson` names each prop's transform but cannot carry its body, and the extractor's other seed is `createTransform()` calls parsed out of project files. Without it, props using a package-shipped transform emit the raw value.
+- In dev mode the manifest reports what reconciliation would have eliminated instead of eliminating it, as `report.eliminated_details` entries carrying `kind: "prospective_component"`. That turns a JSX-scanner blind spot into an authoring-time diagnostic rather than missing CSS in a production build.
+- `build:extract-v2` checks rustc against `rust-toolchain.toml` before building the shipped binary; `build:v2:debug` skips the check on purpose because it builds a developer-profile binary.
+
 ## License
 
 MIT

package/crates/extract-v2/index.d.ts

@@ -2,116 +2,46 @@
 /* eslint-disable */
 export declare class ExtractEngine {
   constructor(options?: EngineOptions | undefined | null)
-  /**
-   * Parse-once fact extraction over the file set; facts and sources are
-   * RETAINED on the handle for subsequent per-file calls. Returns the
-   * fact manifest (files + parseCount) as JSON.
-   */
   analyze(fileEntriesJson: string): string
-  /** Reset all retained build state. */
   clearCache(): void
   get parseCount(): number
-  /**
-   * Per-file transformation from retained source + facts (no-config
-   * subset: variants/compounds/states; system/custom payloads need the
-   * row-07 config inputs and FAIL LOUD). Returns {code, hasComponents}
-   * JSON. Import decisions come from surviving chain/payload metadata;
-   * consumed-import stripping and directive handling are the ported v1
-   * semantics.
-   */
   transformFile(path: string): string
 }
 
 /**
- * Chain discovery over a file set: parse once per file (parallel), walk
- * every stored AST, return owned facts. The v2 spine's first real surface;
- * consumed by the parity comparison tooling.
+ * Chain discovery over a file set: one parse per file, then one walk per
+ * stored AST.
  */
 export declare function discoverChains(fileEntriesJson: string): string
 
-/**
- * Engine options (row 07 Task 07.3 — replaces the RF-53 hardcodes).
- * All fields optional; absent = v1 defaults.
- */
 export interface EngineOptions {
-  /** Class-identity prefix (v1 default "animus"). */
   prefix?: string
-  /** Runtime import source (v1 default "@animus-ui/system"). */
   runtimeImport?: string
-  /** CSS virtual module id (v1 default "virtual:animus/styles.css"). */
   cssModuleId?: string
-  /**
-   * System-props virtual module id (v1 EmitterConfig default
-   * "virtual:animus/system-props").
-   */
   systemPropsModuleId?: string
-  /** Flat theme scales JSON (v1 analyzeProject `theme_json`). */
   themeJson?: string
-  /** Token-alias variable map JSON (v1 `variable_map_json`). */
   variableMapJson?: string
-  /** Contextual vars JSON (v1 `contextual_vars_json`). */
   contextualVarsJson?: string
-  /** Prop config map JSON (v1 `config_json`). */
   configJson?: string
-  /** Group registry JSON (v1 `group_registry_json`). */
   groupRegistryJson?: string
-  /**
-   * Transform source texts (`{ transformName: sourceText }` JSON) from the
-   * system evaluation. `config_json` names each prop's transform but cannot
-   * carry its body, and the extractor's other seed is `createTransform()`
-   * calls parsed out of project files — so without this, transforms shipped
-   * inside a package are unresolvable at build time and their props fall
-   * back to the raw value.
-   */
   transformSourcesJson?: string
-  /** Selector aliases JSON (v1 `selector_aliases_json`). */
   selectorAliasesJson?: string
-  /**
-   * Condition aliases JSON (the `conditionAliases` manifest field):
-   * `{ "_motionReduce": { "value": "@media …", "order": 500, "kind":
-   * "media" } }`. Absent = no registrations.
-   */
   conditionAliasesJson?: string
-  /** Global style blocks JSON (v1 `global_style_blocks_json`). */
   globalStyleBlocksJson?: string
-  /**
-   * Keyframes blocks JSON (v1 `keyframes_blocks_json` — feeds BOTH the
-   * global sheet and the static keyframes registry, v1 Phase 2a).
-   */
   keyframesJson?: string
-  /** Package resolution JSON (v1 `package_resolution_json`). */
   packageResolutionJson?: string
-  /** Path aliases JSON (`{aliases: [...]}` wrapper, v1 shape). */
   pathAliasesJson?: string
-  /**
-   * Forced-emission declarations (spec: static-emission-overrides) —
-   * the serialized `staticCss` plugin option.
-   */
   staticCssJson?: string
-  /**
-   * rootDir-relative directory prefixes of discovered external packages
-   * (JSON string array). Files under these dirs get the external-token
-   * candidate walk (extraction-diagnostics: cross-source correlation);
-   * absent = no candidates recorded.
-   */
   externalDirsJson?: string
-  /** v1 `dev_mode`: retain all components (skip reconciliation pruning). */
   devMode?: boolean
 }
 
-/**
- * Build/probe identity: proves the v2 binary loads and its oxc linkage
- * parses. Consumed by the dual-build verification and the parity harness
- * engine registry.
- */
+/** Probe identity: proves the binary loads and its oxc linkage parses. */
 export declare function engineVersion(): string
 
 /**
- * Full per-file fact extraction: chains + eagerly evaluated
- * stages + statics + raw usage facts + compose families — one parse per
- * file. The store (and every AST) is dropped when this call returns; the
- * invariant is that no program() read happens after
- * cross-file facts resolve.
+ * Full per-file fact extraction, one parse per file. The store and its
+ * ASTs drop on return: no `program()` read survives cross-file resolve.
  */
 export declare function extractFacts(fileEntriesJson: string): string
 
@@ -128,40 +58,29 @@ export interface NapiSystemConfig {
   selectorOrder?: string
   /**
    * Condition alias map JSON (the `conditionAliases` manifest field):
-   * alias → `{ value, order, kind }`. Absent when the system registers none.
+   * alias → `{ value, order, kind }`. Absent when none are registered.
    */
   conditionAliases?: string
   /**
-   * Transform source texts (`{ transformName: sourceText }` JSON) captured
-   * during system evaluation — the only channel by which transforms shipped
-   * inside a package reach the build-time evaluator. Absent against a system
-   * built by an older @animus-ui/system.
+   * Transform source texts (`{ transformName: sourceText }` JSON): the
+   * only channel by which transforms shipped in a package reach evaluation.
    */
   transformSources?: string
   globalStyleBlocks?: string
   keyframesBlocks?: string
   /**
-   * Canonical absolute paths of every module evaluated for the system
-   * (sorted; entry included, runtime stubs excluded). The plugins use this
-   * as the geological-reset membership set.
+   * Vocabulary witnesses as a JSON array of coded entries; hosts surface
+   * each as a diagnostic keyed by its `code`. Absent when there are none.
+   */
+  vocabularyWitnesses?: string
+  /**
+   * Canonical absolute paths of every module evaluated for the system,
+   * sorted; the entry is included, runtime stubs are not.
    */
   dependencies: Array<string>
   /**
-   * Per-module built-theme token manifests captured during evaluation
-   * (`{ modulePath: { exportName: [token paths] } }`) — the source-token
-   * witness for the cross-source correlation diagnostic. Absent when no
-   * evaluated module exports a built theme.
+   * Per-module built-theme token manifests, shaped
+   * `{ modulePath: { exportName: [token paths] } }`. Absent when none exist.
    */
   sourceThemeManifests?: string
 }
-
-/**
- * Scan one module entry for named `Keyframes` collection exports — the
- * keyframes-only carve-out for external package entries. The
- * entry evaluates through the same loader pipeline as a system module, but
- * nothing except `__brand === 'Keyframes'` exports is read from it; the
- * consumer's configured system remains the singular config authority.
- * Returns the `{ exportName: { keyName: { name, frames } } }` JSON, or None
- * when the entry exports no collections.
- */
-export declare function scanKeyframesExports(entryPath: string, rootDir: string): string | null