android2harmony 0.1.7 → 0.1.8

package/skills/a2h-spec-design/scripts/move_spec_technical_reference.mjs

@@ -0,0 +1,198 @@
+#!/usr/bin/env node
+// Move an exact level-2 '## 技术参考' section from a SPEC to its design file.
+
+import { chmodSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { randomBytes } from 'node:crypto';
+
+const TECHNICAL_REFERENCE_HEADING = '## 技术参考';
+const RELATED_UI_HEADING = '## 相关 UI';
+const LEVEL_2_HEADING = /^##(?:\s|$)/;
+
+function fatal(message) {
+  process.stderr.write(`${message}\n`);
+  process.exit(1);
+}
+
+function readText(path) {
+  return readFileSync(path, 'utf8');
+}
+
+// Mirror Python's str.splitlines(keepends=True): split on \n, \r\n, or \r,
+// keeping the line terminator attached to each element.
+function splitlinesKeepends(text) {
+  const lines = [];
+  let start = 0;
+  for (let i = 0; i < text.length; i++) {
+    const ch = text[i];
+    if (ch === '\n') {
+      lines.push(text.slice(start, i + 1));
+      start = i + 1;
+    } else if (ch === '\r') {
+      if (text[i + 1] === '\n') {
+        lines.push(text.slice(start, i + 2));
+        i++;
+      } else {
+        lines.push(text.slice(start, i + 1));
+      }
+      start = i + 1;
+    }
+  }
+  if (start < text.length) {
+    lines.push(text.slice(start));
+  }
+  return lines;
+}
+
+function rstripNewline(line) {
+  return line.replace(/\r?\n$/, '');
+}
+
+function exactHeadingIndexes(lines, heading) {
+  const indexes = [];
+  lines.forEach((line, index) => {
+    if (rstripNewline(line).replace(/\s+$/, '') === heading) {
+      indexes.push(index);
+    }
+  });
+  return indexes;
+}
+
+function sectionEnd(lines, start) {
+  for (let index = start + 1; index < lines.length; index++) {
+    if (LEVEL_2_HEADING.test(rstripNewline(lines[index]))) {
+      return index;
+    }
+  }
+  return lines.length;
+}
+
+function newlineFor(text) {
+  return text.includes('\r\n') ? '\r\n' : '\n';
+}
+
+function writeTemp(path, content) {
+  const mode = statSync(path).mode & 0o777;
+  const dir = dirname(path);
+  const suffix = randomBytes(6).toString('hex');
+  const tempPath = resolve(dir, `.${path.split('/').pop()}.${suffix}`);
+  try {
+    writeFileSync(tempPath, content, { encoding: 'utf8' });
+    chmodSync(tempPath, mode);
+  } catch (err) {
+    try {
+      unlinkSync(tempPath);
+    } catch {
+      // ignore
+    }
+    throw err;
+  }
+  return tempPath;
+}
+
+function unlinkMissingOk(path) {
+  try {
+    unlinkSync(path);
+  } catch {
+    // ignore
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length < 2) {
+    fatal('usage: move_spec_technical_reference.mjs <input_file> <design_path>');
+  }
+  const inputFile = resolve(argv[0]);
+  const designPath = resolve(argv[1]);
+
+  let inputStat;
+  try {
+    inputStat = statSync(inputFile);
+  } catch {
+    fatal(`input SPEC does not exist or is not a file: ${inputFile}`);
+  }
+  if (!inputStat.isFile()) {
+    fatal(`input SPEC does not exist or is not a file: ${inputFile}`);
+  }
+
+  let designStat;
+  try {
+    designStat = statSync(designPath);
+  } catch {
+    fatal(`design file does not exist or is not a file: ${designPath}`);
+  }
+  if (!designStat.isFile()) {
+    fatal(`design file does not exist or is not a file: ${designPath}`);
+  }
+
+  const specText = readText(inputFile);
+  const designText = readText(designPath);
+  const specLines = splitlinesKeepends(specText);
+  const designLines = splitlinesKeepends(designText);
+
+  const technicalIndexes = exactHeadingIndexes(specLines, TECHNICAL_REFERENCE_HEADING);
+  if (technicalIndexes.length === 0) {
+    process.stdout.write('technical_reference=absent\n');
+    process.stdout.write('moved=false\n');
+    return 0;
+  }
+  if (technicalIndexes.length !== 1) {
+    fatal(
+      `expected at most one exact '${TECHNICAL_REFERENCE_HEADING}' section, found ${technicalIndexes.length}`,
+    );
+  }
+
+  const relatedUiIndexes = exactHeadingIndexes(designLines, RELATED_UI_HEADING);
+  if (relatedUiIndexes.length !== 1) {
+    fatal(
+      `expected exactly one exact '${RELATED_UI_HEADING}' heading in design file, found ${relatedUiIndexes.length}`,
+    );
+  }
+  if (exactHeadingIndexes(designLines, TECHNICAL_REFERENCE_HEADING).length > 0) {
+    fatal(
+      `design file already contains exact '${TECHNICAL_REFERENCE_HEADING}'; refusing to duplicate the section`,
+    );
+  }
+
+  const start = technicalIndexes[0];
+  const end = sectionEnd(specLines, start);
+  const sectionLines = specLines.slice(start, end);
+  const newSpecText = [...specLines.slice(0, start), ...specLines.slice(end)].join('');
+
+  const insertAt = relatedUiIndexes[0];
+  const insertedLines = [...sectionLines];
+  if (insertedLines.length > 0 && insertedLines[insertedLines.length - 1].trim()) {
+    insertedLines.push(newlineFor(designText));
+  }
+  const newDesignText = [
+    ...designLines.slice(0, insertAt),
+    ...insertedLines,
+    ...designLines.slice(insertAt),
+  ].join('');
+
+  const specTemp = writeTemp(inputFile, newSpecText);
+  const designTemp = writeTemp(designPath, newDesignText);
+  try {
+    renameSync(specTemp, inputFile);
+    try {
+      renameSync(designTemp, designPath);
+    } catch (err) {
+      // Restore the SPEC content if the second replacement fails.
+      const restoreTemp = writeTemp(inputFile, specText);
+      renameSync(restoreTemp, inputFile);
+      throw err;
+    }
+  } finally {
+    unlinkMissingOk(specTemp);
+    unlinkMissingOk(designTemp);
+  }
+
+  process.stdout.write('technical_reference=present\n');
+  process.stdout.write('moved=true\n');
+  process.stdout.write(`input_file=${inputFile}\n`);
+  process.stdout.write(`design_path=${designPath}\n`);
+  return 0;
+}
+
+process.exit(main());

package/skills/a2h-spec-design/scripts/validate_spec_design_output.mjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+const FILE_PATH_TABLE_HEADINGS = new Set([
+  '### 相关 UI 及文件路径',
+  '### 相关数据实体及文件路径',
+  '### 相关逻辑模块及文件路径',
+]);
+
+function emit(payload, code = 0) {
+  process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
+  process.exit(code);
+}
+
+function fail(message, extra = {}) {
+  emit({ ok: false, error: message, ...extra }, 1);
+}
+
+function expanduser(p) {
+  if (p === '~') return homedir();
+  if (p.startsWith('~/') || p.startsWith('~\\')) return join(homedir(), p.slice(2));
+  return p;
+}
+
+function isDir(p) {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+function isFile(p) {
+  try {
+    return statSync(p).isFile();
+  } catch {
+    return false;
+  }
+}
+
+function isTableRow(line) {
+  const stripped = line.trim();
+  return stripped.startsWith('|') && stripped.endsWith('|');
+}
+
+function splitTableRow(line) {
+  const stripped = line.trim();
+  const inner = stripped.replace(/^\|+/, '').replace(/\|+$/, '');
+  return inner.split('|').map((cell) => cell.trim());
+}
+
+function isSeparatorRow(cells) {
+  if (cells.length === 0) return false;
+  return cells.every((cell) => {
+    const compact = cell.replace(/ /g, '');
+    return compact.length > 0 && [...compact].every((ch) => ch === '-' || ch === ':');
+  });
+}
+
+function addIssue(issues, lineNo, location, problem, suggestion) {
+  issues.push({ line: lineNo, location, problem, suggestion });
+}
+
+function displayPathToRealPath(displayPath, root) {
+  const displayRoot = `/${basename(root)}`;
+  if (!displayPath.startsWith(`${displayRoot}/`)) {
+    return null;
+  }
+  const rel = displayPath.slice(displayRoot.length + 1);
+  return join(root, rel);
+}
+
+function collectFilePathTableIssues(lines, root, issues) {
+  let activeHeading = null;
+
+  lines.forEach((line, i) => {
+    const idx = i + 1;
+    const stripped = line.trim();
+
+    if (stripped.startsWith('### ')) {
+      activeHeading = FILE_PATH_TABLE_HEADINGS.has(stripped) ? stripped : null;
+      return;
+    }
+
+    if (stripped.startsWith('## ')) {
+      activeHeading = null;
+      return;
+    }
+
+    if (!activeHeading || !isTableRow(line)) {
+      return;
+    }
+
+    const cells = splitTableRow(line);
+    if (cells.length === 0 || isSeparatorRow(cells)) {
+      return;
+    }
+    if (cells.some((cell) => cell === '文件路径')) {
+      return;
+    }
+
+    if (cells.some((cell) => cell === 'None')) {
+      addIssue(
+        issues,
+        idx,
+        activeHeading,
+        '文件路径表格行包含 None。',
+        '删除该行，或补充真实存在的文件路径和语义描述。',
+      );
+    }
+
+    const pathText = cells.length > 0 ? cells[cells.length - 1] : '';
+    const realPath = displayPathToRealPath(pathText, root);
+
+    if (realPath === null) {
+      addIssue(
+        issues,
+        idx,
+        activeHeading,
+        '文件路径未使用 path_display_root 格式。',
+        `路径应使用 /${basename(root)}/<relative/path>。`,
+      );
+      return;
+    }
+
+    if (!existsSync(realPath)) {
+      addIssue(issues, idx, activeHeading, '文件路径不存在。', '删除该行，或替换为真实存在的文件路径。');
+    } else if (!isFile(realPath)) {
+      addIssue(
+        issues,
+        idx,
+        activeHeading,
+        '文件路径不是文件。',
+        '文件路径不能指向目录；删除该行，或替换为具体文件。',
+      );
+    }
+  });
+}
+
+function collectNoneLineIssues(lines, issues) {
+  lines.forEach((line, i) => {
+    const idx = i + 1;
+    const stripped = line.trim();
+
+    if (stripped === '关联数据实体：None') {
+      addIssue(issues, idx, '### 数据库表', '关联数据实体为 None。', '删除该行。');
+    }
+
+    if (stripped === '表依赖关系：None') {
+      addIssue(issues, idx, '### 数据库表', '表依赖关系为 None。', '删除该行。');
+    }
+  });
+}
+
+function nextNonEmptyLine(lines, startIdx) {
+  for (let idx = startIdx + 1; idx < lines.length; idx++) {
+    if (lines[idx].trim()) {
+      return [idx + 1, lines[idx].trim()];
+    }
+  }
+  return [null, null];
+}
+
+function collectNotInvolvedIssues(lines, issues) {
+  lines.forEach((line, idx) => {
+    const stripped = line.trim();
+
+    if (stripped === '### 数据库表') {
+      const [lineNo, value] = nextNonEmptyLine(lines, idx);
+      if (value === 'None') {
+        addIssue(issues, lineNo, '### 数据库表', '数据库表不涉及时写成了 None。', '改为“不涉及”。');
+      }
+    }
+
+    if (stripped === '### Preferences 相关键') {
+      const [lineNo, value] = nextNonEmptyLine(lines, idx);
+      if (value === 'None') {
+        addIssue(
+          issues,
+          lineNo,
+          '### Preferences 相关键',
+          'Preferences 不涉及时写成了 None。',
+          '改为“不涉及”。',
+        );
+      }
+    }
+  });
+}
+
+function writeIssueFile(issuePath, designPath, issues) {
+  const rows = [
+    `# ${basename(designPath)} 输出校验问题`,
+    '',
+    '| 序号 | 行号 | 位置 | 问题 | 建议 |',
+    '|---|---:|---|---|---|',
+  ];
+
+  issues.forEach((item, i) => {
+    rows.push(`| ${i + 1} | ${item.line} | ${item.location} | ${item.problem} | ${item.suggestion} |`);
+  });
+
+  writeFileSync(issuePath, `${rows.join('\n')}\n`, 'utf8');
+}
+
+function stem(p) {
+  const base = basename(p);
+  const dot = base.lastIndexOf('.');
+  return dot > 0 ? base.slice(0, dot) : base;
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  if (argv.length < 2) {
+    fail('缺少 target_directory 或 design_path 参数。');
+  }
+
+  const root = resolve(expanduser(argv[0]));
+  const designPath = resolve(expanduser(argv[1]));
+
+  if (!isDir(root)) {
+    fail('target_directory 不存在或不是目录。', { target_directory: root });
+  }
+
+  if (!isFile(designPath)) {
+    fail('design_path 不存在。', { design_path: designPath });
+  }
+
+  const issuePath = join(dirname(designPath), `${stem(designPath)}_issue.md`);
+
+  const text = readFileSync(designPath, 'utf8');
+  const lines = text.split(/\r\n|\r|\n/);
+
+  const issues = [];
+  collectFilePathTableIssues(lines, root, issues);
+  collectNoneLineIssues(lines, issues);
+  collectNotInvolvedIssues(lines, issues);
+
+  if (issues.length > 0) {
+    writeIssueFile(issuePath, designPath, issues);
+  } else if (existsSync(issuePath)) {
+    unlinkSync(issuePath);
+  }
+
+  emit({
+    ok: true,
+    design_path: designPath,
+    issue_path: issuePath,
+    has_issues: issues.length > 0,
+    issue_count: issues.length,
+    issues,
+  });
+}
+
+main();