draft-ole 0.9.0

package/dist/transformer/inline-recovery.d.ts

@@ -0,0 +1,109 @@
+/**
+ * inline-recovery — ヘルパー関数インライン展開の採否判定
+ *
+ * 仕様: `.kiro/specs/transformer-inline-recovery-spec/`
+ *   - design.md §6.1
+ *   - requirements.md 1.1, 1.2, 3.2, 4.1, 4.2, 5.2
+ *
+ * 単一責任:
+ *   1. ハンドラ AST を再帰スキャンしてヘルパー呼び出し候補を列挙する
+ *   2. design §6.1 の優先順位（1. function-declaration → 2. not-module-level
+ *      → 3. mutable-binding → 4. has-parameters → 5. has-arguments）に従い
+ *      採否を分類する
+ *   3. 採用候補から `Map<string, ts.ArrowFunction>` を構築する
+ *   4. 不採用候補から DT012 診断を生成する
+ *
+ * 副作用なしの純粋関数のみで構成し、`fileDiagnostics` への push は
+ * 呼び出し側（transformer/index.ts）の責任。
+ */
+import * as ts from 'typescript';
+import type { OnCallInfo } from './call-detector';
+import { type HandlerIR, type IdentifierRef } from './handler-ir-extractor';
+import type { RecoveryOutcome, TransformerBaseContext, ValidationOutcome } from './per-call-context';
+import type { StateIdFallback } from './state-id-fallback';
+/** 採用された helper 候補。`buildInlineMap` の戻り値要素に対応。 */
+export interface AcceptedHelper {
+    readonly kind: 'accepted';
+    readonly name: string;
+    readonly arrow: ts.ArrowFunction;
+    readonly callSite: ts.CallExpression;
+}
+/** 不採用理由（discriminated union）。 */
+export type HelperRejectionReason = {
+    readonly code: 'has-arguments';
+    readonly argCount: number;
+} | {
+    readonly code: 'has-parameters';
+    readonly paramCount: number;
+} | {
+    readonly code: 'function-declaration';
+} | {
+    readonly code: 'not-module-level';
+} | {
+    readonly code: 'mutable-binding';
+};
+export interface RejectedHelper {
+    readonly kind: 'rejected';
+    readonly name: string;
+    readonly callSite: ts.CallExpression;
+    readonly reason: HelperRejectionReason;
+}
+export type HelperClassification = AcceptedHelper | RejectedHelper;
+/**
+ * ハンドラ本体を再帰スキャンし、ヘルパー呼び出し候補を分類して返す。
+ *
+ * 候補とは: ExpressionStatement 直下の CallExpression で、
+ * 呼び出し対象が単純 Identifier かつ宣言が解決可能なもの（引数の有無は問わない）。
+ * 同名 helper は最初の出現のみを返す（重複 push を防ぐ）。
+ */
+export declare function classifyHelperCandidates(arrowFn: ts.ArrowFunction, sourceFile: ts.SourceFile, checker: ts.TypeChecker): readonly HelperClassification[];
+/**
+ * 採用候補のみから inlineMap を構築する。
+ * 既存 `buildInlineMap` と互換の戻り値（Map<name, ArrowFunction>）。
+ */
+export declare function buildInlineMap(classifications: readonly HelperClassification[]): Map<string, ts.ArrowFunction>;
+/**
+ * 不採用候補から DT012 診断を生成する。
+ *
+ * - `category`: 呼び出し側が `options.strictHelpers ? Warning : Suggestion` を渡す
+ * - `relatedInformation`: reason.code を平文化したメッセージを 1 件付与
+ */
+export declare function buildRejectionDiagnostics(classifications: readonly HelperClassification[], sourceFile: ts.SourceFile, category: ts.DiagnosticCategory): readonly ts.Diagnostic[];
+/**
+ * `tryInlineRecovery` の戻り値 (成功時)。
+ *
+ * relocated from index.ts (transformer-index-pipeline-split task 2.4).
+ */
+export interface InlineRecoveryResult {
+    stateIdMap: Map<ts.Symbol, string>;
+    inlineMap: Map<string, ts.ArrowFunction>;
+    rejectionDiagnostics: readonly ts.Diagnostic[];
+}
+/**
+ * バリデーションエラー時にモジュールレベル関数インライン展開による回復を試みる。
+ *
+ * 手順:
+ * 1. ハンドラ内のゼロ引数モジュールレベル関数呼び出しを検出して inlineMap を構築
+ * 2. 検出した関数名を extraWhitelist に追加して再バリデーション
+ * 3. 各インライン関数の本体を独立してバリデーション
+ * 4. すべてパスした場合 stateIdMap と inlineMap を返す
+ *
+ * @returns 回復成功時 { stateIdMap, inlineMap, rejectionDiagnostics }、
+ *          失敗時 { rejectionDiagnostics } または undefined
+ */
+export declare function tryInlineRecovery(arrowFn: ts.ArrowFunction, ir: HandlerIR, refs: IdentifierRef[], checker: ts.TypeChecker, program: ts.Program, sourceFile: ts.SourceFile, extraWhitelist: readonly string[] | undefined, debugMode: boolean, fallback: StateIdFallback, rejectionCategory: ts.DiagnosticCategory): InlineRecoveryResult | {
+    rejectionDiagnostics: readonly ts.Diagnostic[];
+} | undefined;
+/**
+ * Phase 4a per-call delegate: validation エラーありの場合の inline recovery 分岐を実行する。
+ *
+ * 2 個の private sub-helper を順次呼んで `RecoveryOutcome` を組み立てる薄い
+ * オーケストレーター (本体 ≤ 12 行)。
+ *
+ * @param base - per-invocation base context (checker / program / fallback / debug など)
+ * @param callInfo - 対象 .on() 呼出情報
+ * @param ir - Phase 2a で抽出済の HandlerIR
+ * @param validation - Phase 3 outcome (元の validation 診断を保持)
+ */
+export declare function runInlineRecoveryBranch(base: TransformerBaseContext, callInfo: OnCallInfo, ir: HandlerIR, validation: ValidationOutcome): RecoveryOutcome;
+//# sourceMappingURL=inline-recovery.d.ts.map

package/dist/transformer/inline-recovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-recovery.d.ts","sourceRoot":"","sources":["../../src/transformer/inline-recovery.ts"],"names":[],"mappings":"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"}

package/dist/transformer/inline-recovery.js

@@ -0,0 +1,369 @@
+"use strict";
+/**
+ * inline-recovery — ヘルパー関数インライン展開の採否判定
+ *
+ * 仕様: `.kiro/specs/transformer-inline-recovery-spec/`
+ *   - design.md §6.1
+ *   - requirements.md 1.1, 1.2, 3.2, 4.1, 4.2, 5.2
+ *
+ * 単一責任:
+ *   1. ハンドラ AST を再帰スキャンしてヘルパー呼び出し候補を列挙する
+ *   2. design §6.1 の優先順位（1. function-declaration → 2. not-module-level
+ *      → 3. mutable-binding → 4. has-parameters → 5. has-arguments）に従い
+ *      採否を分類する
+ *   3. 採用候補から `Map<string, ts.ArrowFunction>` を構築する
+ *   4. 不採用候補から DT012 診断を生成する
+ *
+ * 副作用なしの純粋関数のみで構成し、`fileDiagnostics` への push は
+ * 呼び出し側（transformer/index.ts）の責任。
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyHelperCandidates = classifyHelperCandidates;
+exports.buildInlineMap = buildInlineMap;
+exports.buildRejectionDiagnostics = buildRejectionDiagnostics;
+exports.tryInlineRecovery = tryInlineRecovery;
+exports.runInlineRecoveryBranch = runInlineRecoveryBranch;
+const ts = __importStar(require("typescript"));
+const handler_ir_extractor_1 = require("./handler-ir-extractor");
+const helper_decl_utils_1 = require("./helper-decl-utils");
+const identifier_collector_1 = require("./identifier-collector");
+const state_id_resolver_1 = require("./state-id-resolver");
+const whitelist_validator_1 = require("./whitelist-validator");
+// ---- ヘルパー: シンボル解決 -------------------------------------------------
+// resolveValueDeclaration / isModuleLevelVariableDeclaration / isConstDeclaration は
+// `./helper-decl-utils` に移管。本ファイルでは import して使用する。
+// ---- 候補列挙 + 分類 --------------------------------------------------------
+/**
+ * 1 つの候補 CallExpression に対して採否を確定する。
+ * design §6.1 の優先順位（先勝ち）に従う。
+ */
+function classifyOne(callSite, identName, checker, sourceFile) {
+    if (!ts.isIdentifier(callSite.expression))
+        return undefined;
+    const decl = (0, helper_decl_utils_1.resolveValueDeclaration)(callSite.expression, checker);
+    if (decl === undefined) {
+        // 解決不能 Identifier → 候補列挙対象外（既存 DT001 路に委ねる）
+        return undefined;
+    }
+    // 1. function-declaration
+    if (ts.isFunctionDeclaration(decl)) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'function-declaration' },
+        };
+    }
+    // VariableDeclaration で arrow を初期化しているか確認
+    if (!ts.isVariableDeclaration(decl)) {
+        // 想定外形状（class、parameter 等）→ not-module-level 相当として扱う
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'not-module-level' },
+        };
+    }
+    // 2. not-module-level
+    // ブロック内 const、cross-file（別 sourceFile）含む
+    if (decl.getSourceFile() !== sourceFile || !(0, helper_decl_utils_1.isModuleLevelVariableDeclaration)(decl, sourceFile)) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'not-module-level' },
+        };
+    }
+    // 3. mutable-binding
+    if (!(0, helper_decl_utils_1.isConstDeclaration)(decl)) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'mutable-binding' },
+        };
+    }
+    // initializer が ArrowFunction でなければ採否対象外（function expression 等）
+    if (decl.initializer === undefined || !ts.isArrowFunction(decl.initializer)) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'not-module-level' },
+        };
+    }
+    const arrow = decl.initializer;
+    // 4. has-parameters（宣言側 param > 0）— 呼び出し側引数より優先
+    if (arrow.parameters.length > 0) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'has-parameters', paramCount: arrow.parameters.length },
+        };
+    }
+    // 5. has-arguments
+    if (callSite.arguments.length > 0) {
+        return {
+            kind: 'rejected',
+            name: identName,
+            callSite,
+            reason: { code: 'has-arguments', argCount: callSite.arguments.length },
+        };
+    }
+    // すべての条件をクリア → 採用
+    return {
+        kind: 'accepted',
+        name: identName,
+        arrow,
+        callSite,
+    };
+}
+/**
+ * ハンドラ本体を再帰スキャンし、ヘルパー呼び出し候補を分類して返す。
+ *
+ * 候補とは: ExpressionStatement 直下の CallExpression で、
+ * 呼び出し対象が単純 Identifier かつ宣言が解決可能なもの（引数の有無は問わない）。
+ * 同名 helper は最初の出現のみを返す（重複 push を防ぐ）。
+ */
+function classifyHelperCandidates(arrowFn, sourceFile, checker) {
+    const seen = new Set();
+    const result = [];
+    function visit(node) {
+        if (ts.isExpressionStatement(node)) {
+            const expr = node.expression;
+            if (ts.isCallExpression(expr) && ts.isIdentifier(expr.expression)) {
+                const name = expr.expression.text;
+                if (!seen.has(name)) {
+                    const cls = classifyOne(expr, name, checker, sourceFile);
+                    if (cls !== undefined) {
+                        seen.add(name);
+                        result.push(cls);
+                    }
+                }
+            }
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(arrowFn.body);
+    return result;
+}
+// ---- 採用マップ構築 ---------------------------------------------------------
+/**
+ * 採用候補のみから inlineMap を構築する。
+ * 既存 `buildInlineMap` と互換の戻り値（Map<name, ArrowFunction>）。
+ */
+function buildInlineMap(classifications) {
+    const map = new Map();
+    for (const c of classifications) {
+        if (c.kind === 'accepted' && !map.has(c.name)) {
+            map.set(c.name, c.arrow);
+        }
+    }
+    return map;
+}
+// ---- 診断生成 ---------------------------------------------------------------
+/** reason.code を人読み形に整形する。 */
+function describeReason(reason) {
+    switch (reason.code) {
+        case 'has-arguments':
+            return `has-arguments: call site passes ${reason.argCount} argument(s)`;
+        case 'has-parameters':
+            return `has-parameters: helper takes ${reason.paramCount} parameter(s)`;
+        case 'function-declaration':
+            return 'function-declaration: helper is a function declaration, not a const arrow';
+        case 'not-module-level':
+            return 'not-module-level: helper is not declared at module top-level';
+        case 'mutable-binding':
+            return 'mutable-binding: helper is declared with let (mutable binding)';
+    }
+}
+/**
+ * 不採用候補から DT012 診断を生成する。
+ *
+ * - `category`: 呼び出し側が `options.strictHelpers ? Warning : Suggestion` を渡す
+ * - `relatedInformation`: reason.code を平文化したメッセージを 1 件付与
+ */
+function buildRejectionDiagnostics(classifications, sourceFile, category) {
+    const diags = [];
+    for (const c of classifications) {
+        if (c.kind !== 'rejected')
+            continue;
+        const reasonText = describeReason(c.reason);
+        const start = c.callSite.getStart(sourceFile);
+        const length = c.callSite.getWidth(sourceFile);
+        const messageText = `DT012: Helper '${c.name}' is not eligible for inline recovery (${reasonText}). ` +
+            'Supported shape: zero-argument module-level const arrow function, single level.';
+        diags.push({
+            file: sourceFile,
+            start,
+            length,
+            messageText,
+            category,
+            code: 9012,
+            source: 'draftole-transformer',
+            relatedInformation: [
+                {
+                    file: sourceFile,
+                    start,
+                    length,
+                    messageText: `reason: ${c.reason.code}`,
+                    category: ts.DiagnosticCategory.Message,
+                    code: 9012,
+                },
+            ],
+        });
+    }
+    return diags;
+}
+/**
+ * バリデーションエラー時にモジュールレベル関数インライン展開による回復を試みる。
+ *
+ * 手順:
+ * 1. ハンドラ内のゼロ引数モジュールレベル関数呼び出しを検出して inlineMap を構築
+ * 2. 検出した関数名を extraWhitelist に追加して再バリデーション
+ * 3. 各インライン関数の本体を独立してバリデーション
+ * 4. すべてパスした場合 stateIdMap と inlineMap を返す
+ *
+ * @returns 回復成功時 { stateIdMap, inlineMap, rejectionDiagnostics }、
+ *          失敗時 { rejectionDiagnostics } または undefined
+ */
+function tryInlineRecovery(arrowFn, ir, refs, checker, program, sourceFile, extraWhitelist, debugMode, fallback, rejectionCategory) {
+    // 採否判定: 候補ごとに accepted / rejected を確定
+    const classifications = classifyHelperCandidates(arrowFn, sourceFile, checker);
+    const rejectionDiagnostics = buildRejectionDiagnostics(classifications, sourceFile, rejectionCategory);
+    const inlineMap = buildInlineMap(classifications);
+    // 採用候補が無い場合: rejection 診断のみ呼び出し側に返却
+    if (inlineMap.size === 0) {
+        if (rejectionDiagnostics.length === 0)
+            return undefined;
+        return { rejectionDiagnostics };
+    }
+    // インライン関数名を whitelist に追加して再バリデーション
+    const extendedWhitelist = [...(extraWhitelist !== null && extraWhitelist !== void 0 ? extraWhitelist : []), ...inlineMap.keys()];
+    const revalidDiags = (0, whitelist_validator_1.validateHandler)(ir, refs, program, sourceFile, extendedWhitelist);
+    if (revalidDiags.some((d) => d.category === ts.DiagnosticCategory.Error)) {
+        return rejectionDiagnostics.length > 0 ? { rejectionDiagnostics } : undefined;
+    }
+    // 各インライン関数本体を個別にバリデーション
+    for (const [name, funcArrow] of inlineMap) {
+        const { ir: inlineIr } = (0, handler_ir_extractor_1.extractHandlerIR)(funcArrow, sourceFile);
+        if (inlineIr === undefined) {
+            return rejectionDiagnostics.length > 0 ? { rejectionDiagnostics } : undefined;
+        }
+        const inlineRefs = (0, identifier_collector_1.collectIdentifiers)(inlineIr);
+        const inlineDiags = (0, whitelist_validator_1.validateHandler)(inlineIr, inlineRefs, program, sourceFile, extraWhitelist);
+        if (inlineDiags.some((d) => d.category === ts.DiagnosticCategory.Error)) {
+            if (debugMode) {
+                console.log(`[draftole-transformer] inline recovery: '${name}' body has validation errors`);
+            }
+            return rejectionDiagnostics.length > 0 ? { rejectionDiagnostics } : undefined;
+        }
+    }
+    const resolution = (0, state_id_resolver_1.buildStateIdMapWithInlining)(arrowFn, checker, inlineMap, fallback);
+    // マージ後も未解決 Symbol が残る場合は recovery 不成立とする。
+    if (resolution.unresolved.size > 0) {
+        if (debugMode) {
+            const names = [...resolution.unresolved.values()].map((id) => id.text).join(', ');
+            console.log(`[draftole-transformer] inline recovery: unresolved states remain after merge: ${names}`);
+        }
+        return rejectionDiagnostics.length > 0 ? { rejectionDiagnostics } : undefined;
+    }
+    return { stateIdMap: resolution.stateIdMap, inlineMap, rejectionDiagnostics };
+}
+/**
+ * sub-helper 1: tryInlineRecovery を呼び、3 通りの戻り値を flat な `InlineRecoveryAttempt`
+ * に正規化する。base.strictHelpers に応じて rejectionCategory (Warning / Suggestion) を決定し、
+ * base.debug を debugMode として渡す。
+ */
+function attemptInlineRecovery(base, callInfo, ir) {
+    const refs = (0, identifier_collector_1.collectIdentifiers)(ir);
+    const rejectionCategory = base.strictHelpers
+        ? ts.DiagnosticCategory.Warning
+        : ts.DiagnosticCategory.Suggestion;
+    const result = tryInlineRecovery(callInfo.handlerArg, ir, refs, base.checker, base.program, base.sourceFile, base.extraWhitelist, base.debug, base.fallback, rejectionCategory);
+    if (result === undefined) {
+        return { success: false, stateIdMap: new Map(), inlineMap: undefined, rejectionDiagnostics: [] };
+    }
+    if ('stateIdMap' in result) {
+        return {
+            success: true,
+            stateIdMap: result.stateIdMap,
+            inlineMap: result.inlineMap,
+            rejectionDiagnostics: result.rejectionDiagnostics,
+        };
+    }
+    return {
+        success: false,
+        stateIdMap: new Map(),
+        inlineMap: undefined,
+        rejectionDiagnostics: result.rejectionDiagnostics,
+    };
+}
+/**
+ * sub-helper 2: 元の validation エラーと DT012 rejection 診断を mix する中央管理箇所。
+ *
+ * - success: recovery 成功 → 元の validation エラーは superseded、rejection のみ発行
+ * - failure: 元の validation エラー + DT012 rejection を順に concat
+ *
+ * 既存テストが mix 順序を等価性 oracle とするため、本関数で順序を固定する。
+ */
+function composeRecoveryDiagnostics(originalValidationDiags, rejectionDiagnostics, success) {
+    if (success)
+        return rejectionDiagnostics;
+    return [...originalValidationDiags, ...rejectionDiagnostics];
+}
+/**
+ * Phase 4a per-call delegate: validation エラーありの場合の inline recovery 分岐を実行する。
+ *
+ * 2 個の private sub-helper を順次呼んで `RecoveryOutcome` を組み立てる薄い
+ * オーケストレーター (本体 ≤ 12 行)。
+ *
+ * @param base - per-invocation base context (checker / program / fallback / debug など)
+ * @param callInfo - 対象 .on() 呼出情報
+ * @param ir - Phase 2a で抽出済の HandlerIR
+ * @param validation - Phase 3 outcome (元の validation 診断を保持)
+ */
+function runInlineRecoveryBranch(base, callInfo, ir, validation) {
+    const attempt = attemptInlineRecovery(base, callInfo, ir);
+    return {
+        success: attempt.success,
+        stateIdMap: attempt.stateIdMap,
+        inlineMap: attempt.inlineMap,
+        diagnostics: composeRecoveryDiagnostics(validation.diagnostics, attempt.rejectionDiagnostics, attempt.success),
+    };
+}
+//# sourceMappingURL=inline-recovery.js.map

package/dist/transformer/inline-recovery.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inline-recovery.js","sourceRoot":"","sources":["../../src/transformer/inline-recovery.ts"],"names":[],"mappings":"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"}

package/dist/transformer/label-injector.d.ts

@@ -0,0 +1,105 @@
+/**
+ * label-injector: 抽出済み varName を用いて、対象 CallExpression を
+ * `__draftole_label__(<origCall>, "<varName>")` の形にラップする AST プリミティブを提供する。
+ *
+ * # 役割
+ * - 本モジュールは **AST ノードを構築するだけ** で、SourceFile への変異は一切行わない。
+ *   呼び出し側（task 4.7 の transformer pipeline）が printer / replace で適用する。
+ *
+ * # `__draftole_label__` の import 戦略（reuse-existing-import）
+ * design §label-injector の方針:
+ *   1. 既に DraftOle が export している識別子（`KNOWN_DRAFTOLE_IDENTIFIERS`）のいずれかを
+ *      named import で取り込んでいる ImportDeclaration をファイル先頭から探索する。
+ *   2. 見つかった ImportDeclaration の `moduleSpecifier` をそのまま再利用し、
+ *      その named imports に `__draftole_label__` を **追加** する。
+ *   3. 見つからない場合は新規 import を生成せず、対象ファイルの書き換えをスキップし、
+ *      pipeline 側で diagnostic コード `DT013`（Suggestion カテゴリ）を発行する。
+ *
+ * # DT013 フォールバック方針
+ * `findDraftOleImport` が `undefined` を返した場合、呼び出し側 pipeline は:
+ *   - 新規 import を作らない
+ *   - 当該ファイルの label 注入をスキップする
+ *   - `fileDiagnostics` に Suggestion カテゴリ・コード `DT013` の `ts.Diagnostic` を push する
+ * 本モジュールはあくまでプリミティブを提供するのみで、上記オーケストレーションは行わない。
+ *
+ * 対応 requirements: 4.1, 4.2, 4.5
+ * 対応 design: §label-injector
+ */
+import * as ts from 'typescript';
+/**
+ * `__draftole_label__` をどこから import するかの方針を表す。
+ * `findDraftOleImport` の戻り値。
+ */
+export interface DraftOleImportSite {
+    /** 拡張対象の既存 ImportDeclaration（named imports に `__draftole_label__` を追加する）。 */
+    readonly importDecl: ts.ImportDeclaration;
+    /** その import の moduleSpecifier 文字列（例: `'draft-ole'`, `'../../dist/index.js'`）。 */
+    readonly moduleSpecifier: string;
+}
+/**
+ * SourceFile を走査し、再利用可能な DraftOle named import を探す。
+ *
+ * 仕様:
+ * - `ts.ImportDeclaration` を順に検査する。
+ * - `importClause.namedBindings` が `ts.NamedImports` の場合のみ対象。
+ *   （`NamespaceImport` の場合は本モジュールでは扱わない。）
+ * - いずれかの `ImportSpecifier.name.text` が `KNOWN_DRAFTOLE_IDENTIFIERS` に含まれていれば
+ *   その import を採用する（**ファイル中で最初に一致したもの**）。
+ * - 該当が無ければ `undefined` を返す。
+ *
+ * # 呼び出し側への期待
+ * `undefined` が返った場合、pipeline は label 注入をスキップし、
+ * Suggestion カテゴリの diagnostic（コード `DT013`）を発行すること。
+ */
+export declare function findDraftOleImport(sourceFile: ts.SourceFile): DraftOleImportSite | undefined;
+/**
+ * `__draftole_label__` が既に SourceFile の named imports に存在するかを判定する。
+ * 存在する場合は pipeline 側で import 追加処理をスキップできる。
+ */
+export declare function hasLabelImport(sourceFile: ts.SourceFile): boolean;
+/**
+ * `__draftole_label__(<callExpr>, "<varName>")` の CallExpression を構築する。
+ *
+ * - 純粋な AST 構築のみ。SourceFile への変異は行わない。
+ * - 返り値の型は元の式と同じ（runtime helper の signature が identity 型透過のため）。
+ */
+export declare function buildLabeledCall(callExpr: ts.CallExpression, varName: string): ts.CallExpression;
+/**
+ * `__draftole_label__` を単独で named import する新規 ImportDeclaration を生成する。
+ *
+ * # 用途: emit-safe な import 注入
+ * 呼び出し側 pipeline は、本関数で生成した ImportDeclaration を
+ * SourceFile の statements 先頭に prepend することで `__draftole_label__` を
+ * 取り込む。`updateImportDeclaration` で既存 import を mutate する方式は
+ * TS→TS printing では問題なく動作するが、`program.emit()` 経由の TS→JS では
+ * binder が pre-transform 時点のシンボル表で識別子解決を行うため、後付けで
+ * 加えた named specifier が「bare identifier」として未解決化される。
+ *
+ * # 重要: emit substitution の限界
+ * TypeScript の ES→CJS modules transformer は、シンボル束縛済みの識別子のみ
+ * `draft_ole_N.__draftole_label__` 形に書き換える。transformer が新規追加した
+ * 識別子はシンボル束縛を持たないため、`import` 構文を新規追加するだけでは
+ * call site が bare identifier のまま emit され ReferenceError になる。
+ *
+ * このため、CommonJS ターゲット時は本関数ではなく
+ * {@link createLabelRequireStatement} を使い、`const { __draftole_label__ } = require(...)`
+ * を直接生成すること。本関数は ESM ターゲット / TS→TS printing 用途に残す。
+ *
+ * @param moduleSpecifier `findDraftOleImport` で取得した既存 draft-ole import の
+ *   module path をそのまま渡す。新規 import は同一 module を参照する必要がある。
+ */
+export declare function createLabelImportDeclaration(moduleSpecifier: string): ts.ImportDeclaration;
+/**
+ * CommonJS 出力向けの `__draftole_label__` 取り込み文を生成する。
+ *
+ * 生成形:
+ *   `const { __draftole_label__ } = require('<moduleSpecifier>');`
+ *
+ * TS の ES→CJS modules transformer による識別子置換に依存しないため、
+ * transformer が新規追加した識別子でも安全に解決される。
+ *
+ * 呼び出し側 pipeline は、`compilerOptions.module` が CommonJS 系の場合に
+ * 本関数の戻り値を SourceFile.statements の先頭に prepend する。
+ */
+export declare function createLabelRequireStatement(moduleSpecifier: string): ts.VariableStatement;
+//# sourceMappingURL=label-injector.d.ts.map

package/dist/transformer/label-injector.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"label-injector.d.ts","sourceRoot":"","sources":["../../src/transformer/label-injector.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,KAAK,EAAE,MAAM,YAAY,CAAC;AA6BjC;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,6EAA6E;IAC7E,QAAQ,CAAC,UAAU,EAAE,EAAE,CAAC,iBAAiB,CAAC;IAC1C,kFAAkF;IAClF,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,kBAAkB,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,kBAAkB,GAAG,SAAS,CAqB5F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,UAAU,EAAE,EAAE,CAAC,UAAU,GAAG,OAAO,CAajE;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,EAAE,CAAC,cAAc,EAC3B,OAAO,EAAE,MAAM,GACd,EAAE,CAAC,cAAc,CAMnB;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAgB,4BAA4B,CAC1C,eAAe,EAAE,MAAM,GACtB,EAAE,CAAC,iBAAiB,CAiBtB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,2BAA2B,CACzC,eAAe,EAAE,MAAM,GACtB,EAAE,CAAC,iBAAiB,CA4BtB"}