@generaltranslation/vue-extractor 0.0.0 → 0.1.0-iris.0

package/dist/types.d.ts

@@ -1,4 +1,30 @@
-import type { JsxChildren } from '@generaltranslation/format/types';
+import type { GTProp, JsxElement, Variable } from '@generaltranslation/format/types';
+/** A direct Branch or Plural source value preserved by the GT wire format. */
+export type VueBranchSource = VueJsxChildren;
+/** GT element metadata with the complete branch-source wire contract. */
+export type VueGTProp = Omit<GTProp, 'b'> & {
+    /** Named Branch or Plural sources. */
+    b?: Record<string, VueBranchSource>;
+};
+/** A serialized Vue element in a rich translation source. */
+export type VueJsxElement = Omit<JsxElement, 'c' | 'd'> & {
+    /** Nested serialized children. */
+    c?: VueJsxChildren;
+    /** Translation metadata attached to this element. */
+    d?: VueGTProp;
+};
+/** One serialized child in a rich Vue translation source. */
+export type VueJsxChild = string | VueJsxElement | Variable;
+/**
+ * The complete rich-source wire format returned by Vue extraction.
+ *
+ * Boolean and null values can occur at scalar root, element-child, Fragment,
+ * Branch, and Plural positions. React removes those values from authored child
+ * arrays, so arrays retain the narrower {@link VueJsxChild} member type.
+ * This Vue-specific export documents those exact recursive wire semantics for
+ * consumers without requiring framework-internal casts.
+ */
+export type VueJsxChildren = VueJsxChild | boolean | null | VueJsxChild[];
 /**
  * Version-neutral Vue compiler surface accepted by programmatic extraction.
  *
@@ -32,13 +58,22 @@ export type VueSourceCode = {
 /** Metadata attached to an extracted Vue translation. */
 export type VueExtractionMetadata = {
     context?: string;
+    /** Deprecated custom identifier retained for React catalog compatibility. */
+    id?: string;
+    /** Maximum translated character count included in the catalog identity. */
+    maxChars?: number;
+    /** Whether generated translations require human review. */
+    requiresReview?: boolean;
     filePaths?: string[];
+    /** Stable catalog key calculated by project-level extraction. */
+    hash?: string;
     sourceCode?: Record<string, VueSourceCode[]>;
 };
 /** A translation extracted from Vue source code before CLI post-processing. */
 export type VueExtractionResult = {
     dataFormat: 'JSX';
-    source: JsxChildren;
+    /** Missing when the authored T has no default-slot content. */
+    source: VueJsxChildren | undefined;
     metadata: VueExtractionMetadata;
 } | {
     dataFormat: 'STRING';
@@ -55,6 +90,16 @@ export type VueExtractionOptions = {
     includeSourceCodeContext?: boolean;
     /** Root used to make metadata file paths relative. Defaults to `process.cwd()`. */
     projectRoot?: string;
+    /**
+     * Skips standalone script files that have no statically proven gt-vue
+     * provenance. Vue single-file components are always parsed.
+     *
+     * This is useful when a framework dispatcher sends the same JavaScript and
+     * TypeScript files to multiple extractors. A permissive, read-only preflight
+     * recognizes gt-vue imports through local barrels before the normal parser
+     * applies the source file's declared language.
+     */
+    requireGTProvenance?: boolean;
     /**
      * Resolves a static module specifier to a source file without loading or
      * executing that module. Relative source files and index barrels are
@@ -64,8 +109,9 @@ export type VueExtractionOptions = {
      * The hook is consulted first for every specifier, including relative ones,
      * so a project can preserve its compiler's source-over-build precedence.
      *
-     * Returning `undefined` leaves the import unresolved and makes GT-shaped
-     * uses fail closed. The returned path must identify a readable local source
+     * Returning `undefined` leaves the import unresolved. GT-shaped uses fail
+     * closed only inside Vue SFCs or standalone files with separate proven
+     * gt-vue provenance. The returned path must identify a readable local source
      * file.
      */
     resolveModule?: (specifier: string, importer: string) => string | undefined;
@@ -78,3 +124,48 @@ export type VueExtractionOutput = {
     errors: string[];
     warnings: string[];
 };
+/** Options for extracting every gt-vue source owned by one project. */
+export type VueProjectExtractionOptions = {
+    /** Project root. Defaults to `process.cwd()`. */
+    cwd?: string;
+    /** Reusable package-owned workspace inspection for this project root. */
+    inspection?: VueProjectInspection;
+    /** Optional project-root-relative globs that replace framework defaults. */
+    filePatterns?: string[];
+    /** Includes surrounding source lines in result metadata. */
+    includeSourceCodeContext?: boolean;
+    /** Package export conditions used by static local-module resolution. */
+    conditionNames?: string[];
+    /** Explicit hash-affecting Vue compiler options from project configuration. */
+    vueCompilerOptions?: VueCompilerOptions;
+    /** Explicit Vite config path relative to the project root. */
+    viteConfigPath?: string;
+    /**
+     * Explicit tsconfig.json or jsconfig.json path relative to the project root.
+     * When omitted, module resolution discovers the nearest config per importer.
+     */
+    tsconfigPath?: string;
+    /** Number of source lines captured before and after a translation. */
+    surroundingLineCount?: number;
+};
+/** Opaque summary returned by package-owned Vue workspace inspection. */
+export type VueProjectInspection = {
+    /** Absolute root inspected for Vue-owned source scopes. */
+    readonly projectRoot: string;
+    /** Whether the root package itself activates the Vue command surface. */
+    readonly rootOwnsVue: boolean;
+    /** Whether the root or any declared workspace owns Vue source. */
+    readonly hasVueScopes: boolean;
+};
+/** A project result whose stable catalog hash has been calculated. */
+export type VueProjectExtractionResult = VueExtractionResult & {
+    metadata: VueExtractionMetadata & {
+        hash: string;
+    };
+};
+/** Complete output from atomic project-level Vue extraction. */
+export type VueProjectExtractionOutput = {
+    updates: VueProjectExtractionResult[];
+    errors: string[];
+    warnings: string[];
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@generaltranslation/vue-extractor",
-  "version": "0.0.0",
+  "version": "0.1.0-iris.0",
   "description": "Vue source code extraction for General Translation",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -13,7 +13,7 @@
     }
   },
   "author": "General Translation, Inc.",
-  "license": "FSL-1.1-ALv2",
+  "license": "MIT",
   "exports": {
     ".": {
       "import": "./dist/index.js",
@@ -23,6 +23,22 @@
       "import": "./dist/config.js",
       "types": "./dist/config.d.ts"
     },
+    "./detect": {
+      "import": "./dist/detect.js",
+      "types": "./dist/detect.d.ts"
+    },
+    "./inspect": {
+      "import": "./dist/inspect.js",
+      "types": "./dist/inspect.d.ts"
+    },
+    "./integration": {
+      "import": "./dist/integration.js",
+      "types": "./dist/integration.d.ts"
+    },
+    "./project": {
+      "import": "./dist/project.js",
+      "types": "./dist/project.d.ts"
+    },
     "./types": {
       "import": "./dist/types.js",
       "types": "./dist/types.d.ts"
@@ -46,16 +62,26 @@
     "@babel/traverse": "^7.25.7",
     "@babel/types": "^7.25.7",
     "@vue/shared": "^3.5.0",
-    "@generaltranslation/format": "0.1.4",
-    "generaltranslation": "9.1.1"
+    "enhanced-resolve": "^5.18.3",
+    "entities": "^7.0.1",
+    "es-module-lexer": "^2.3.1",
+    "fast-glob": "^3.3.3",
+    "semver": "^7.8.5",
+    "tsconfig-paths": "^4.2.0",
+    "yaml": "^2.8.0",
+    "@generaltranslation/format": "0.1.5-iris.0",
+    "generaltranslation": "9.1.3-iris.0"
   },
   "devDependencies": {
     "@types/babel__traverse": "^7.20.6",
     "@types/node": "^22.13.5",
+    "@types/semver": "^7.7.1",
     "@vue/compiler-dom": "^3.5.0",
     "@vue/compiler-sfc": "^3.5.0",
     "tsdown": "^0.21.10",
     "typescript": "^5.9.2",
+    "vue": "^3.5.0",
+    "vite": "^7.1.7",
     "vitest": "^3.2.4"
   },
   "scripts": {