@zintljs/extractor 0.1.0-alpha.6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026-present Khalid F. Shuhail
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,37 @@
+# @zintljs/extractor
+
+> AST-based message extractor for [Zintl](https://github.com/zintljs/zintl).
+
+[![npm version](https://img.shields.io/npm/v/@zintljs/extractor.svg?color=863bff&label=)](https://npmjs.com/package/@zintljs/extractor)
+
+This is an **internal package**. You almost certainly want [`zintl`](https://npmjs.com/package/zintl) instead — it bundles this extractor behind a ready-to-use Vite plugin.
+
+Install it directly only if you are building custom tooling on top of Zintl's extraction layer.
+
+## What it does
+
+`@zintljs/extractor` is a **pure metadata provider**. It scans source syntax with high-performance [oxc](https://oxc.rs) AST parsers and reports what it finds. It never modifies your source files.
+
+It is deliberately **framework-blind** — it carries no implicit knowledge of React, Vue, or Svelte. All framework behavior is supplied by the caller through configuration.
+
+## Intelligent stitching
+
+The extractor does not emit raw string literals. It stitches template literals, JSX fragments, and HTML strings into logical **Stitched Units**:
+
+- **HTML fragmentation** — large `innerHTML` strings are split along tag boundaries. Translatable text between tags becomes its own key; the tags themselves are preserved as structure.
+- **Variable normalization** — unnamed expressions are normalized to stable placeholders (`{input}`, `{inputN}`), so identical UI fragments share a translation key regardless of their position in a template.
+- **Comment directives** — `@zintl-ignore`, `@zintl-note`, and `@zintl-pass` are recognized and attached to the units they annotate.
+
+## Installation
+
+```bash
+npm install @zintljs/extractor
+```
+
+## Requirements
+
+- Node.js `^22.18.0 || >=24.11.0`
+
+## License
+
+[MIT](./LICENSE) © Khalid F. Shuhail

package/dist/index.d.mts

@@ -0,0 +1,345 @@
+import { Expression, Node } from "@oxc-project/types";
+//#region src/logger.d.ts
+type LogLevel = "silent" | "error" | "warn" | "info";
+interface LoggerOptions {
+  level?: LogLevel;
+  prefix?: string;
+  debug?: boolean | string;
+}
+declare class ZintlLogger {
+  private level;
+  private prefix;
+  private debugEnabled;
+  private debugScope;
+  private lastDebugTime;
+  constructor(options?: LoggerOptions);
+  private setupDebug;
+  private formatMessage;
+  private formatDebugMessage;
+  error(message: string, ...args: any[]): void;
+  warn(message: string, ...args: any[]): void;
+  info(message: string, ...args: any[]): void;
+  debug(message: string, ...args: any[]): void;
+  /**
+   * Create a sub-logger with a combined prefix.
+   */
+  withPrefix(subPrefix: string): ZintlLogger;
+  setLevel(level: LogLevel): void;
+}
+/** Global default logger */
+declare const logger: ZintlLogger;
+//#endregion
+//#region src/types.d.ts
+interface ExtractedMessage {
+  id: string;
+  text: string;
+  contexts: string[];
+  boundaryId: string;
+  location: {
+    line: number;
+    column: number;
+  };
+  note?: string;
+  variables: string[];
+  sinkTypes: string[];
+  passVars?: Record<string, string>;
+}
+/** A resolved dependency on another boundary. */
+interface BoundaryDep {
+  /** Boundary id (relative path without extension). */
+  id: string;
+  /** True if reachable only via a dynamic import() expression. */
+  dynamic: boolean;
+  /** Specific exported identifiers being used from this dependency. */
+  bindings?: string[];
+}
+/** Location of a trust anchor (zintl() call). */
+interface AnchorSite {
+  start: number;
+  end: number;
+  scope: "module" | "function";
+  boundaryId: string;
+  originalArgs: string;
+  argType: "literal" | "expression";
+  isTopLevel: boolean;
+  originalName: string;
+  /** Optional range of the governing statement (e.g. ExpressionStatement including semicolon). */
+  statementRange?: {
+    start: number;
+    end: number;
+  };
+  /** Optional code snippet discovered by tracing the anchor argument for hoisting into bootstrap. */
+  detectionCode?: string;
+}
+interface HtmlProjectionPayload {
+  title?: string;
+  description?: string;
+  dir?: string;
+  /** Found module scripts via <script type="module" src="..."> */
+  scripts: string[];
+}
+interface ExtractionResult {
+  messages: ExtractedMessage[];
+  code: string;
+  /** List of string replacements (original offsets) to apply to original code. */
+  transforms: Transform[];
+  needsLoader: boolean;
+  /** If true, this module contains at least one trust anchor (zintl). */
+  hasZintlMacro: boolean;
+  /** If true, this module contains a side-effect import "zintl" ($M). */
+  hasZintlMarker: boolean;
+  /** Locations of zintl calls for compiler-driven catalog injection. */
+  anchorSites: AnchorSite[];
+  mode: "entry" | "boundary";
+  runtimeImports: string[];
+  dependencies: BoundaryDep[];
+  usedKeys: Set<string>;
+  /** Map of boundaryId -> sha1 hash of its messages (text+context+note) */
+  boundaryHashes: Record<string, string>;
+  /** Location and actual source of existing import from "zintl" used for merging. */
+  zintlImportGroup?: {
+    start: number;
+    end: number;
+    source: string;
+  };
+  /** Map of exported identifier -> internal boundary ID. */
+  exportedBoundaries: Record<string, string>;
+  /** Map of parent boundary -> set of child boundaries it depends on (local calls) */
+  internalDeps: Record<string, string[]>;
+  /** Full-fidelity UI sink observations captured at the visitor level. */
+  rawSinks: RawSink[];
+  /** Explicit t() calls captured at the visitor level. */
+  rawManualTranslations: RawManualT[];
+  /** Component function insertion positions (e.g. function body block starts). */
+  componentFunctions?: number[];
+  /** HTML-specific projection data (for .html files). */
+  htmlProjection?: HtmlProjectionPayload;
+}
+/**
+ * A raw UI string captured at the exact point of discovery in a visitor.
+ *
+ * Unlike the adapter approach (which reconstructs data from transforms),
+ * this captures full-fidelity observation data including:
+ * - Exact source locations (start/end offsets)
+ * - Variable expressions as source code strings
+ * - @zintl-pass context variables
+ * - Fragment and quote conversion metadata
+ */
+interface RawSink {
+  /** Stitched text content (after fragmentation + variable normalization). */
+  text: string;
+  /** UI context: "innerHTML", "title", "h1", "aria-label", "label", etc. */
+  sinkType: string;
+  /** Start offset in source code for the replaceable range. */
+  start: number;
+  /** End offset in source code for the replaceable range. */
+  end: number;
+  /** Source line number. */
+  line: number;
+  /** Source column number. */
+  column: number;
+  /** Owning boundary ID. */
+  boundaryId: string;
+  /** Interpolated variable bindings with source expressions. */
+  variables: RawVariable[];
+  /** Translator note from @zintl-note. */
+  note?: string;
+  /** Context variables from @zintl-pass (target-language asymmetry). */
+  passVars?: Record<string, string>;
+  /** True if this is a fragment within a larger template/string (inline replacement). */
+  isFragment: boolean;
+  /** True if the replacement requires JSX curly braces wrapping. */
+  requiresJsxBraces?: boolean;
+  /** If fragment: start offset of the fragment sub-range. */
+  fragmentStart?: number;
+  /** If fragment: end offset of the fragment sub-range. */
+  fragmentEnd?: number;
+  /** If fragment: start offset of the enclosing host node. */
+  hostStart?: number;
+  /** If fragment: end offset of the enclosing host node. */
+  hostEnd?: number;
+  /** True if the host string literal must be converted to a template literal. */
+  requiresQuoteConversion?: boolean;
+  /** Phrase tag attribute map (alias -> original open tag). */
+  tagMap?: TagMapEntry[];
+}
+interface TagMapEntry {
+  alias: string;
+  originalOpen: string;
+  tagName: string;
+}
+/**
+ * A variable binding captured with its source expression.
+ */
+interface RawVariable {
+  /** Variable name after normalization (e.g. "input", "name"). */
+  name: string;
+  /** Variable name before normalization (e.g. "var0", "name"). */
+  originalName: string;
+  /** Source code of the expression (e.g. "user.name", "items.length"). */
+  expression: string;
+  /** Start offset of the expression in source. */
+  start: number;
+  /** End offset of the expression in source. */
+  end: number;
+}
+/**
+ * An explicit t("key") call captured at the visitor level.
+ */
+interface RawManualT {
+  /** The string key passed to t("key"). */
+  key: string;
+  /** Start offset of the t(...) call. */
+  start: number;
+  /** End offset of the t(...) call. */
+  end: number;
+  /** Source line number. */
+  line: number;
+  /** Source column number. */
+  column: number;
+  /** Owning boundary ID. */
+  boundaryId: string;
+  /** Optional source code for the parameters object. */
+  paramsSource?: string;
+}
+interface LiteralSource {
+  node: Node;
+  text: string;
+  context: string;
+  location: {
+    line: number;
+    column: number;
+  };
+  note?: string;
+  variables?: string[];
+  transformStart?: number;
+  transformEnd?: number;
+  inlineReplacement?: boolean;
+  normalizedVariables?: Record<string, string>;
+  passVars?: Record<string, string>;
+  tagMap?: TagMapEntry[];
+}
+interface BoundaryInfo {
+  id: string;
+  active: boolean;
+}
+interface Transform {
+  start: number;
+  end: number;
+  replacement: string;
+  msgId?: string;
+  originalText?: string;
+  boundaryId: string;
+  argNode?: Expression;
+}
+/**
+ * A structural sink descriptor.
+ *
+ * Deliberately framework-blind: there are no `"react"` / `"vue"` / `"svelte"` /
+ * `"nextjs"` members. Framework presets live in `@zintljs/compiler/facets` and
+ * expand to these low-level forms before they ever reach the extractor.
+ */
+type TargetDescriptor = `jsx:*:${string}` | `jsx:${string}:${string}` | `dom:prop:${string}` | `dom:attr:${string}` | `obj:field:${string}` | `html:attr:${string}` | TargetPlugin;
+interface TargetPlugin {
+  name: string;
+  resolveOptions?: (base: ExtractionOptions) => Partial<ExtractionOptions>;
+  createVisitor?: (ctx: any) => any;
+  fastPathHint?: string | string[];
+}
+interface SfcBlockRule {
+  id: string;
+  pattern: RegExp;
+  action: "javascript" | "html" | "ignore";
+  resolveVirtualExtension?: (attributes: string) => string;
+  isActiveContent?: boolean;
+}
+interface SfcRule {
+  extensions: string[];
+  blocks: SfcBlockRule[];
+}
+interface SuppressionRule {
+  targets?: string[];
+  match: {
+    types: string[];
+    names: string[];
+    isTopLevel?: boolean;
+  };
+  bypassIf?: "hasAnchor";
+}
+interface MustacheRule {
+  extensions: string[];
+  pattern: RegExp;
+}
+interface CompiledExtractionState {
+  jsxAttributes: Set<string>;
+  jsxElementAttributes: Map<string, Set<string>>;
+  domProperties: Set<string>;
+  objectFields: Set<string>;
+  htmlAttributes: Set<string>;
+  plugins: TargetPlugin[];
+  fastPathHints: string[];
+  uniqueHints: string[];
+  fastPathRegex: RegExp;
+  hasDomSinks: boolean;
+  hasJsxSinks: boolean;
+  sfcRules: SfcRule[];
+  suppressionRules: SuppressionRule[];
+  mustacheRegex?: RegExp | null;
+  mustacheRules?: MustacheRule[];
+}
+interface ExtractionOptions {
+  runtimePackage?: string;
+  uiAttributes?: Set<string>;
+  uiObjectFields?: Set<string>;
+  uiSinkProperties?: string[];
+  targets?: TargetDescriptor[];
+  logger?: ZintlLogger;
+  isZeroConfig?: boolean;
+  sfcRules?: SfcRule[];
+  suppressionRules?: SuppressionRule[];
+  activeRange?: {
+    start: number;
+    end: number;
+  };
+  isSfcTemplate?: boolean;
+  compiledState?: CompiledExtractionState;
+}
+//#endregion
+//#region src/parser.d.ts
+declare function extract(code: string, filePath: string, fileBoundaryId: string, options?: ExtractionOptions): ExtractionResult;
+//#endregion
+//#region src/hashing.d.ts
+declare function generateMessageId(messageText: string, _context?: string, _note?: string): string;
+//#endregion
+//#region src/constants.d.ts
+/**
+ * The extractor's only constants.
+ *
+ * The former `DEFAULT_UI_ATTRIBUTES` / `DEFAULT_UI_OBJECT_FIELDS` /
+ * `DEFAULT_UI_SINK_PROPERTIES` sets and `TEMPLATE_ATTR_REGEX` lived here and
+ * encoded opinions about which DOM and JSX attributes are translatable. That is
+ * facet knowledge — it now lives in `@zintljs/compiler/facets` and reaches the
+ * extractor as descriptors. All four were already unreferenced (one survived
+ * only inside a commented-out line) and have been removed.
+ */
+declare const ZINTL_MACRO = "zintl";
+declare const RUNTIME_PACKAGE = "zintl";
+/**
+ * Module specifiers that carry the Zintl runtime surface.
+ *
+ * This list was previously inlined at four call sites (`parser.ts`, two in
+ * `visitors/program.ts`, one in `visitors/bindings.ts`) and the four had drifted:
+ * the `bindings.ts` copy omitted the bare `"zintl"` literal, so a project with a
+ * custom `runtimePackage` would have had its bare `"zintl"` imports recognised
+ * by three of the four checks and missed by the fourth.
+ */
+declare const RUNTIME_SPECIFIERS: readonly string[];
+/** Whether an import specifier resolves to the Zintl runtime. */
+declare function isRuntimeSpecifier(source: string, runtimePackage?: string): boolean;
+declare const HTML_TAG_SPLIT_REGEX: RegExp;
+//#endregion
+//#region src/targets.d.ts
+type ResolvedTargets = CompiledExtractionState;
+declare function resolveTargets(targets: TargetDescriptor[]): ResolvedTargets;
+//#endregion
+export { AnchorSite, BoundaryDep, BoundaryInfo, CompiledExtractionState, ExtractedMessage, ExtractionOptions, ExtractionResult, HTML_TAG_SPLIT_REGEX, HtmlProjectionPayload, LiteralSource, LogLevel, LoggerOptions, MustacheRule, RUNTIME_PACKAGE, RUNTIME_SPECIFIERS, RawManualT, RawSink, RawVariable, ResolvedTargets, SfcBlockRule, SfcRule, SuppressionRule, TagMapEntry, TargetDescriptor, TargetPlugin, Transform, ZINTL_MACRO, ZintlLogger, extract, generateMessageId, isRuntimeSpecifier, logger, resolveTargets };