@chengzhao-dev/dsh-cpp-workflow 0.3.1 → 0.5.0

package/skills/developing-cpp/scripts/checking-comments.mjs

@@ -21,7 +21,7 @@ const SOURCE_EXT = new Set([
 ])
 const HEADER_EXT = new Set(['.h', '.hh', '.hpp', '.hxx', '.h++', '.inl', '.ipp', '.tpp'])
 const SKIP_DIR = new Set([
-  '.git', '.hg', '.svn', 'build', 'out', 'node_modules', '_book', '.quarto', '.cache',
+  '.git', '.hg', '.svn', 'build', 'build-release', 'out', 'node_modules', '_book', '.quarto', '.cache',
   '.tmp', 'temp', 'third_party', 'third-party', 'external', 'vendor', 'deps', 'cmake-build-debug',
   'cmake-build-release', '.vs', '.idea',
 ])
@@ -40,7 +40,7 @@ function usage(message) {
 }
 
 function parseArgs(argv) {
-  const options = { root: undefined, width: 80, bannerWidth: 80, requireHeader: true, json: false, quiet: false }
+  const options = { root: undefined, width: 80, bannerWidth: 80, widthExplicit: false, bannerWidthExplicit: false, requireHeader: true, json: false, quiet: false }
   for (let index = 0; index < argv.length; index += 1) {
     const arg = argv[index]
     if (arg === '--root') {
@@ -48,9 +48,11 @@ function parseArgs(argv) {
       index += 1
     } else if (arg === '--width') {
       options.width = Number(argv[index + 1])
+      options.widthExplicit = true
       index += 1
     } else if (arg === '--banner-width') {
       options.bannerWidth = Number(argv[index + 1])
+      options.bannerWidthExplicit = true
       index += 1
     } else if (arg === '--no-header') {
       options.requireHeader = false
@@ -72,6 +74,18 @@ function parseArgs(argv) {
   return options
 }
 
+/** 从工程 .clang-format 读取 ColumnLimit；没有配置时返回 undefined。 */
+function readColumnLimit(root) {
+  const dir = statSync(root).isDirectory() ? root : path.dirname(root)
+  try {
+    const text = readFileSync(path.join(dir, '.clang-format'), 'utf8')
+    const match = text.match(/^\s*ColumnLimit:\s*(\d+)\s*$/m)
+    return match ? Number(match[1]) : undefined
+  } catch {
+    return undefined
+  }
+}
+
 /** 中文按两列计宽，用于判断渲染后的行宽。 */
 export function displayWidth(text) {
   let width = 0
@@ -225,6 +239,18 @@ export function checkText(text, options = {}) {
     }
   }
 
+  for (let index = 0; index + 1 < lines.length; index += 1) {
+    const trimmed = lines[index].trim()
+    if (!trimmed.startsWith('//') || trimmed.startsWith('///') || trimmed.startsWith('//!')) continue
+    const next = lines[index + 1].trim()
+    if (next === '' || next.startsWith('//')) continue
+    if (!/(下标|存储|对应坐标|行优先)/.test(trimmed)) continue
+    const identifiers = next.match(/[A-Za-z_]\w*/g) ?? []
+    if (identifiers.some((identifier) => trimmed.includes(identifier))) {
+      add(index + 1, 'restates-next', '实现注释在复述下一行声明或存储细节：删掉这句，让声明自己表达')
+    }
+  }
+
   for (let index = 0; index < lines.length; index += 1) {
     const trimmed = lines[index].trim()
     if (!/^(template\s*<[^>]*>\s*)?enum\b/.test(trimmed)) continue
@@ -249,6 +275,30 @@ export function checkText(text, options = {}) {
     index = body
   }
 
+  for (let index = 0; index < lines.length; index += 1) {
+    const trimmed = lines[index].trim()
+    if (trimmed.startsWith('//') || trimmed.startsWith('///') || !/\bnoexcept\b/.test(trimmed)) continue
+    let bodyStart = index
+    if (!trimmed.includes('{')) {
+      let next = index + 1
+      while (next < lines.length && lines[next].trim() === '') next += 1
+      if (next >= lines.length || !lines[next].trim().startsWith('{')) continue
+      bodyStart = next
+    }
+    const afterBrace = trimmed.slice(trimmed.indexOf('{') + 1)
+    if (afterBrace.includes('.at(')) {
+      add(index + 1, 'noexcept-throws', 'noexcept 函数体内调用 at()：越界会抛 std::out_of_range，去掉 noexcept 或改用 [] 与显式越界检查')
+      continue
+    }
+    for (let cursor = bodyStart + 1; cursor < lines.length; cursor += 1) {
+      if (/^\}/.test(lines[cursor])) break
+      if (lines[cursor].includes('.at(')) {
+        add(cursor + 1, 'noexcept-throws', 'noexcept 函数体内调用 at()：越界会抛 std::out_of_range，去掉 noexcept 或改用 [] 与显式越界检查')
+        break
+      }
+    }
+  }
+
   return issues.sort((left, right) => left.line - right.line)
 }
 
@@ -280,6 +330,11 @@ function main(argv) {
   }
   if (options.help) return usage()
   const root = options.root ? path.resolve(options.root) : process.cwd()
+  const columnLimit = readColumnLimit(root)
+  if (columnLimit !== undefined) {
+    if (!options.widthExplicit) options.width = columnLimit
+    if (!options.bannerWidthExplicit) options.bannerWidth = columnLimit
+  }
   let files
   try {
     files = collectFiles(root)

package/skills/developing-cpp/steps/03-declaration.md

@@ -12,8 +12,8 @@
 - 公共头文件自包含：自身需要的头都直接包含，不依赖调用方的包含顺序。
 - 单参数构造函数写 `explicit`；可查询的成员函数加 `[[nodiscard]]`；默认成员初始化写在声明处，不在构造函数里重复。
 - 头文件只就地定义大约 10 行以内的短函数；更长或需要完整定义的普通函数只在 `.cpp` 定义，模板和 `constexpr` 例外。
-- 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型。判据见 `references/exceptions.md`。
-- 声明注释按 `references/comments.md` 分四层写：文件头的范围与边界、类型注释的概念与使用约定、函数注释的承诺与契约、数据成员的行尾说明。类型注释不罗列成员功能、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
+- 失败是调用方的正常结果时，用结果类型、`bool` + 输出参数或 `std::optional` 表达；函数无法完成自己的任务、或构造函数无法建立 invariant 时，才在声明注释里写清抛出的异常类型；越界用 `std::out_of_range`，前置条件被破坏用 `std::logic_error`，只有调用方必须区分时才新增派生类型；Debug/Release 的抛出条件相同。判据见 `references/exceptions.md`。
+- 声明注释按 `references/comments.md` 分四层写：文件头的范围与边界、类型注释的结果/限制与约定、函数注释的第一句结果或失败方式与契约、数据成员的行尾说明。类型注释不罗列成员功能、不写方案对比与设计论证；全项目的风格理由写进项目文档，不写进注释。
 - `std::format` 用于组合消息；声明里不要承诺 `std::print`（C++23）。
 
 ## 情况
@@ -22,7 +22,7 @@
 
 **改公共接口**：先找所有调用方；改签名、改返回类型、改异常声明都算破坏性变更。能加默认参数或重载时优先加，不要静默改变旧调用的含义。
 
-**异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `TaskIndexError`」这样的具体类型，不要只写「可能抛异常」，也不要机械地写成 `std::invalid_argument` / `std::out_of_range`。类型选择见 `references/exceptions.md`。
+**异常声明**：构造函数、`Get` 类查询、解析函数最容易抛；在声明注释里写「当……时抛出 `std::out_of_range`」这样的具体类型，不要只写「可能抛异常」，也不要给每个参数错误都新建类型。类型选择见 `references/exceptions.md`。
 
 **注释**：声明注释用 `///` 写中文散文，只写调用方需要知道的；实现细节留给 `.cpp`。`@param`、`@return`、`@throws` 要么全写要么全不写，标识符和标签保持英文。写完运行 `node "<skill-dir>/scripts/checking-comments.mjs" --root <项目根>`，横幅、标签、参数完整性、成员清单与设计论证由脚本兜底。文件头、章节横幅和 TODO 的格式见 `references/comments.md`。
 

package/skills/developing-cpp/steps/04-implementation.md

@@ -9,8 +9,9 @@
 - 函数保持短小；一个函数只做一件事。超过约 40 行时先找可以命名的中间步骤，不要用注释把长函数切成几段。
 - 按「准备 → 操作 → 收尾」排列语句，用空行分组；组与组之间的空行表达阶段，不用大段叙述。
 - `.cpp` 的第一个 include 是自己的配对头，然后直接包含本文件用到的标准库头；不要依赖公共头替本文件转发声明。包含顺序见 `references/google-cpp-style.md`；文件槽位见 `references/file-template.md`。
-- 实现注释只写「为什么这样做」「这里的边界条件」「这样排序的代价」，1–3 行，放语句上方；不复述代码，不在 `if` 与 `else` 之间挂注释，记录变更史的内容留给提交说明。
-- 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。
+- `.cpp` 的函数体默认不写注释：契约在头文件的 `///` 里。只有删掉会让下一次修改得到错误结果、而代码本身看不出的地方才写一句（次序依赖、类型收窄、解析失败整行丢弃、共享方式），写在被解释语句上方，不复述代码，记录变更史的内容留给提交说明。
+- 错误处理：失败是调用方正常结果时返回结果类型、`bool` 或 `std::optional`；函数无法完成自己的任务时抛异常，不拿异常做正常分支。Debug 与 Release 用同一套返回值与抛出条件，只有诊断详略不同。两种模式都要守的 invariant 用 `Check`（项目保留时），只在开发期做的自检用 `DebugCheck`；没有这两个宏就分别用 `assert` 与 `std::terminate`。捕获时按 `const` 引用，只处理能处理的类型，其余继续抛。
+- 声明 `noexcept` 前核对函数体：出现 `at()` 或其他可能抛出的调用就去掉。越界用 `at()` 抛 `std::out_of_range`，这个函数就不能标 `noexcept`。
 - 组合输出用 `std::format`，再写入 `std::cout` / `std::cerr`；不要在库实现里直接打印。C++23 且库支持时程序边界可用 `std::print`，C++20 及更早没有。
 - 不写 C 风格强制转换；用 `static_cast` / `std::bit_cast` 等具名转换。
 - 所有权用 `std::unique_ptr`；没有共享所有权的理由时不用 `std::shared_ptr`。
@@ -24,7 +25,7 @@
 
 **重构**：一次只动一种东西（改名、抽函数、换容器）。每步都让测试保持绿色；行为句不变。
 
-**异常边界**：库内部让异常向上传播；程序入口捕获 `std::exception`，用 `std::format("错误: {}", error.what())` 打印，返回项目约定的非零退出码。不要吞掉异常后继续用无效状态。
+**异常边界**：库内部让异常向上传播；程序入口捕获 `std::exception`（或项目自己的异常基类），用 `std::format("错误: {}", error.what())` 打印，返回项目约定的非零退出码。不要吞掉异常后继续用无效状态。
 
 ## 交回构建
 

package/skills/building-cpp/assets/cmake/applying-warnings.cmake

@@ -1,10 +0,0 @@
-# 给一个 target 施加团队警告；不污染全局 CMAKE_CXX_FLAGS。
-function(cpp_workflow_apply_warnings target)
-  target_compile_options(${target} PRIVATE
-    -Wall
-    -Wextra
-    -Werror
-    -Wold-style-cast
-    -Wshadow
-  )
-endfunction()

package/skills/building-cpp/assets/cmake/fetching-googletest.cmake

@@ -1,15 +0,0 @@
-# 固定版本拉取 GoogleTest；只在 tests/ 需要时调用。
-include(FetchContent)
-
-function(cpp_workflow_fetch_googletest)
-  if(POLICY CMP0135)
-    cmake_policy(SET CMP0135 NEW)
-  endif()
-  FetchContent_Declare(
-    googletest
-    URL https://codeload.github.com/google/googletest/tar.gz/refs/tags/v1.17.0
-    URL_HASH SHA256=65fab701d9829d38cb77c14acdc431d2108bfdbf8979e40eb8ae567edf10b27c
-  )
-  set(gtest_force_shared_crt ON CACHE BOOL "" FORCE)
-  FetchContent_MakeAvailable(googletest)
-endfunction()

package/skills/building-cpp/assets/cmake/setting-rpath.cmake

@@ -1,8 +0,0 @@
-# 让构建目录里的程序直接找到同目录的共享库；安装规则另配。
-function(cpp_workflow_set_build_rpath target)
-  if(APPLE)
-    set_target_properties(${target} PROPERTIES BUILD_RPATH "@loader_path/../lib")
-  else()
-    set_target_properties(${target} PROPERTIES BUILD_RPATH "$ORIGIN/../lib")
-  endif()
-endfunction()