@generaltranslation/vue-extractor 0.0.0

package/dist/internal/script/model.d.ts

@@ -0,0 +1,317 @@
+import type { Binding, NodePath, Scope } from '@babel/traverse';
+import type * as t from '@babel/types';
+import type { GTComponentName, StringFunctionKind, TemplateContainerKind, VueBuiltinName } from '../types.js';
+import type { LocalModuleResolver } from './localModules.js';
+/** A statically recognized value that affects Vue translation extraction. */
+export type KnownValue = {
+    type: 'component';
+    name: GTComponentName;
+} | {
+    type: 'hook';
+    kind: Exclude<StringFunctionKind, 'msg'>;
+} | {
+    type: 'string';
+    kind: StringFunctionKind;
+} | {
+    type: 'namespace';
+    source: 'gt-vue' | 'vue';
+    /** CommonJS namespace objects can be mutated through member writes. */
+    mutable: boolean;
+} | {
+    /** Immutable ESM namespace imported from a statically resolved barrel. */
+    type: 'local-namespace';
+    modulePath: string;
+} | {
+    type: 'vue-builtin';
+    name: VueBuiltinName;
+} | {
+    type: 'vue-call';
+    name: 'createVNode' | 'defineAsyncComponent' | 'h';
+} | {
+    type: 'container-wrapper';
+    kind: ContainerWrapperKind;
+    writePolicy: ContainerWritePolicy;
+} | {
+    type: 'vue-wrapper';
+    kind: 'computed' | 'ref';
+} | {
+    type: 'identity';
+} | {
+    type: 'defineComponent';
+};
+export type ContainerWritePolicy = 'forward' | 'readonly-deep' | 'readonly-shallow';
+export type ContainerWrapperKind = 'reactive' | 'readonly' | 'shallow-reactive' | 'shallow-readonly' | 'to-raw' | 'unref';
+/** Import information shared by the two script blocks of one Vue SFC. */
+export type VueScriptAnalysis = {
+    /** Optional visit counters used by deterministic complexity regressions. */
+    stats?: VueScriptAnalysisStats;
+    /** Absolute path of the source file currently being extracted. */
+    entryFile?: string;
+    /** Read-only local ESM graph used to resolve application barrels. */
+    localModules?: LocalModuleResolver;
+    /** Lengths of statically known, non-mutated normal-script arrays. */
+    arrayLengths: Map<string, number>;
+    /** Normal-script callables that may return a GT or Vue component. */
+    componentFactories: Set<string>;
+    /** Statically known normal-script container paths. */
+    containerKinds: Map<string, TemplateContainerKind>;
+    /** Normal-script names that take precedence over component registrations. */
+    directBindings: Set<string>;
+    /** Normal-script callables that may specifically return a GT component. */
+    gtComponentFactories: Set<string>;
+    /** Statically visible string alternatives for non-singleton expressions. */
+    possibleStaticStrings: Map<string, Set<string>>;
+    /** Container or factory paths whose selected value can be `<T>`. */
+    possibleGTContainers: Set<string>;
+    /** Normal-script callables returning containers that may directly contain T. */
+    gtContainerFactories: Set<string>;
+    staticValues: Map<string, string | number | bigint | boolean | null>;
+    /** Values exposed to templates after Vue's top-level ref unwrapping. */
+    templateValues: Map<string, KnownValue>;
+    /** Cross-block component bindings whose runtime identity is not provable. */
+    uncertainComponents: Set<string>;
+    /** Cross-block aliases that can specifically resolve to a GT component. */
+    uncertainGTComponents: Set<string>;
+    /** Cross-block aliases that may resolve to a gt-vue string function. */
+    uncertainStringFunctions: Set<string>;
+    /** Mutable local helpers that are unsafe only when passed a translator. */
+    uncertainTranslationHelpers: Set<string>;
+    values: Map<string, KnownValue>;
+};
+/** Internal analyzer visits whose growth should remain bounded by source size. */
+export type VueScriptAnalysisStats = {
+    arrayEntryVisits: number;
+    containerKindVisits: number;
+    finalContainerSnapshotReads: number;
+    knownExpressionVisits: number;
+    stringFunctionVisits: number;
+    transformArrayEntryVisits: number;
+};
+/** Babel expression paired with the lexical scope in which it is evaluated. */
+export type ScopedExpression = {
+    node: t.Node;
+    scope: Scope;
+};
+export type ComponentKind = 'translation' | 'vue' | 'T';
+export type TemplateKnownValue = Extract<KnownValue, {
+    type: 'component' | 'string' | 'vue-builtin';
+}>;
+export type ComponentMemberCandidate = {
+    certain: boolean;
+    name: string;
+    value: TemplateKnownValue;
+};
+export type ComponentFactoryCandidate = {
+    gt: boolean;
+    name: string;
+};
+export type ObjectEntryResult = {
+    status: 'absent';
+} | {
+    status: 'known';
+    expression: ScopedExpression;
+} | {
+    status: 'unknown';
+};
+export type CollectedObjectEntries = {
+    entries: Map<string, ScopedExpression>;
+    unknownAll: boolean;
+    unknownNames: Set<string>;
+};
+export type TemplateExposure = {
+    type: 'known';
+    value: KnownValue;
+} | {
+    type: 'container';
+    kind?: TemplateContainerKind;
+    length?: number;
+    possibleGT?: true;
+} | {
+    type: 'uncertain';
+    component: boolean;
+    gtComponent: boolean;
+    stringFunction: boolean;
+} | {
+    type: 'factory';
+    gt: boolean;
+    gtContainer?: boolean;
+} | {
+    type: 'possible-static-strings';
+    values: Set<string>;
+} | {
+    type: 'static';
+    value: string | number | bigint | boolean | null;
+};
+export type GTContainerExposure = {
+    containers: Set<string>;
+    factories: Set<string>;
+};
+export type FinalContainerSnapshot = {
+    kind: 'array';
+    entries: Array<ScopedExpression | undefined>;
+} | {
+    kind: 'object';
+    entries: Map<string, ScopedExpression>;
+};
+export type FinalContainerOperation = {
+    position: number;
+    apply: (snapshot: FinalContainerSnapshot) => FinalContainerSnapshot | undefined;
+};
+export type ContainerIdentityReplay = {
+    unsafeBindings: Set<Binding>;
+    values: Map<Binding, ReplayValue | undefined>;
+};
+export type ReplayValue = ReplayCollectionReference | ReplayComputedReference | ReplayContainerReference | ReplayFunctionReference | ReplayGetterReference | ReplayLeaf | ReplayMethodReference | ReplayRefReference | ReplayUnsafe;
+export type ReplayContainerReference = {
+    type: 'container';
+    identity: ReplayContainerIdentity;
+    writePolicy: ContainerWritePolicy;
+};
+export type ReplayContainerIdentity = {
+    escaped: boolean;
+    snapshot: ReplayContainerSnapshot;
+};
+export type ReplayRefReference = {
+    type: 'ref';
+    identity: ReplayRefIdentity;
+    writePolicy: ContainerWritePolicy;
+};
+export type ReplayRefIdentity = {
+    escaped: boolean;
+    value: ReplayValue | undefined;
+};
+export type ReplayComputedReference = {
+    type: 'computed';
+    getter: ScopedExpression & {
+        node: t.Function;
+    };
+    writePolicy: ContainerWritePolicy;
+};
+export type ReplayGetterReference = {
+    type: 'getter';
+    getter: ScopedExpression & {
+        node: t.Function;
+    };
+    substitutions: Map<Binding, ReplayValue>;
+};
+export type ReplayFunctionReference = {
+    type: 'function';
+    boundArguments: ReplayValue[];
+    callable: ScopedExpression & {
+        node: t.Function;
+    };
+    substitutions: Map<Binding, ReplayValue>;
+    thisValue?: ReplayValue;
+};
+export type ReplayMethodReference = {
+    type: 'method';
+    callable: ScopedExpression & {
+        node: t.Function;
+    };
+    receiver?: ReplayContainerReference;
+    substitutions: Map<Binding, ReplayValue>;
+};
+export type ReplayCollectionReference = {
+    type: 'collection';
+    identity: ReplayCollectionIdentity;
+    iteration: 'entries' | 'values';
+    writePolicy: ContainerWritePolicy;
+};
+export type ReplayCollectionIdentity = {
+    entries: Map<string, ReplayValue>;
+    escaped: boolean;
+    kind: 'map' | 'set';
+    templateKeys: Map<string, string>;
+};
+export type ReplayContainerSnapshot = {
+    kind: 'array';
+    entries: Array<ReplayValue | undefined>;
+} | {
+    kind: 'object';
+    entries: Map<string, ReplayValue>;
+    prototype?: ReplayContainerReference;
+    setters?: Map<string, ReplayMethodReference>;
+};
+export type ReplayLeaf = {
+    type: 'leaf';
+    exactSelection?: boolean;
+    expression: ScopedExpression;
+    hasGT: boolean | undefined;
+    knownValue?: TemplateKnownValue;
+    selectionKind?: 'collection' | 'getter' | 'member' | 'ref';
+};
+export type ReplayUnsafe = {
+    type: 'unsafe';
+};
+export type ReplayEvaluationContext = {
+    /** Enables getter side effects only while replaying actual program execution. */
+    allowGetterEffects?: boolean;
+    substitutions: Map<Binding, ReplayValue>;
+    thisValue?: ReplayValue;
+    unsafeBindings: Set<Binding>;
+    values: Map<Binding, ReplayValue | undefined>;
+};
+export type ReplayLeafState = {
+    status: 'leaf';
+    value: ReplayLeaf;
+} | {
+    status: 'unsafe';
+};
+/** Mutable analysis caches shared by one parsed script block. */
+export type ScriptState = {
+    activeComponentFunctions: Set<t.Function>;
+    activeReplayFunctions: Set<t.Function>;
+    activeStringFunctions: Set<t.Function>;
+    activeTranslationFunctions: Set<t.Function>;
+    analysis: VueScriptAnalysis;
+    attachedLocalModules: Set<string>;
+    arrayEntries: Map<Binding, Array<ScopedExpression | undefined> | null>;
+    arrayEntriesInProgress: Set<Binding>;
+    componentPossibilities: Map<Binding, Map<ComponentKind | 'any', boolean>>;
+    componentFactoryCandidates: Map<Binding, ComponentFactoryCandidate[]>;
+    componentFactoryCandidatesInProgress: Set<Binding>;
+    bindings: Map<Binding, KnownValue>;
+    containerKindSnapshots: Map<Binding, {
+        arrayLengths: Map<string, number>;
+        kinds: Map<string, TemplateContainerKind>;
+    }>;
+    containerKindSnapshotsInProgress: Set<Binding>;
+    containerIdentityReplays: WeakMap<t.Node, ContainerIdentityReplay>;
+    containerWritePolicies: Map<Binding, ContainerWritePolicy | undefined>;
+    /** Immutable aliases proven to hold a non-callable or known non-string value. */
+    definiteNonStringFunctionBindings: Set<Binding>;
+    definiteNonStringFunctionBindingsInProgress: Set<Binding>;
+    entryProgram: t.Program;
+    finalContainerSnapshots: Map<Binding, FinalContainerSnapshot>;
+    finalContainerSnapshotsInProgress: Set<Binding>;
+    gtContainerPossibilities: Map<Binding, boolean>;
+    gtContainerPossibilitiesInProgress: Set<Binding>;
+    gtContainerPaths: Map<Binding, Set<string>>;
+    gtContainerPathsInProgress: Set<Binding>;
+    localCallableBindings: Map<Binding, ScopedExpression & {
+        node: t.Function;
+    }>;
+    mutationGTContainerPaths: Map<Binding, Set<string>>;
+    mutationGTContainerPathsInProgress: Set<Binding>;
+    mutationPossibleStaticStrings: Map<Binding, Map<string, Set<string>>>;
+    mutationPossibleStaticStringsInProgress: Set<Binding>;
+    mutableImportSources: Map<Binding, 'gt-vue' | 'vue'>;
+    nextReplayIdentityKey: number;
+    parameterSubstitutions: Array<Map<Binding, ScopedExpression>>;
+    paths: WeakMap<t.Node, NodePath<t.Node>>;
+    possibleStaticStrings: Map<Binding, Set<string>>;
+    possibleStaticStringsInProgress: Set<Binding>;
+    possibleStaticStringMembers: Map<Binding, Map<string, Set<string>>>;
+    possibleStaticStringMembersInProgress: Set<Binding>;
+    readonlyContainerUses: Map<Binding, boolean>;
+    readonlyContainerUsesInProgress: Set<Binding>;
+    replayIdentityKeys: WeakMap<object, string>;
+    resolvedBindings: Set<Binding>;
+    scopes: WeakMap<t.Node, Scope>;
+    thisSubstitutions: ScopedExpression[];
+    transformArrayEntries: Map<Binding, Array<ScopedExpression | undefined> | null>;
+    transformArrayEntriesInProgress: Set<Binding>;
+    /** Import and alias bindings that may call a forwarded translator. */
+    uncertainTranslationHelperBindings: Set<Binding>;
+    unsafeMutableNamespaceSources: Set<'gt-vue' | 'vue'>;
+};

package/dist/internal/script/model.js

@@ -0,0 +1 @@
+export {};

package/dist/internal/script/parser.d.ts

@@ -0,0 +1,3 @@
+import type * as t from '@babel/types';
+/** Parses one JavaScript or TypeScript block using Vue-compatible syntax. */
+export declare function parseScriptAst(source: string, language: string | undefined): t.File;

package/dist/internal/script/parser.js

@@ -0,0 +1,21 @@
+import { parse } from "@babel/parser";
+//#region src/internal/script/parser.ts
+/** Returns the Babel syntax plugins accepted by a Vue script language. */
+function getParserPlugins(language) {
+	const normalizedLanguage = language?.toLowerCase();
+	const plugins = ["decorators-legacy"];
+	if (normalizedLanguage === "ts" || normalizedLanguage === "tsx") plugins.push("typescript");
+	if (normalizedLanguage === "jsx" || normalizedLanguage === "tsx") plugins.push("jsx");
+	return plugins;
+}
+/** Parses one JavaScript or TypeScript block using Vue-compatible syntax. */
+function parseScriptAst(source, language) {
+	return parse(source, {
+		plugins: getParserPlugins(language),
+		sourceType: "module"
+	});
+}
+//#endregion
+export { parseScriptAst };
+
+//# sourceMappingURL=parser.js.map

package/dist/internal/script/parser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.js","names":[],"sources":["../../../src/internal/script/parser.ts"],"sourcesContent":["import { parse, type ParserPlugin } from '@babel/parser';\nimport type * as t from '@babel/types';\n\n/** Returns the Babel syntax plugins accepted by a Vue script language. */\nfunction getParserPlugins(language: string | undefined): ParserPlugin[] {\n  const normalizedLanguage = language?.toLowerCase();\n  const plugins: ParserPlugin[] = ['decorators-legacy'];\n  if (normalizedLanguage === 'ts' || normalizedLanguage === 'tsx') {\n    plugins.push('typescript');\n  }\n  if (normalizedLanguage === 'jsx' || normalizedLanguage === 'tsx') {\n    plugins.push('jsx');\n  }\n  return plugins;\n}\n\n/** Parses one JavaScript or TypeScript block using Vue-compatible syntax. */\nexport function parseScriptAst(\n  source: string,\n  language: string | undefined\n): t.File {\n  return parse(source, {\n    plugins: getParserPlugins(language),\n    sourceType: 'module',\n  });\n}\n"],"mappings":";;;AAIA,SAAS,iBAAiB,UAA8C;CACtE,MAAM,qBAAqB,UAAU,aAAa;CAClD,MAAM,UAA0B,CAAC,oBAAoB;AACrD,KAAI,uBAAuB,QAAQ,uBAAuB,MACxD,SAAQ,KAAK,aAAa;AAE5B,KAAI,uBAAuB,SAAS,uBAAuB,MACzD,SAAQ,KAAK,MAAM;AAErB,QAAO;;;AAIT,SAAgB,eACd,QACA,UACQ;AACR,QAAO,MAAM,QAAQ;EACnB,SAAS,iBAAiB,SAAS;EACnC,YAAY;EACb,CAAC"}

package/dist/internal/script/replay.d.ts

@@ -0,0 +1,53 @@
+import type { Binding, Scope } from '@babel/traverse';
+import type * as t from '@babel/types';
+import type { TemplateContainerKind } from '../types.js';
+import { type StaticPrimitiveResult } from '../utils.js';
+import type { ComponentFactoryCandidate, ComponentMemberCandidate, ContainerWrapperKind, ContainerWritePolicy, KnownValue, ReplayLeaf, ReplayLeafState, ReplayValue, ScopedExpression, ScriptState, VueScriptAnalysis } from './model.js';
+/** Static-analysis operations consumed by the source-ordered replay SCC. */
+export type ReplayAnalysisDependencies = {
+    ordinaryGlobalValues: ReadonlySet<string>;
+    readonlyArrayTransforms: ReadonlySet<string>;
+    bindingReadsUnsafeMutableImport: (binding: Binding, state: ScriptState) => boolean;
+    collectFunctionReturnExpressions: (fn: t.Function, scope: Scope, state: ScriptState) => ScopedExpression[];
+    collectPatternBindingNames: (pattern: t.Node) => string[];
+    composeContainerWritePolicy: (wrapper: ContainerWrapperKind, inner: ContainerWritePolicy | undefined) => ContainerWritePolicy;
+    knownValueKey: (value: KnownValue) => string;
+    readDefiniteArrayInteger: (node: t.Node | undefined, fallback: number, scope: Scope, state: ScriptState) => number | undefined;
+    readResolvedMemberPath: (node: t.Node, scope: Scope, state: ScriptState) => string | undefined;
+    readResolvedMemberProperty: (node: t.MemberExpression | t.OptionalMemberExpression, scope: Scope, state: ScriptState) => string | undefined;
+    readResolvedPropertyKey: (property: {
+        computed: boolean;
+        key: t.Node;
+    }, scope: Scope, state: ScriptState) => string | undefined;
+    readStaticFromScope: (node: t.Node | null | undefined, scope: Scope, seen: Set<Binding>, atPosition: number, analysis?: VueScriptAnalysis, allowNumericGlobals?: boolean) => StaticPrimitiveResult;
+    resolveCalledFunction: (node: t.Node | null | undefined, scope: Scope, state: ScriptState, seen: Set<t.Node>) => (ScopedExpression & {
+        node: t.Function;
+    }) | undefined;
+    resolveComputedGetter: (node: t.Node, scope: Scope, state: ScriptState) => (ScopedExpression & {
+        node: t.Function;
+    }) | undefined;
+    resolveKnownExpression: (node: t.Node | null | undefined, scope: Scope, state: ScriptState, seen: Set<Binding>) => KnownValue | undefined;
+};
+/** Narrow replay queries used by the surrounding script analyzer. */
+export type ReplayAnalysis = {
+    evaluateReplayAtPosition: (node: t.Node, scope: Scope, atPosition: number, state: ScriptState) => ReplayValue | undefined;
+    readDefiniteReplayGTContainerPaths: (binding: Binding, state: ScriptState) => Set<string> | null | undefined;
+    readReplayComponentCandidates: (binding: Binding, basePath: string, state: ScriptState) => ComponentMemberCandidate[] | undefined;
+    readReplayComponentFactoryCandidates: (binding: Binding, basePath: string, state: ScriptState) => ComponentFactoryCandidate[] | undefined;
+    readReplayContainerMetadata: (binding: Binding, basePath: string, state: ScriptState) => {
+        arrayLengths: Map<string, number>;
+        kinds: Map<string, TemplateContainerKind>;
+    } | undefined;
+    readReplayLeafState: (binding: Binding, state: ScriptState) => ReplayLeafState | undefined;
+    readSafeReplayLeafOverride: (binding: Binding, replayLeaf: ReplayLeafState | undefined, state: ScriptState) => Extract<ReplayLeafState, {
+        status: 'leaf';
+    }> | undefined;
+    isReplayGetterStringLeaf: (value: ReplayLeaf) => boolean;
+    replayBindingRetainsUnsafeIdentity: (binding: Binding, state: ScriptState) => boolean;
+};
+/**
+ * Creates the finite source-ordered identity analyzer used by script analysis.
+ * Dependencies are injected so the replay evaluator remains one cohesive SCC
+ * without creating a runtime import cycle back to the script orchestrator.
+ */
+export declare function createReplayAnalysis({ ordinaryGlobalValues: ORDINARY_GLOBAL_VALUES, readonlyArrayTransforms: READONLY_ARRAY_TRANSFORMS, bindingReadsUnsafeMutableImport, collectFunctionReturnExpressions, collectPatternBindingNames, composeContainerWritePolicy, knownValueKey, readDefiniteArrayInteger, readResolvedMemberPath, readResolvedMemberProperty, readResolvedPropertyKey, readStaticFromScope, resolveCalledFunction, resolveComputedGetter, resolveKnownExpression, }: ReplayAnalysisDependencies): ReplayAnalysis;