parallel-codex-tui 0.1.0 → 0.1.4

package/dist/orchestrator/collaboration-channel.js

@@ -1,11 +1,47 @@
 import { join } from "node:path";
-import { appendJsonLine, ensureDir, writeJson, writeText } from "../core/file-store.js";
+import { z } from "zod";
+import { appendJsonLine, ensureDir, pathExists, readJson, readTextIfExists, writeJson, writeText } from "../core/file-store.js";
+import { FeatureStatusSchema } from "../domain/schemas.js";
+const CriticFindingRecordSchema = z.object({
+    id: z.string().trim().min(1),
+    severity: z.string().trim().optional(),
+    summary: z.string().trim().min(1).optional(),
+    message: z.string().trim().min(1).optional()
+}).passthrough().superRefine((record, context) => {
+    if (!record.summary && !record.message) {
+        context.addIssue({
+            code: z.ZodIssueCode.custom,
+            path: ["summary"],
+            message: "summary or legacy message is required"
+        });
+    }
+}).transform((record) => ({
+    ...record,
+    summary: record.summary ?? record.message ?? ""
+}));
+const ActorFindingReplyRecordSchema = z.object({
+    finding_id: z.string().trim().min(1),
+    status: z.string().trim().toLowerCase().pipe(z.enum(["fixed", "not_fixed", "deferred"])).default("fixed"),
+    notes: z.string().trim().optional()
+}).passthrough();
+const ApprovedFindingResolutionSchema = z.object({
+    version: z.literal(1),
+    decision: z.literal("approved"),
+    finding_ids: z.array(z.string().min(1)),
+    fixed_ids: z.array(z.string().min(1)),
+    unresolved_ids: z.array(z.string().min(1)).length(0)
+});
 export async function createFeatureChannel(input) {
-    const id = featureIdForTurn(input.turn, input.request);
+    const id = input.feature
+        ? `${input.turn.turnId}-${input.feature.id}`
+        : featureIdForTurn(input.turn, input.request);
     const dir = join(input.task.dir, "features", id);
     const dialoguePath = join(input.task.dir, "dialogue", "actor-critic.jsonl");
     const channel = {
         id,
+        title: input.feature?.title ?? input.request.trim(),
+        description: input.feature?.description ?? input.request.trim(),
+        dependsOn: input.feature?.depends_on ?? [],
         taskId: input.task.id,
         turnId: input.turn.turnId,
         dir,
@@ -15,10 +51,19 @@ export async function createFeatureChannel(input) {
         actorWorklogPath: join(dir, "actor-worklog.md"),
         actorRepliesPath: join(dir, "actor-replies.jsonl"),
         criticFindingsPath: join(dir, "critic-findings.jsonl"),
+        findingResolutionPath: join(dir, "finding-resolution.json"),
         decisionsPath: join(dir, "decisions.md")
     };
     await ensureDir(dir);
     await ensureDir(join(input.task.dir, "dialogue"));
+    if (input.resume) {
+        await ensureFeatureChannelFiles(input, channel);
+        const repairedState = await repairFeatureStatus(channel);
+        if (repairedState) {
+            await appendFeatureDialogue(channel, "feature.status_recovered", "actor", `Recovered Feature status as ${repairedState} while preserving collaboration evidence.`);
+        }
+        return channel;
+    }
     await writeText(channel.specPath, buildFeatureSpec(input, channel));
     await writeText(channel.actorWorklogPath, "");
     await writeText(channel.actorRepliesPath, "");
@@ -27,9 +72,26 @@ export async function createFeatureChannel(input) {
     await appendFeatureDialogue(channel, "feature.created", "actor", "Feature mailbox created for the current turn.");
     return channel;
 }
+async function ensureFeatureChannelFiles(input, channel) {
+    const files = [
+        [channel.specPath, buildFeatureSpec(input, channel)],
+        [channel.actorWorklogPath, ""],
+        [channel.actorRepliesPath, ""],
+        [channel.criticFindingsPath, ""]
+    ];
+    for (const [path, initialContent] of files) {
+        if (!(await pathExists(path))) {
+            await writeText(path, initialContent);
+        }
+    }
+}
 export function featurePromptContext(channel) {
     return {
         featureId: channel.id,
+        featureTitle: channel.title,
+        featureDescription: channel.description,
+        featureSpecPath: channel.specPath,
+        featureDependencies: channel.dependsOn,
         featureDir: channel.dir,
         dialoguePath: channel.dialoguePath,
         actorWorklogPath: channel.actorWorklogPath,
@@ -39,14 +101,59 @@ export function featurePromptContext(channel) {
     };
 }
 export async function updateFeatureStatus(channel, state) {
+    if (await pathExists(channel.statusPath)) {
+        try {
+            const current = await readJson(channel.statusPath, FeatureStatusSchema);
+            if (current.state === state && featureStatusMatchesChannel(current, channel)) {
+                return;
+            }
+        }
+        catch {
+            // A corrupt status is rebuilt from the authoritative feature channel.
+        }
+    }
     await writeJson(channel.statusPath, {
         feature_id: channel.id,
         task_id: channel.taskId,
         turn_id: channel.turnId,
+        title: channel.title,
+        description: channel.description,
+        depends_on: channel.dependsOn,
         state,
         updated_at: new Date().toISOString()
     });
 }
+async function repairFeatureStatus(channel) {
+    let current = null;
+    if (await pathExists(channel.statusPath)) {
+        try {
+            current = await readJson(channel.statusPath, FeatureStatusSchema);
+        }
+        catch {
+            // Invalid status is rebuilt without replacing the collaboration mailbox.
+        }
+    }
+    if (current && featureStatusMatchesChannel(current, channel)) {
+        return null;
+    }
+    const state = current && featureStatusIdentityMatches(current, channel)
+        ? current.state
+        : "created";
+    await updateFeatureStatus(channel, state);
+    return state;
+}
+function featureStatusMatchesChannel(status, channel) {
+    return featureStatusIdentityMatches(status, channel)
+        && status.title === channel.title
+        && status.description === channel.description
+        && status.depends_on.length === channel.dependsOn.length
+        && status.depends_on.every((dependency, index) => dependency === channel.dependsOn[index]);
+}
+function featureStatusIdentityMatches(status, channel) {
+    return status.feature_id === channel.id
+        && status.task_id === channel.taskId
+        && status.turn_id === channel.turnId;
+}
 export async function appendFeatureDialogue(channel, type, role, message, paths = {}) {
     await appendJsonLine(channel.dialoguePath, {
         time: new Date().toISOString(),
@@ -70,11 +177,155 @@ export async function writeFeatureDecision(channel, summary) {
         ""
     ].join("\n"));
 }
+export async function requireFeatureRevisionFindings(channel) {
+    const findings = await readFeatureCriticFindings(channel);
+    if (findings.length === 0) {
+        throw new Error(`Critic requested revision without valid critic findings for ${channel.id}.`);
+    }
+    const findingIds = findings.map((finding) => finding.id);
+    const replies = await readFeatureActorReplies(channel);
+    await writeFindingResolutionSnapshot(channel, "pending", findingIds, replies);
+    return findingIds;
+}
+export async function requireActorFindingReplies(channel, findingIds) {
+    const replies = await readFeatureActorReplies(channel);
+    const resolution = await writeFindingResolutionSnapshot(channel, "pending", findingIds, replies);
+    const unknown = resolution.unknownReplyIds;
+    if (unknown.length > 0) {
+        throw new Error(`Actor replies reference unknown Critic findings: ${unknown.join(", ")}.`);
+    }
+    const unresolved = resolution.unresolvedIds;
+    if (unresolved.length > 0) {
+        throw new Error(`Actor revision did not mark every Critic finding fixed: ${unresolved.join(", ")}.`);
+    }
+}
+export async function recordApprovedFindingResolution(channel, revisionFindingIds = [], options = {}) {
+    const findings = await readFeatureCriticFindings(channel);
+    const currentIds = [...new Set(findings.map((finding) => finding.id))];
+    const replies = await readFeatureActorReplies(channel);
+    const latestReplies = new Map(replies.map((reply) => [reply.finding_id, reply]));
+    const expectedIds = revisionFindingIds.length > 0
+        ? [...new Set(revisionFindingIds)]
+        : options.allowLegacyResolvedFindings
+            ? currentIds.filter((id) => latestReplies.get(id)?.status === "fixed")
+            : [];
+    const unexpected = currentIds.filter((id) => !expectedIds.includes(id));
+    if (unexpected.length > 0) {
+        await writeFindingResolutionRecord(channel, {
+            decision: "inconsistent",
+            findingIds: currentIds,
+            fixedIds: [],
+            unresolvedIds: currentIds,
+            unknownReplyIds: [...new Set(replies.map((reply) => reply.finding_id))]
+                .filter((id) => !currentIds.includes(id)),
+            replyCount: replies.length
+        });
+        throw new Error(`Critic approved with unresolved blocking findings: ${unexpected.join(", ")}.`);
+    }
+    await requireActorFindingReplies(channel, expectedIds);
+    await writeFindingResolutionRecord(channel, {
+        decision: "approved",
+        findingIds: expectedIds,
+        fixedIds: expectedIds,
+        unresolvedIds: [],
+        unknownReplyIds: [],
+        replyCount: replies.length
+    });
+}
+export async function featureCriticCheckpointIsReusable(channel, decision) {
+    try {
+        if (decision === "revision") {
+            return (await readFeatureCriticFindings(channel)).length > 0;
+        }
+        const resolutionText = await readTextIfExists(channel.findingResolutionPath);
+        if (resolutionText.trim()) {
+            return ApprovedFindingResolutionSchema.safeParse(JSON.parse(resolutionText)).success;
+        }
+        const findings = await readFeatureCriticFindings(channel);
+        const replies = await readFeatureActorReplies(channel);
+        if (findings.length === 0) {
+            return replies.length === 0;
+        }
+        const findingIds = new Set(findings.map((finding) => finding.id));
+        const latestReplies = new Map(replies.map((reply) => [reply.finding_id, reply]));
+        return [...latestReplies.keys()].every((id) => findingIds.has(id))
+            && [...findingIds].every((id) => latestReplies.get(id)?.status === "fixed");
+    }
+    catch {
+        return false;
+    }
+}
+async function readFeatureCriticFindings(channel) {
+    return readMailboxJsonLines(channel.criticFindingsPath, CriticFindingRecordSchema, "Critic finding");
+}
+async function readFeatureActorReplies(channel) {
+    return readMailboxJsonLines(channel.actorRepliesPath, ActorFindingReplyRecordSchema, "Actor finding reply");
+}
+async function writeFindingResolutionSnapshot(channel, decision, findingIds, replies) {
+    const ids = [...new Set(findingIds)];
+    const expected = new Set(ids);
+    const latest = new Map(replies.map((reply) => [reply.finding_id, reply]));
+    const fixedIds = ids.filter((id) => latest.get(id)?.status === "fixed");
+    const unresolvedIds = ids.filter((id) => latest.get(id)?.status !== "fixed");
+    const unknownReplyIds = [...latest.keys()].filter((id) => !expected.has(id));
+    await writeFindingResolutionRecord(channel, {
+        decision,
+        findingIds: ids,
+        fixedIds,
+        unresolvedIds,
+        unknownReplyIds,
+        replyCount: replies.length
+    });
+    return { fixedIds, unresolvedIds, unknownReplyIds };
+}
+async function writeFindingResolutionRecord(channel, input) {
+    await writeJson(channel.findingResolutionPath, {
+        version: 1,
+        decision: input.decision,
+        finding_ids: input.findingIds,
+        fixed_ids: input.fixedIds,
+        unresolved_ids: [
+            ...input.unresolvedIds,
+            ...input.unknownReplyIds.map((id) => `unknown:${id}`)
+        ],
+        unknown_reply_ids: input.unknownReplyIds,
+        reply_count: input.replyCount,
+        updated_at: new Date().toISOString()
+    });
+}
+async function readMailboxJsonLines(path, schema, label) {
+    const records = [];
+    const lines = (await readTextIfExists(path)).split(/\r?\n/);
+    for (let index = 0; index < lines.length; index += 1) {
+        const line = lines[index]?.trim() ?? "";
+        if (!line) {
+            continue;
+        }
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            throw new Error(`${label} JSONL is invalid at line ${index + 1}: ${path}.`);
+        }
+        const result = schema.safeParse(parsed);
+        if (!result.success) {
+            const issue = result.error.issues[0];
+            const field = issue?.path.length ? ` field ${issue.path.join(".")}` : "";
+            throw new Error(`${label}${field} is invalid at line ${index + 1}: ${path}.`);
+        }
+        records.push(result.data);
+    }
+    return records;
+}
 function buildFeatureSpec(input, channel) {
     return [
         "# Feature Mailbox",
         "",
         `Feature: ${channel.id}`,
+        `Title: ${channel.title}`,
+        `Description: ${channel.description}`,
+        `Depends on: ${channel.dependsOn.length > 0 ? channel.dependsOn.join(", ") : "(none)"}`,
         `Task: ${input.task.id}`,
         `Turn: ${input.turn.turnId}`,
         `Turn directory: ${input.turn.dir}`,
@@ -85,8 +336,8 @@ function buildFeatureSpec(input, channel) {
         "",
         "Protocol:",
         "- Actor writes implementation notes to actor-worklog.md.",
-        "- Critic writes one JSON object per blocking issue to critic-findings.jsonl.",
-        "- Actor replies to each critic finding in actor-replies.jsonl.",
+        '- Critic writes one JSON object per blocking issue to critic-findings.jsonl: {"id":"C-001","severity":"blocker","summary":"what must change"}.',
+        '- Actor replies to each fixed finding in actor-replies.jsonl: {"finding_id":"C-001","status":"fixed","notes":"what changed"}.',
         "- Supervisor writes the final decision summary to decisions.md.",
         ""
     ].join("\n");

package/dist/orchestrator/feature-plan.js

@@ -0,0 +1,70 @@
+import { z } from "zod";
+const FeatureIdSchema = z.string()
+    .trim()
+    .regex(/^[a-z0-9][a-z0-9-]{0,31}$/, "Feature ids must use lowercase letters, numbers, and hyphens only");
+const FeatureDefinitionSchema = z.object({
+    id: FeatureIdSchema,
+    title: z.string().trim().min(1),
+    description: z.string().trim().min(1),
+    depends_on: z.array(FeatureIdSchema).default([])
+});
+const FeaturePlanSchema = z.object({
+    version: z.literal(1),
+    features: z.array(FeatureDefinitionSchema).min(1).max(8)
+});
+export function parseFeaturePlan(input) {
+    const plan = FeaturePlanSchema.parse(input);
+    const ids = new Set();
+    for (const feature of plan.features) {
+        if (ids.has(feature.id)) {
+            throw new Error(`Duplicate feature id: ${feature.id}`);
+        }
+        ids.add(feature.id);
+    }
+    for (const feature of plan.features) {
+        const dependencies = new Set();
+        for (const dependency of feature.depends_on) {
+            if (dependency === feature.id) {
+                throw new Error(`Feature ${feature.id} cannot depend on itself`);
+            }
+            if (!ids.has(dependency)) {
+                throw new Error(`Feature ${feature.id} depends on unknown feature: ${dependency}`);
+            }
+            if (dependencies.has(dependency)) {
+                throw new Error(`Feature ${feature.id} has duplicate dependency: ${dependency}`);
+            }
+            dependencies.add(dependency);
+        }
+    }
+    const waves = buildWaves(plan);
+    if (waves.flat().length !== plan.features.length) {
+        const scheduled = new Set(waves.flat().map((feature) => feature.id));
+        const cycle = plan.features
+            .filter((feature) => !scheduled.has(feature.id))
+            .map((feature) => feature.id)
+            .sort();
+        throw new Error(`Feature dependency cycle: ${cycle.join(", ")}`);
+    }
+    return plan;
+}
+export function featureExecutionWaves(plan) {
+    return buildWaves(plan);
+}
+function buildWaves(plan) {
+    const completed = new Set();
+    const remaining = new Set(plan.features.map((feature) => feature.id));
+    const waves = [];
+    while (remaining.size > 0) {
+        const wave = plan.features.filter((feature) => (remaining.has(feature.id)
+            && feature.depends_on.every((dependency) => completed.has(dependency))));
+        if (wave.length === 0) {
+            break;
+        }
+        waves.push(wave);
+        for (const feature of wave) {
+            remaining.delete(feature.id);
+            completed.add(feature.id);
+        }
+    }
+    return waves;
+}

package/dist/orchestrator/judge-artifacts.js

@@ -0,0 +1,236 @@
+import { Lexer } from "marked";
+export const JUDGE_REQUIRED_ARTIFACTS = [
+    "requirements.md",
+    "plan.md",
+    "acceptance.md",
+    "actor-brief.md",
+    "critic-brief.md"
+];
+export const JUDGE_VALIDATION_FILE = "judge-validation.json";
+const CONTRACT_ARTIFACTS = {
+    "requirements.md": { prefix: "R", label: "requirement" },
+    "plan.md": { prefix: "P", label: "plan step" },
+    "acceptance.md": { prefix: "A", label: "acceptance criterion" }
+};
+const PLACEHOLDER_PATTERN = /^(?:todo|tbd|pending|placeholder|to be determined|coming soon|n\/?a|none|待定|稍后(?:补充|处理)?|后续(?:补充|再说)?|暂无|未定|占位(?:内容)?)(?:\s*[:：-].*)?$/iu;
+const ARTIFACT_NAME_PATTERN = /^(?:requirements|plan|acceptance|actor-brief|critic-brief)\.md$/iu;
+export function validateJudgeArtifacts(input) {
+    const requirements = validateContractArtifact("requirements.md", input["requirements.md"] ?? "");
+    const plan = validateContractArtifact("plan.md", input["plan.md"] ?? "");
+    const acceptance = validateContractArtifact("acceptance.md", input["acceptance.md"] ?? "");
+    const actorBrief = validateBriefArtifact("actor-brief.md", input["actor-brief.md"] ?? "");
+    const criticBrief = validateBriefArtifact("critic-brief.md", input["critic-brief.md"] ?? "");
+    const requirementIds = new Set(requirements.items.map((item) => item.id));
+    for (const item of acceptance.items) {
+        const unknown = item.references.filter((reference) => !requirementIds.has(reference));
+        if (unknown.length > 0) {
+            acceptance.validation.issues.push(issue("acceptance.md", "unknown_requirement_reference", `${item.id} references unknown requirement${unknown.length === 1 ? "" : "s"}: ${unknown.join(", ")}.`));
+            acceptance.validation.state = "invalid";
+        }
+    }
+    const artifacts = {
+        "requirements.md": requirements.validation,
+        "plan.md": plan.validation,
+        "acceptance.md": acceptance.validation,
+        "actor-brief.md": actorBrief.validation,
+        "critic-brief.md": criticBrief.validation
+    };
+    const issues = JUDGE_REQUIRED_ARTIFACTS.flatMap((file) => artifacts[file].issues);
+    return {
+        version: 1,
+        state: issues.length === 0 ? "valid" : "invalid",
+        artifacts,
+        contract: {
+            requirements: requirements.items,
+            plan: plan.items,
+            acceptance: acceptance.items
+        },
+        briefs: {
+            actor: actorBrief.content,
+            critic: criticBrief.content
+        },
+        issues
+    };
+}
+function validateContractArtifact(file, markdown) {
+    const parsed = parseMarkdown(markdown);
+    const issues = [];
+    const spec = CONTRACT_ARTIFACTS[file];
+    if (!markdown.trim()) {
+        issues.push(issue(file, "missing", `${file} is missing or empty.`));
+    }
+    else if (parsed.parseError) {
+        issues.push(issue(file, "parse_error", `${file} is not valid Markdown: ${parsed.parseError}`));
+    }
+    const normalized = parsed.listItems.map((text, index) => normalizeContractItem(text, spec.prefix, index));
+    const meaningful = normalized.filter((item) => isMeaningful(item.text));
+    const placeholders = normalized.filter((item) => !isMeaningful(item.text));
+    if (markdown.trim() && !parsed.parseError && parsed.listItems.length === 0) {
+        issues.push(issue(file, "missing_list_items", `${file} must contain at least one Markdown list ${spec.label}.`));
+    }
+    else if (parsed.listItems.length > 0 && meaningful.length === 0) {
+        issues.push(issue(file, "placeholder_only", `${file} contains only placeholder ${spec.label}s.`));
+    }
+    else if (placeholders.length > 0) {
+        issues.push(issue(file, "placeholder_items", `${file} still contains ${placeholders.length} placeholder ${spec.label}${placeholders.length === 1 ? "" : "s"}.`));
+    }
+    const duplicateIds = repeatedIds(meaningful);
+    if (duplicateIds.length > 0) {
+        issues.push(issue(file, "duplicate_item_id", `${file} repeats item id${duplicateIds.length === 1 ? "" : "s"}: ${duplicateIds.join(", ")}.`));
+    }
+    return {
+        validation: {
+            state: issues.length === 0 ? "valid" : "invalid",
+            item_count: parsed.listItems.length,
+            content_count: parsed.content.length,
+            issues
+        },
+        items: meaningful
+    };
+}
+function validateBriefArtifact(file, markdown) {
+    const parsed = parseMarkdown(markdown);
+    const issues = [];
+    const meaningful = parsed.content.filter(isMeaningful);
+    const placeholders = parsed.content.filter((content) => !isMeaningful(content));
+    if (!markdown.trim()) {
+        issues.push(issue(file, "missing", `${file} is missing or empty.`));
+    }
+    else if (parsed.parseError) {
+        issues.push(issue(file, "parse_error", `${file} is not valid Markdown: ${parsed.parseError}`));
+    }
+    else if (parsed.content.length === 0) {
+        issues.push(issue(file, "missing_content", `${file} must contain implementation guidance below its heading.`));
+    }
+    else if (meaningful.length === 0) {
+        issues.push(issue(file, "placeholder_only", `${file} contains only placeholder guidance.`));
+    }
+    else if (placeholders.length > 0) {
+        issues.push(issue(file, "placeholder_items", `${file} still contains placeholder guidance.`));
+    }
+    return {
+        validation: {
+            state: issues.length === 0 ? "valid" : "invalid",
+            item_count: parsed.listItems.length,
+            content_count: parsed.content.length,
+            issues
+        },
+        content: meaningful
+    };
+}
+function parseMarkdown(markdown) {
+    if (!markdown.trim()) {
+        return { listItems: [], content: [] };
+    }
+    try {
+        const tokens = Lexer.lex(markdown);
+        return {
+            listItems: collectListItems(tokens),
+            content: collectContent(tokens)
+        };
+    }
+    catch (error) {
+        return {
+            listItems: [],
+            content: [],
+            parseError: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+function collectListItems(tokens) {
+    const items = [];
+    for (const token of tokens) {
+        if (isListToken(token)) {
+            for (const item of token.items) {
+                const text = normalizeWhitespace(item.tokens
+                    .filter((itemToken) => itemToken.type !== "list")
+                    .map(tokenPlainText)
+                    .join(" "));
+                items.push(text);
+                items.push(...collectListItems(item.tokens.filter(isListToken)));
+            }
+            continue;
+        }
+        const nested = tokenTokens(token);
+        if (nested.length > 0) {
+            items.push(...collectListItems(nested));
+        }
+    }
+    return items;
+}
+function collectContent(tokens) {
+    const content = [];
+    for (const token of tokens) {
+        if (token.type === "heading" || token.type === "space" || token.type === "hr" || token.type === "def") {
+            continue;
+        }
+        if (isListToken(token)) {
+            content.push(...collectListItems([token]));
+            continue;
+        }
+        if (token.type === "blockquote") {
+            content.push(...collectContent(tokenTokens(token)));
+            continue;
+        }
+        const text = normalizeWhitespace(tokenPlainText(token));
+        if (text) {
+            content.push(text);
+        }
+    }
+    return content;
+}
+function normalizeContractItem(text, prefix, index) {
+    const idPattern = new RegExp(`^\\[?(${prefix}-\\d{1,4})\\]?\\s*(?:[:：-]\\s*)?`, "iu");
+    const match = text.match(idPattern);
+    const id = match?.[1]?.toUpperCase() ?? `${prefix}-${String(index + 1).padStart(3, "0")}`;
+    const normalizedText = normalizeWhitespace(match ? text.slice(match[0].length) : text);
+    const references = Array.from(normalizedText.matchAll(/\bR-\d{1,4}\b/giu), (reference) => reference[0].toUpperCase());
+    return {
+        id,
+        text: normalizedText,
+        references: [...new Set(references)]
+    };
+}
+function tokenPlainText(token) {
+    if (token.type === "checkbox" || token.type === "space" || token.type === "def") {
+        return "";
+    }
+    const nested = tokenTokens(token);
+    if (nested.length > 0) {
+        return nested.map(tokenPlainText).join(" ");
+    }
+    if ("text" in token && typeof token.text === "string") {
+        return token.text;
+    }
+    return typeof token.raw === "string" ? token.raw : "";
+}
+function tokenTokens(token) {
+    return "tokens" in token && Array.isArray(token.tokens) ? token.tokens : [];
+}
+function isListToken(token) {
+    return token.type === "list" && "items" in token && Array.isArray(token.items);
+}
+function normalizeWhitespace(value) {
+    return value.replace(/\s+/gu, " ").trim();
+}
+function isMeaningful(value) {
+    const normalized = normalizeWhitespace(value).replace(/[.。,，;；:：!！?？]+$/gu, "").trim();
+    return Boolean(normalized)
+        && /[\p{L}\p{N}]/u.test(normalized)
+        && !PLACEHOLDER_PATTERN.test(normalized)
+        && !ARTIFACT_NAME_PATTERN.test(normalized);
+}
+function repeatedIds(items) {
+    const seen = new Set();
+    const duplicates = new Set();
+    for (const item of items) {
+        if (seen.has(item.id)) {
+            duplicates.add(item.id);
+        }
+        seen.add(item.id);
+    }
+    return [...duplicates];
+}
+function issue(file, code, message) {
+    return { file, code, message };
+}