@miniidealab/openlogos 0.5.0 → 0.5.3

package/spec/logos.config.schema.json

@@ -0,0 +1,147 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "https://openlogos.ai/schemas/logos.config.json",
+  "title": "OpenLogos Project Configuration",
+  "description": "logos.config.json 是 OpenLogos 项目的核心配置文件（位于 logos/ 目录下），定义项目的基本信息和文档模块结构。",
+  "type": "object",
+  "required": ["name", "documents"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "项目名称"
+    },
+    "description": {
+      "type": "string",
+      "description": "项目描述"
+    },
+    "maxOpenTabs": {
+      "type": "integer",
+      "minimum": 1,
+      "default": 20,
+      "description": "RunLogos 中最大打开标签页数（仅 RunLogos 使用）"
+    },
+    "modules": {
+      "type": "array",
+      "description": "代码模块定义（保留字段，供 RunLogos 使用）",
+      "items": {
+        "type": "object"
+      }
+    },
+    "fileModules": {
+      "type": "object",
+      "description": "文件级模块映射（保留字段，供 RunLogos 使用）"
+    },
+    "locale": {
+      "type": "string",
+      "enum": ["en", "zh"],
+      "default": "en",
+      "description": "CLI and RunLogos display language"
+    },
+    "documents": {
+      "type": "object",
+      "description": "文档模块定义。每个 key 是模块标识符，value 定义模块的标签、路径和文件匹配模式。",
+      "additionalProperties": {
+        "$ref": "#/definitions/DocumentModule"
+      }
+    },
+    "verify": {
+      "type": "object",
+      "description": "测试验收配置（可选）。配置 openlogos verify 的行为。",
+      "properties": {
+        "result_path": {
+          "type": "string",
+          "default": "logos/resources/verify/test-results.jsonl",
+          "description": "测试结果 JSONL 文件路径（相对项目根目录）"
+        },
+        "test_command": {
+          "type": "string",
+          "description": "测试命令（可选）。配置后 openlogos verify 会先执行此命令再读取结果"
+        }
+      }
+    }
+  },
+  "definitions": {
+    "DocumentModule": {
+      "type": "object",
+      "required": ["label", "path", "pattern"],
+      "properties": {
+        "label": {
+          "$ref": "#/definitions/I18nLabel",
+          "description": "模块显示名称（支持多语言）"
+        },
+        "path": {
+          "type": "string",
+          "description": "模块根目录的相对路径（相对于 logos.config.json 所在目录）"
+        },
+        "pattern": {
+          "type": "string",
+          "description": "文件匹配的 glob 模式"
+        }
+      }
+    },
+    "I18nLabel": {
+      "type": "object",
+      "required": ["en"],
+      "properties": {
+        "en": {
+          "type": "string",
+          "description": "英文标签"
+        },
+        "zh": {
+          "type": "string",
+          "description": "中文标签"
+        }
+      },
+      "additionalProperties": {
+        "type": "string"
+      }
+    }
+  },
+  "examples": [
+    {
+      "name": "My SaaS Project",
+      "description": "A SaaS product following OpenLogos methodology",
+      "locale": "en",
+      "documents": {
+        "prd": {
+          "label": { "en": "Product Docs", "zh": "产品文档" },
+          "path": "./resources/prd",
+          "pattern": "**/*.{md,html,htm,pdf}"
+        },
+        "api": {
+          "label": { "en": "API Docs", "zh": "API 文档" },
+          "path": "./resources/api",
+          "pattern": "**/*.{yaml,yml,json}"
+        },
+        "test": {
+          "label": { "en": "Test Cases", "zh": "测试用例" },
+          "path": "./resources/test",
+          "pattern": "**/*.md"
+        },
+        "scenario": {
+          "label": { "en": "Scenarios", "zh": "业务场景" },
+          "path": "./resources/scenario",
+          "pattern": "**/*.json"
+        },
+        "database": {
+          "label": { "en": "Database", "zh": "数据库" },
+          "path": "./resources/database",
+          "pattern": "**/*.sql"
+        },
+        "verify": {
+          "label": { "en": "Verify Reports", "zh": "验收报告" },
+          "path": "./resources/verify",
+          "pattern": "**/*.{jsonl,md}"
+        },
+        "changes": {
+          "label": { "en": "Change Proposals", "zh": "变更提案" },
+          "path": "./changes",
+          "pattern": "**/*.{md,json}"
+        }
+      },
+      "verify": {
+        "result_path": "logos/resources/verify/test-results.jsonl"
+      }
+    }
+  ]
+}

package/spec/sql-comment-convention.md

@@ -0,0 +1,225 @@
+# SQLite 结构化注释规范
+
+> 版本：0.1.0
+>
+> 本文档定义 OpenLogos 项目中 SQLite DDL 的结构化注释格式。AI 在生成 SQLite `schema.sql` 时必须遵循此格式输出表注释和字段注释，使其可被 `parseSqlComments()` 等工具链解析。
+
+## 概述
+
+PostgreSQL 和 MySQL 提供原生的注释语法（`COMMENT ON` / `COMMENT`），但 SQLite 不支持任何形式的元数据注释。OpenLogos 定义了一套基于 SQL 行注释（`--`）的结构化约定，让 SQLite DDL 具备等价的元数据表达能力：
+
+- **`-- @comment`**：字段注释，放在字段定义行的紧邻上方
+- **`-- @table-comment`**：表注释，放在 `CREATE TABLE` 语句的紧邻下方
+
+这套约定对标准 SQL 工具完全透明（只是普通注释），不影响 SQLite 执行。
+
+## 适用范围
+
+仅当 `logos-project.yaml` 的 `tech_stack.database` 为 **SQLite** 时激活此约定。PostgreSQL 和 MySQL 项目继续使用各自的原生注释语法。
+
+## 字段注释：`-- @comment`
+
+### 语法
+
+```sql
+-- @comment <描述文本>
+<字段定义行>
+```
+
+### 规则
+
+1. `-- @comment` 行必须**紧邻**目标字段定义行的上方
+2. `-- @comment` 与字段定义之间**不允许空行**（空行会断开关联）
+3. 多行注释：连续多个 `-- @comment` 行会自动拼接为一条注释（以空格连接）
+4. 约束行（`FOREIGN KEY`、独立 `CHECK`、独立 `UNIQUE`）**不需要也不消费** `-- @comment`
+
+### 示例
+
+单行注释：
+
+```sql
+-- @comment 用户唯一标识，UUID v4 字符串
+id TEXT PRIMARY KEY NOT NULL,
+```
+
+多行注释（自动拼接）：
+
+```sql
+-- @comment 账户余额，单位：分 [USD cents]
+-- @comment 禁止使用 DECIMAL/FLOAT 存储金额
+balance INTEGER NOT NULL DEFAULT 0,
+```
+
+解析结果：`"账户余额，单位：分 [USD cents] 禁止使用 DECIMAL/FLOAT 存储金额"`
+
+### 不需要注释的行
+
+以下行不应添加 `-- @comment`，解析器也不会将 `-- @comment` 关联到它们：
+
+```sql
+FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
+```
+
+## 表注释：`-- @table-comment`
+
+### 语法
+
+```sql
+);
+-- @table-comment <表名> <描述文本>
+```
+
+### 规则
+
+1. `-- @table-comment` 放在 `CREATE TABLE ... ();` 语句的**紧邻下方**
+2. `<表名>` 必须与 `CREATE TABLE` 中的表名完全一致
+3. `<表名>` 与 `<描述文本>` 之间用空格分隔，第一个空格之后的所有内容为描述
+
+### 示例
+
+```sql
+CREATE TABLE users (
+  -- @comment 用户唯一标识
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 用户邮箱
+  email TEXT NOT NULL UNIQUE
+);
+-- @table-comment users 用户基础信息表，存储核心用户数据
+```
+
+## 完整示例
+
+```sql
+-- TaskFlow v0.1 — SQLite DDL
+-- 方言：SQLite 3；连接须开启 PRAGMA foreign_keys = ON;
+-- 生成日期：2026-04-07
+
+-- ---------------------------------------------------------------------------
+-- users（来源：auth.yaml → register, login）
+-- ---------------------------------------------------------------------------
+CREATE TABLE users (
+  -- @comment 用户唯一标识，UUID v4 字符串
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 用户邮箱，已归一化为小写
+  email TEXT NOT NULL UNIQUE,
+  -- @comment Argon2id 密码哈希，仅存哈希
+  password_hash TEXT NOT NULL,
+  -- @comment 创建时间，ISO 8601 格式
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment 最后更新时间
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+);
+-- @table-comment users 用户表，存储注册用户的核心信息
+
+CREATE INDEX idx_users_email ON users (email);
+
+-- ---------------------------------------------------------------------------
+-- tasks（来源：tasks.yaml → create, list, get, update, delete）
+-- ---------------------------------------------------------------------------
+CREATE TABLE tasks (
+  -- @comment 任务唯一标识
+  id TEXT PRIMARY KEY NOT NULL,
+  -- @comment 任务归属用户 ID
+  user_id TEXT NOT NULL,
+  -- @comment 任务标题
+  title TEXT NOT NULL,
+  -- @comment 任务详细描述，可为空
+  description TEXT,
+  -- @comment 任务状态：todo / in_progress / done
+  status TEXT NOT NULL DEFAULT 'todo' CHECK (status IN ('todo', 'in_progress', 'done')),
+  -- @comment 任务优先级：low / medium / high
+  priority TEXT NOT NULL DEFAULT 'medium' CHECK (priority IN ('low', 'medium', 'high')),
+  -- @comment 创建时间
+  created_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  -- @comment 最后更新时间
+  updated_at TEXT NOT NULL DEFAULT (strftime('%Y-%m-%dT%H:%M:%fZ', 'now')),
+  FOREIGN KEY (user_id) REFERENCES users (id) ON DELETE CASCADE
+);
+-- @table-comment tasks 任务表，存储用户创建的所有任务
+
+CREATE INDEX idx_tasks_user_status ON tasks (user_id, status);
+CREATE INDEX idx_tasks_user_updated ON tasks (user_id, updated_at);
+```
+
+## 解析算法
+
+解析器逐行扫描 SQL 文件，维护以下状态：
+
+- `currentTable: string | null` — 当前所在的 `CREATE TABLE` 上下文
+- `pendingComment: string[]` — 待关联的注释缓冲区
+
+### 伪代码
+
+```
+for each line in file:
+  trimmed = line.trim()
+
+  if trimmed starts with "-- @table-comment ":
+    extract tableName and description
+    associate description with tableName
+    continue
+
+  if trimmed starts with "-- @comment ":
+    extract text after "-- @comment "
+    append to pendingComment
+    continue
+
+  if trimmed is empty:
+    clear pendingComment
+    continue
+
+  if trimmed matches /^CREATE TABLE\s+(\w+)/i:
+    set currentTable to captured name
+    clear pendingComment (table-level comment uses @table-comment)
+    continue
+
+  if currentTable is set AND trimmed is a column definition:
+    extract columnName (first word-like token)
+    if pendingComment is not empty:
+      associate joined pendingComment with currentTable.columnName
+      clear pendingComment
+    add column to currentTable's column list
+
+  if trimmed starts with ")":
+    clear currentTable
+    clear pendingComment
+```
+
+### 列定义识别
+
+一行被视为列定义，当且仅当：
+1. 当前在 `CREATE TABLE` 块内（`currentTable` 不为 `null`）
+2. 该行**不是**以 `FOREIGN KEY`、`CHECK`、`UNIQUE`、`PRIMARY KEY`（独立约束）、`CONSTRAINT` 开头（不区分大小写）
+3. 该行**不是** `)`（表结束行）
+4. 该行**不是** `--` 开头的注释行
+
+列名提取：取该行第一个匹配 `/^\s*["']?(\w+)["']?/` 的标识符。
+
+## 输出数据结构
+
+```typescript
+interface SchemaMetadata {
+  tables: TableMeta[];
+}
+
+interface TableMeta {
+  name: string;
+  comment?: string;
+  columns: ColumnMeta[];
+}
+
+interface ColumnMeta {
+  name: string;
+  comment?: string;
+}
+```
+
+## 与其他方言的关系
+
+| 数据库 | 表注释 | 字段注释 |
+|--------|--------|---------|
+| PostgreSQL | `COMMENT ON TABLE t IS '...'` | `COMMENT ON COLUMN t.c IS '...'` |
+| MySQL | `CREATE TABLE t (...) COMMENT = '...'` | `col TYPE COMMENT '...'` |
+| **SQLite** | **`-- @table-comment t 描述`** | **`-- @comment 描述`** |
+
+OpenLogos 的 `db-designer` Skill 会根据 `tech_stack.database` 自动选择正确的注释方式。工具链中的 `parseSqlComments()` 函数专门解析 SQLite 的 `@comment` / `@table-comment` 标记。

package/spec/test-results.md

@@ -0,0 +1,255 @@
+# 测试结果格式规范
+
+> 版本：0.1.0
+>
+> 本文档定义 OpenLogos 的标准化测试结果输出格式。AI 在生成测试代码时必须内嵌 reporter，按此格式输出每个用例的运行结果，供 `openlogos verify` 读取和验收。
+
+## 概述
+
+OpenLogos 不绑定任何测试框架。取而代之的做法是：**AI 在生成测试代码时内嵌一个小型 reporter**，测试运行后自动将每个用例的结果追加写入统一格式的文件。`openlogos verify` 命令只需读取该文件即可完成验收判定。
+
+这套机制的核心优势：
+
+- **零框架依赖**：vitest、jest、pytest、go test、cargo test 均可产出同一格式
+- **零适配成本**：`openlogos verify` 只解析一种格式
+- **AI 天然能做**：reporter 代码不超过 20 行，AI 在生成测试代码时顺手写入
+- **用例 ID 是原生的**：不需要从测试名称里正则提取，ID 直接是数据字段
+
+## 文件路径
+
+测试结果文件的默认路径为：
+
+```
+logos/resources/verify/test-results.jsonl
+```
+
+可通过 `logos.config.json` 的 `verify.result_path` 字段自定义路径。
+
+## 格式：JSONL
+
+文件格式为 **JSONL**（JSON Lines）——每行一个独立的 JSON 对象，以换行符分隔。
+
+选择 JSONL 而非完整 JSON 数组的理由：
+
+| 特性 | JSONL | JSON 数组 |
+|------|-------|----------|
+| 追加写入 | 直接 append 一行 | 需维护数组闭合括号 |
+| 流式读取 | 逐行解析 | 需读完整个文件 |
+| 部分损坏 | 一行损坏不影响其他行 | 括号不匹配则整个文件不可解析 |
+| 跨语言写入 | `JSON.stringify(obj) + "\n"` | 需手动管理逗号和括号 |
+
+## 字段定义
+
+每行是一个 JSON 对象，包含以下字段：
+
+| 字段 | 类型 | 必需 | 说明 |
+|------|------|------|------|
+| `id` | string | 是 | 用例 ID，与 `test-cases.md` 中的 `UT-xx` / `ST-xx` 完全一致 |
+| `status` | `"pass"` \| `"fail"` \| `"skip"` | 是 | 运行结果 |
+| `duration_ms` | number | 否 | 执行耗时（毫秒） |
+| `timestamp` | string (ISO 8601) | 否 | 执行时间，如 `2026-04-03T15:30:01Z` |
+| `error` | string | `status=fail` 时必需 | 失败原因（断言错误信息） |
+| `scenario` | string | 否 | 场景编号（如 `S01`），用于验证 ID 前缀一致性 |
+
+### 示例
+
+```jsonl
+{"id":"UT-S01-01","status":"pass","duration_ms":12,"timestamp":"2026-04-03T15:30:01Z"}
+{"id":"UT-S01-02","status":"fail","duration_ms":45,"timestamp":"2026-04-03T15:30:01Z","error":"Expected exit code 0, got 1"}
+{"id":"UT-S01-03","status":"skip","timestamp":"2026-04-03T15:30:01Z"}
+{"id":"ST-S01-01","status":"pass","duration_ms":230,"timestamp":"2026-04-03T15:30:02Z","scenario":"S01"}
+```
+
+### 字段约束
+
+- `id` 必须匹配正则 `^(UT|ST)-S\d{2}-\d{2,3}$`
+- `status` 仅允许三个值：`pass`、`fail`、`skip`
+- `error` 在 `status=fail` 时必须提供，其他状态可省略
+- 同一个 `id` 如果出现多次（如重试），`openlogos verify` 取**最后一次**的结果
+
+## 运行约定
+
+### 清空策略
+
+每次完整测试运行前，reporter 应**清空**（truncate）结果文件，确保文件只包含最近一次运行的结果。推荐方式：
+
+- 在测试套件的 `globalSetup` 或等效钩子中清空文件
+- 或者 reporter 的初始化阶段写入空文件
+
+### 目录创建
+
+reporter 在写入前应确保 `logos/resources/verify/` 目录存在（`mkdir -p` 等效操作）。
+
+## AI 生成 reporter 代码模板
+
+以下是各语言的 reporter 参考实现。AI 在 Phase 3 Step 4（代码生成）时，应根据项目的 `tech_stack` 选择对应语言的模板，嵌入到测试代码中。
+
+### TypeScript (vitest / jest)
+
+````typescript
+import { appendFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { dirname } from 'node:path';
+
+const RESULT_PATH = 'logos/resources/verify/test-results.jsonl';
+let initialized = false;
+
+function reportResult(
+  id: string,
+  status: 'pass' | 'fail' | 'skip',
+  error?: string,
+  durationMs?: number,
+) {
+  if (!initialized) {
+    mkdirSync(dirname(RESULT_PATH), { recursive: true });
+    writeFileSync(RESULT_PATH, '');
+    initialized = true;
+  }
+  const record: Record<string, unknown> = {
+    id,
+    status,
+    timestamp: new Date().toISOString(),
+  };
+  if (durationMs !== undefined) record.duration_ms = durationMs;
+  if (error) record.error = error;
+  appendFileSync(RESULT_PATH, JSON.stringify(record) + '\n');
+}
+````
+
+在测试用例中使用：
+
+````typescript
+import { describe, it, expect } from 'vitest';
+
+describe('S01: CLI Init', () => {
+  it('UT-S01-01: should detect project name from package.json', () => {
+    const start = Date.now();
+    try {
+      const result = detectProjectName('/path/to/project');
+      expect(result.name).toBe('my-project');
+      reportResult('UT-S01-01', 'pass', undefined, Date.now() - start);
+    } catch (e) {
+      reportResult('UT-S01-01', 'fail', String(e), Date.now() - start);
+      throw e;
+    }
+  });
+});
+````
+
+### Python (pytest)
+
+````python
+# conftest.py
+import json
+import os
+import time
+import re
+import pytest
+
+RESULT_PATH = "logos/resources/verify/test-results.jsonl"
+_initialized = False
+
+
+def _ensure_file():
+    global _initialized
+    if not _initialized:
+        os.makedirs(os.path.dirname(RESULT_PATH), exist_ok=True)
+        open(RESULT_PATH, "w").close()
+        _initialized = True
+
+
+def _extract_test_id(nodeid: str) -> str | None:
+    """Extract UT-S01-01 or ST-S01-01 from test function name."""
+    match = re.search(r"(UT|ST)_S\d{2}_\d{2,3}", nodeid)
+    if match:
+        return match.group().replace("_", "-")
+    return None
+
+
+@pytest.hookimpl(tryfirst=True, hookwrapper=True)
+def pytest_runtest_makereport(item, call):
+    outcome = yield
+    report = outcome.get_result()
+    if report.when == "call":
+        _ensure_file()
+        test_id = _extract_test_id(item.nodeid)
+        if not test_id:
+            return
+        record = {
+            "id": test_id,
+            "status": "pass" if report.passed else "fail",
+            "duration_ms": round(report.duration * 1000),
+            "timestamp": time.strftime("%Y-%m-%dT%H:%M:%SZ", time.gmtime()),
+        }
+        if report.failed:
+            record["error"] = str(report.longrepr)[:500]
+        with open(RESULT_PATH, "a") as f:
+            f.write(json.dumps(record) + "\n")
+````
+
+Python 测试函数命名约定——用下划线替代连字符：
+
+````python
+def test_UT_S01_01_detect_project_name():
+    result = detect_project_name("/path/to/project")
+    assert result["name"] == "my-project"
+````
+
+### Go
+
+````go
+package testutil
+
+import (
+	"encoding/json"
+	"fmt"
+	"os"
+	"path/filepath"
+	"sync"
+	"time"
+)
+
+const ResultPath = "logos/resources/verify/test-results.jsonl"
+
+var (
+	once sync.Once
+	mu   sync.Mutex
+)
+
+type TestResult struct {
+	ID         string `json:"id"`
+	Status     string `json:"status"`
+	DurationMs int64  `json:"duration_ms,omitempty"`
+	Timestamp  string `json:"timestamp"`
+	Error      string `json:"error,omitempty"`
+}
+
+func ReportResult(id, status string, durationMs int64, err string) {
+	once.Do(func() {
+		os.MkdirAll(filepath.Dir(ResultPath), 0o755)
+		os.WriteFile(ResultPath, nil, 0o644)
+	})
+	r := TestResult{
+		ID:         id,
+		Status:     status,
+		DurationMs: durationMs,
+		Timestamp:  time.Now().UTC().Format(time.RFC3339),
+		Error:      err,
+	}
+	b, _ := json.Marshal(r)
+	mu.Lock()
+	defer mu.Unlock()
+	f, _ := os.OpenFile(ResultPath, os.O_APPEND|os.O_WRONLY|os.O_CREATE, 0o644)
+	defer f.Close()
+	fmt.Fprintf(f, "%s\n", b)
+}
+````
+
+## 与其他规范的关系
+
+| 规范 | 关系 |
+|------|------|
+| `test-writer` Skill | 定义用例 ID（`UT-xx` / `ST-xx`），是 JSONL 中 `id` 字段的来源 |
+| `test-orchestrator` Skill | API 编排测试也可产出同格式 JSONL |
+| `directory-convention.md` | 定义 `logos/resources/verify/` 目录位置 |
+| `logos.config.json` | `verify.result_path` 可覆盖默认路径 |
+| `openlogos verify` 命令 | 读取此格式文件，生成验收报告 |