feat(overview-artifact): 產生可預覽總覽與截圖 fallback
This commit is contained in:
+43
-119
@@ -1,128 +1,52 @@
|
||||
/**
|
||||
* 圖解版總覽網頁：模板本身，以及兩份正本裡產生它、把網址寫回議題的規則。
|
||||
*/
|
||||
import test from 'node:test';
|
||||
import assert from 'node:assert/strict';
|
||||
import { promptStep, readPrompt, readTemplateFile } from './helpers/prompt-doc.js';
|
||||
import { readFileSync } from 'node:fs';
|
||||
import { join } from 'node:path';
|
||||
import { renderOverview, validateOverview } from '../scripts/overview-render.js';
|
||||
import { repoRoot } from './helpers/run-script.js';
|
||||
|
||||
const template = readTemplateFile('overview-artifact.html');
|
||||
const planPrompt = readPrompt('sdlc-plan');
|
||||
const analyzePrompt = readPrompt('sdlc-analyze');
|
||||
/** 只看產生總覽那一步，避免拿整份正本的任何一處來充數 */
|
||||
const planStep = promptStep(planPrompt, '產生圖解版總覽');
|
||||
/** 分析版的那一步，同樣只看它自己 */
|
||||
const analyzeStep = promptStep(analyzePrompt, '產生分析版的圖解總覽');
|
||||
const base = {
|
||||
schemaVersion: 1,
|
||||
source: { requirement: { repo: 'owner/repo', index: 7 } },
|
||||
requirement: {
|
||||
title: '建立需求總覽',
|
||||
summary: '把複雜需求整理成可理解的交接資料。',
|
||||
goals: ['可追蹤工作包', '可離線檢視'],
|
||||
nonGoals: [],
|
||||
diagrams: [{ kind: 'flowchart', direction: 'LR', title: '輸入流程', nodes: [{ id: 'a', label: '輸入' }, { id: 'b', label: '輸出' }], edges: [{ from: 'a', to: 'b', label: '轉換' }] }],
|
||||
formulas: [{ title: '估算', latex: 'a+b', description: '簡單公式' }],
|
||||
},
|
||||
workPackages: [{
|
||||
title: '建立抽取契約',
|
||||
type: 'implementation',
|
||||
description: '提供可重複的資料抽取。',
|
||||
scope: '只處理抽取。',
|
||||
repos: ['owner/repo'],
|
||||
depends: [],
|
||||
todos: [{ text: '建立函式', done: true }],
|
||||
acceptance: ['輸出固定'],
|
||||
issue: 'https://gitea.example/owner/repo/issues/8',
|
||||
handoff: false,
|
||||
}],
|
||||
overview: { generatedAt: '2026-09-18T00:00:00Z' },
|
||||
};
|
||||
|
||||
/** 模板要填的欄位 */
|
||||
const PLACEHOLDERS = ['標題', '來源議題', '總覽', '目標', '流程圖', '工作包全景', '頁尾'];
|
||||
|
||||
// ── 模板 ───────────────────────────────────────────────────────────
|
||||
|
||||
test('模板以 {{變數}} 佔位，欄位齊全', () => {
|
||||
const found = new Set([...template.matchAll(/\{\{([^}]+)\}\}/g)].map((m) => m[1]));
|
||||
for (const name of PLACEHOLDERS) {
|
||||
assert.ok(found.has(name), `模板缺少佔位 {{${name}}}`);
|
||||
}
|
||||
test('renderer validates and renders self-contained HTML', () => {
|
||||
const html = renderOverview(base);
|
||||
assert.match(html, /<!doctype html>/i);
|
||||
assert.match(html, /<svg/);
|
||||
assert.match(html, /建立抽取契約/);
|
||||
assert.match(html, /a\+b/);
|
||||
assert.doesNotMatch(html, /mermaid/);
|
||||
assert.doesNotMatch(html, /cdn\.jsdelivr/);
|
||||
});
|
||||
|
||||
test('樣式與內容分離：樣式集中在 style 區塊，內文不帶 style 屬性', () => {
|
||||
const styleBlocks = template.match(/<style>[\s\S]*?<\/style>/g) ?? [];
|
||||
assert.equal(styleBlocks.length, 1, '樣式應集中在單一 style 區塊');
|
||||
|
||||
const body = template.slice(template.indexOf('<body>'));
|
||||
assert.equal(/\sstyle="/.test(body), false, '內文不該出現行內樣式');
|
||||
test('renderer rejects unsupported schema versions and graph kinds', () => {
|
||||
assert.throws(() => validateOverview({ ...base, schemaVersion: 2 }), (error) => error.code === 'SCHEMA_UNSUPPORTED');
|
||||
assert.throws(() => validateOverview({ ...base, requirement: { ...base.requirement, diagrams: [{ kind: 'unknown', nodes: [], edges: [] }] } }), (error) => error.code === 'DIAGRAM_UNSUPPORTED');
|
||||
});
|
||||
|
||||
test('是一份可以直接開的完整 HTML', () => {
|
||||
assert.match(template, /^<!DOCTYPE html>/);
|
||||
assert.match(template, /<html lang="zh-Hant">/);
|
||||
assert.match(template, /<meta charset="utf-8">/);
|
||||
assert.match(template, /<meta name="viewport"/, '要能在投影與手機上都看得清楚');
|
||||
});
|
||||
|
||||
test('深色模式不靠手動切換也能用', () => {
|
||||
assert.match(template, /prefers-color-scheme: dark/);
|
||||
});
|
||||
|
||||
test('mermaid 圖有被實際渲染，不是把原始碼丟給讀者看', () => {
|
||||
// 只比對「有出現 mermaid 字樣」會被 CDN 網址矇混過去，要驗到真的有初始化
|
||||
const script = template.match(/<script[\s\S]*?<\/script>/)?.[0] ?? '';
|
||||
assert.match(script, /mermaid\.initialize\(/);
|
||||
assert.match(template, /class="mermaid"/);
|
||||
});
|
||||
|
||||
test('模板裡唯一的腳本就是畫圖那一段，沒有夾帶其他邏輯', () => {
|
||||
// AGENTS.md 說模板不含邏輯，這份是唯一的例外，例外要維持在最小範圍
|
||||
const scripts = template.match(/<script[\s\S]*?<\/script>/g) ?? [];
|
||||
assert.equal(scripts.length, 1);
|
||||
assert.equal(/\bfetch\(|localStorage|document\.cookie|XMLHttpRequest/.test(scripts[0]), false);
|
||||
});
|
||||
|
||||
test('工作包全景是整段佔位，規劃階段才填得了空字串', () => {
|
||||
// 規劃階段沒有工作包，整段要能消失，所以佔位不可以被包在寫死的 section 裡
|
||||
const line = template.split('\n').find((l) => l.includes('{{工作包全景}}'));
|
||||
assert.equal(line.trim(), '{{工作包全景}}');
|
||||
});
|
||||
|
||||
// ── sdlc-plan 的步驟 ───────────────────────────────────────────────
|
||||
|
||||
test('規劃正本交代了產生總覽與寫回網址', () => {
|
||||
assert.match(planStep, /templates\/overview-artifact\.html/);
|
||||
assert.match(planStep, /--overview-url/);
|
||||
assert.match(planStep, /issue-update/);
|
||||
});
|
||||
|
||||
test('規劃正本說明流程圖填進模板時不帶圍欄', () => {
|
||||
assert.match(planStep, /不\*\*含\*\*圍欄|\*\*不含\*\*圍欄/);
|
||||
});
|
||||
|
||||
test('規劃階段沒有工作包，正本要說清楚全景填空字串', () => {
|
||||
assert.match(planStep, /\{\{工作包全景\}\}/);
|
||||
assert.match(planStep, /填空字串/);
|
||||
});
|
||||
|
||||
test('正本說明這份網頁是給非技術的人看的', () => {
|
||||
assert.match(planStep, /非技術/);
|
||||
});
|
||||
|
||||
// ── sdlc-analyze 的步驟 ────────────────────────────────────────────
|
||||
|
||||
test('分析正本的全景圖用 graph TD，並畫出相依與時程', () => {
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /graph TD/);
|
||||
assert.match(step, /相依/);
|
||||
assert.match(step, /截止日/);
|
||||
});
|
||||
|
||||
test('分析正本沿用同一份模板，不另立一份', () => {
|
||||
assert.match(analyzePrompt, /同一份 `templates\/overview-artifact\.html`/);
|
||||
});
|
||||
|
||||
test('全景圖一樣有節點上限，超過時的做法有交代', () => {
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /12/);
|
||||
assert.match(step, /最長路徑/);
|
||||
});
|
||||
|
||||
test('分析正本說明重跑會就地更新，不會留下兩個連結', () => {
|
||||
const step = analyzeStep;
|
||||
assert.match(step, /就地更新/);
|
||||
assert.match(step, /只掛一個總覽網址/);
|
||||
});
|
||||
|
||||
// ── 兩份共通 ───────────────────────────────────────────────────────
|
||||
|
||||
test('兩份正本都指名同一支腳本寫回網址', () => {
|
||||
for (const [name, prompt] of [['sdlc-plan', planPrompt], ['sdlc-analyze', analyzePrompt]]) {
|
||||
assert.match(prompt, /--overview-url/, `${name} 沒有指名寫回網址的方式`);
|
||||
}
|
||||
});
|
||||
|
||||
test('規劃正本說明連結會自動附上私有提醒', () => {
|
||||
assert.match(planStep, /私有/);
|
||||
assert.match(planStep, /組織外/);
|
||||
});
|
||||
|
||||
test('規劃正本強調議題原本的白話總覽不被取代', () => {
|
||||
assert.match(planStep, /網頁是補充，不是取代/);
|
||||
test('renderer script is shipped and template is intentionally removed', () => {
|
||||
assert.equal(readFileSync(join(repoRoot, 'scripts', 'overview-render.js'), 'utf8').includes('overview'), true);
|
||||
assert.throws(() => readFileSync(join(repoRoot, 'templates', 'overview-artifact.html'), 'utf8'));
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user