textlint-rule-preset-ai-writing
Version:
textlintプリセット：AIっぽい記述パターンを検出し、より自然な日本語表現を促すルール集
221 lines (208 loc) • 11.3 kB
JavaScript
;
Object.defineProperty(exports, "__esModule", {
value: true
});
exports.default = void 0;
var _regexpStringMatcher = require("@textlint/regexp-string-matcher");
var _textlintUtilToString = require("textlint-util-to-string");
/**
* テクニカルライティングガイドラインに基づく文書品質改善ルール
*
* 詳細なガイドラインについては以下を参照してください：
* https://github.com/textlint-ja/textlint-rule-preset-ai-writing/blob/main/docs/tech-writing-guidelines.md
*/
const rule = (context, options = {}) => {
const {
Syntax,
report,
locator,
RuleError
} = context;
const allows = options.allows ?? [];
const disableRedundancyGuidance = options.disableRedundancyGuidance ?? false;
const disableVoiceGuidance = options.disableVoiceGuidance ?? false;
const disableConsistencyGuidance = options.disableConsistencyGuidance ?? false;
const disableClarityGuidance = options.disableClarityGuidance ?? false;
const disableStructureGuidance = options.disableStructureGuidance ?? false;
const enableDocumentAnalysis = options.enableDocumentAnalysis ?? true;
// テクニカルライティングガイダンスパターン
// 1. 簡潔性の原則 (Conciseness) - 冗長表現の排除
const redundancyGuidance = [{
pattern: /まず最初に/g,
message: "【簡潔性】冗長表現が検出されました。「まず最初に」→「まず」または「最初に」への簡潔化を検討してください。",
category: "redundancy"
}, {
pattern: /あらかじめ予測/g,
message: "【簡潔性】冗長表現が検出されました。「あらかじめ予測」→「予測」への簡潔化を検討してください。",
category: "redundancy"
}, {
pattern: /することができます/g,
message: "【簡潔性】冗長な助動詞表現が検出されました。「できます」または「します」への簡潔化を検討してください。",
category: "redundancy"
}, {
pattern: /する必要があります/g,
message: "【簡潔性】冗長な義務表現が検出されました。「してください」または「します」への直接的な表現を検討してください。",
category: "redundancy"
}, {
pattern: /言うまでもなく/g,
message: "【簡潔性】不要な前置き表現が検出されました。核心から始める簡潔な文章構成を検討してください。",
category: "redundancy"
}];
// 2. 明確性の原則 (Clarity) - 能動態と具体的な動詞
const voiceGuidance = [{
pattern: /が行われ(て|る|ます)/g,
message: "【明確性】受動的で抽象的な表現が検出されました。具体的な動詞を使った能動態への変更を検討してください（例：「実行する」「処理する」）。",
category: "voice"
}, {
pattern: /の変更を行/g,
message: "【明確性】名詞化された表現が検出されました。「を変更する」のような直接的な動詞表現を検討してください。",
category: "voice"
}, {
pattern: /の実装を実施/g,
message: "【明確性】二重の名詞化表現が検出されました。「を実装する」への簡潔化を検討してください。",
category: "voice"
}, {
pattern: /によって[実行処理実施]され/g,
message: "【明確性】受動態表現が検出されました。「○○が△△を実行する」のような能動態への変更を検討してください。",
category: "voice"
}, {
pattern: /がシステムによって実行される/g,
message: "【明確性】受動態表現が検出されました。「システムが○○を実行する」のような能動態への変更を検討してください。",
category: "voice"
}, {
pattern: /によって実行され/g,
message: "【明確性】受動態表現が検出されました。「システムが○○を実行する」のような能動態への変更を検討してください。",
category: "voice"
}];
// 3. 具体性の原則 (Concreteness) - 抽象的表現の具体化
const clarityGuidance = [{
pattern: /高速な(?:パフォーマンス|処理|動作)/g,
message: "【具体性】抽象的な性能表現が検出されました。具体的な数値基準の提示を検討してください（例：「50ms未満の応答時間」）。",
category: "clarity"
}, {
pattern: /大幅に(?:向上|改善|削減)/g,
message: "【具体性】定量化されていない変化表現が検出されました。具体的な数値や割合の提示を検討してください。",
category: "clarity"
}, {
pattern: /効率的な/g,
message: "【具体性】抽象的な評価表現が検出されました。何に対してどのように効率的なのか、具体的な説明を検討してください。",
category: "clarity"
}, {
pattern: /適切な/g,
message: "【具体性】曖昧な判断表現が検出されました。何を基準として適切なのか、具体的な条件や基準の明示を検討してください。",
category: "clarity"
}, {
pattern: /必要に応じて/g,
message: "【具体性】曖昧な条件表現が検出されました。どのような状況で必要なのか、具体的な判断基準の明示を検討してください。",
category: "clarity"
}];
// 4. 一貫性の原則 (Consistency) - 用語と表現の統一
const consistencyGuidance = [{
pattern: /(ユーザー.*?(?:クライアント|顧客))|(?:(?:クライアント|顧客).*?ユーザー)/g,
message: "【一貫性】同一対象を指す用語の混在が検出されました。文書全体で統一した用語の使用を検討してください。",
category: "consistency"
}, {
pattern: /(設定画面.*?(?:設定ページ|環境設定))|(?:(?:設定ページ|環境設定).*?設定画面)/g,
message: "【一貫性】機能名称の表記揺れが検出されました。プロジェクト内で統一した名称の使用を検討してください。",
category: "consistency"
}, {
pattern: /(です。.*?である。)|(である。.*?です。)/g,
message: "【一貫性】文体の混在が検出されました。「です・ます調」または「だ・である調」への統一を検討してください。",
category: "consistency"
}];
// 5. 構造化の原則 (Structure) - 情報の論理的整理
const structureGuidance = [{
pattern: /また、.*?また、/g,
message: "【構造化】接続表現の重複が検出されました。箇条書きや段落分けによる情報整理を検討してください。",
category: "structure"
}, {
pattern: /(?:第一に|まず).*?(?:第二に|次に).*?(?:第三に|最後に)/g,
message: "【構造化】連続的な手順説明が検出されました。番号付きリストまたは見出し構造での整理を検討してください。",
category: "structure"
}];
// 文書全体の品質評価指標
let hasDocumentIssues = false;
const documentQualityMetrics = {
redundancy: 0,
voice: 0,
clarity: 0,
consistency: 0,
structure: 0
};
return {
[Syntax.Paragraph](node) {
// StringSourceを使用してコードブロックを除外したテキストを取得
const source = new _textlintUtilToString.StringSource(node, {
replacer({
node,
emptyValue
}) {
// コードブロック、インラインコードを除外
if (node.type === "Code" || node.type === "InlineCode") {
return emptyValue();
}
return undefined;
}
});
const text = source.toString();
// 許可パターンのチェック
if (allows.length > 0) {
const matches = (0, _regexpStringMatcher.matchPatterns)(text, allows);
if (matches.length > 0) {
return;
}
}
// 各カテゴリのガイダンスを統合
const allGuidancePatterns = [...(disableRedundancyGuidance ? [] : redundancyGuidance), ...(disableVoiceGuidance ? [] : voiceGuidance), ...(disableClarityGuidance ? [] : clarityGuidance), ...(disableConsistencyGuidance ? [] : consistencyGuidance), ...(disableStructureGuidance ? [] : structureGuidance)];
for (const {
pattern,
message,
category
} of allGuidancePatterns) {
const matches = text.matchAll(pattern);
for (const match of matches) {
const index = match.index ?? 0;
// プレーンテキストの位置を元のノード内の位置に変換
const originalIndex = source.originalIndexFromIndex(index);
const originalEndIndex = source.originalIndexFromIndex(index + match[0].length);
if (originalIndex !== undefined && originalEndIndex !== undefined) {
const originalRange = [originalIndex, originalEndIndex];
// カテゴリ別のメトリクスを更新
documentQualityMetrics[category]++;
hasDocumentIssues = true;
report(node, new RuleError(message, {
padding: locator.range(originalRange)
}));
}
}
}
},
[Syntax.DocumentExit](node) {
// 文書全体の分析を実行（enableDocumentAnalysisがtrueの場合）
if (enableDocumentAnalysis && hasDocumentIssues) {
const totalIssues = Object.values(documentQualityMetrics).reduce((sum, count) => sum + count, 0);
// カテゴリ別の詳細な分析結果を含むメッセージを生成
const categoryDetails = [];
if (documentQualityMetrics.redundancy > 0) {
categoryDetails.push(`簡潔性: ${documentQualityMetrics.redundancy}件`);
}
if (documentQualityMetrics.voice > 0) {
categoryDetails.push(`明確性: ${documentQualityMetrics.voice}件`);
}
if (documentQualityMetrics.clarity > 0) {
categoryDetails.push(`具体性: ${documentQualityMetrics.clarity}件`);
}
if (documentQualityMetrics.consistency > 0) {
categoryDetails.push(`一貫性: ${documentQualityMetrics.consistency}件`);
}
if (documentQualityMetrics.structure > 0) {
categoryDetails.push(`構造化: ${documentQualityMetrics.structure}件`);
}
const detailsText = categoryDetails.length > 0 ? ` [内訳: ${categoryDetails.join(", ")}]` : "";
report(node, new RuleError(`【テクニカルライティング品質分析】この文書で${totalIssues}件の改善提案が見つかりました${detailsText}。効果的なテクニカルライティングの7つのC（Clear, Concise, Correct, Coherent, Concrete, Complete, Courteous）の原則に基づいて見直しを検討してください。詳細なガイドライン: https://github.com/textlint-ja/textlint-rule-preset-ai-writing/blob/main/docs/tech-writing-guidelines.md`));
}
}
};
};
var _default = exports.default = rule;
//# sourceMappingURL=ai-tech-writing-guideline.js.map