@bovinphang/craft-common 1.0.0 → 2.0.0

package/localized/zh-CN/skills/cc-typescript-project-standard/references/common/engineering-practices.sources.json

@@ -0,0 +1,377 @@
+{
+  "schemaVersion": 1,
+  "sources": [
+    {
+      "id": "google-review",
+      "publisher": "Google",
+      "title": "Code review standard",
+      "url": "https://google.github.io/eng-practices/review/reviewer/standard.html",
+      "section": "Engineering principles and code health",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guidance; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Use evidence and project standards; personal preference alone is not a blocker."
+    },
+    {
+      "id": "ms-playbook",
+      "publisher": "Microsoft ISE",
+      "title": "Test planning",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/test-planning/",
+      "section": "Risk, test scope and responsibilities",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Team practice, not a company-wide mandate; retain existing tools."
+    },
+    {
+      "id": "ms-faults",
+      "publisher": "Microsoft ISE",
+      "title": "Fault injection testing",
+      "url": "https://microsoft.github.io/code-with-engineering-playbook/automated-testing/fault-injection-testing/",
+      "section": "Controlled failure and observations",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living ISE playbook; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Run scoped, controlled failures; do not infer production reliability from a small example."
+    },
+    {
+      "id": "google-ts",
+      "publisher": "Google",
+      "title": "TS/JS style guide",
+      "url": "https://google.github.io/styleguide/tsguide.html",
+      "section": "Environment caveat; types and exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Google explicitly notes internal constraints differ; no blanket ban overriding a justified project convention."
+    },
+    {
+      "id": "typescript-publishing",
+      "publisher": "TypeScript",
+      "title": "Publishing declaration files",
+      "url": "https://www.typescriptlang.org/docs/handbook/declaration-files/publishing.html",
+      "section": "Types and declaration dependencies",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living handbook; check installed compiler/module resolution",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Validate the actual packed consumer; do not upgrade compiler or module mode on this basis."
+    },
+    {
+      "id": "rust-api",
+      "publisher": "Rust library team",
+      "title": "Rust API Guidelines",
+      "url": "https://rust-lang.github.io/api-guidelines/",
+      "section": "Type safety, dependability and future proofing",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living recommendations; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Guidance rather than language law; preserve edition and MSRV."
+    },
+    {
+      "id": "tokio-join",
+      "publisher": "Tokio project",
+      "title": "JoinHandle",
+      "url": "https://docs.rs/tokio/latest/tokio/task/struct.JoinHandle.html",
+      "section": "Drop, abort and completion",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 1.54.1; project runtime/version determines applicability",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Tokio-specific mechanics only when Tokio is already used; no new runtime dependency."
+    },
+    {
+      "id": "uber-go",
+      "publisher": "Uber",
+      "title": "Go Style Guide",
+      "url": "https://github.com/uber-go/guide/blob/master/style.md",
+      "section": "Errors, interfaces and goroutine lifetime",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living master; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not import Uber dependencies or turn buffer-size style into a correctness theorem."
+    },
+    {
+      "id": "go-context",
+      "publisher": "Go project",
+      "title": "context package",
+      "url": "https://pkg.go.dev/context",
+      "section": "Cancellation propagation and ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Standard library; check owning go.mod/toolchain",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A cancellation signal alone does not confirm worker exit."
+    },
+    {
+      "id": "google-java",
+      "publisher": "Google",
+      "title": "Java Style Guide",
+      "url": "https://google.github.io/styleguide/javaguide.html",
+      "section": "Source structure and exception handling",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public style; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Naming/layout follows local standard; style is distinct from runtime correctness."
+    },
+    {
+      "id": "oracle-resources",
+      "publisher": "Oracle",
+      "title": "Try-with-resources",
+      "url": "https://docs.oracle.com/javase/tutorial/essential/exceptions/tryResourceClose.html",
+      "section": "Closing resources and suppressed exceptions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "JDK8 tutorial; not a source for newer runtime features",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Preserve primary cause and borrowed-resource ownership; check actual API contract."
+    },
+    {
+      "id": "java-executor",
+      "publisher": "Oracle",
+      "title": "ExecutorService",
+      "url": "https://docs.oracle.com/en/java/javase/17/docs/api/java.base/java/util/concurrent/ExecutorService.html",
+      "section": "Shutdown, termination and awaitTermination",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Java SE17 documentation",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Check target JDK; no automatic virtual-thread or JDK migration."
+    },
+    {
+      "id": "google-python",
+      "publisher": "Google",
+      "title": "Python Style Guide",
+      "url": "https://google.github.io/styleguide/pyguide.html",
+      "section": "Imports, exceptions and mutable state",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Keep current formatter/type checker and library responsibilities."
+    },
+    {
+      "id": "python-asyncio",
+      "publisher": "Python project",
+      "title": "Coroutines and tasks",
+      "url": "https://docs.python.org/3/library/asyncio-task.html",
+      "section": "Cancellation and task ownership",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed 3.15.2; feature availability follows project Python",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Newer TaskGroup/timeout features require a supported project version; no upgrade implied."
+    },
+    {
+      "id": "cert-c",
+      "publisher": "CMU SEI",
+      "title": "MEM00-C allocation and release",
+      "url": "https://cmu-sei.github.io/secure-coding-standards/sei-cert-c-coding-standard/recommendations/memory-management-mem/mem00-c/",
+      "section": "MEM00-C memory responsibility",
+      "checkedAt": "2026-11-08",
+      "versionScope": "2016-edition standard family; MEM00-C is a recommendation",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Do not label recommendations as mandatory CERT rules or apply C++ ownership machinery to pure C."
+    },
+    {
+      "id": "cpp-core",
+      "publisher": "C++ Core Guidelines editors",
+      "title": "C++ Core Guidelines",
+      "url": "https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines",
+      "section": "Resource and lifetime interfaces",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page dated 2026-06-14, living release0.8",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Adapt to existing exception policy and compiler; borrowing does not imply ownership."
+    },
+    {
+      "id": "google-cpp",
+      "publisher": "Google",
+      "title": "C++ Style Guide",
+      "url": "https://google.github.io/styleguide/cppguide.html",
+      "section": "Exceptions and project consistency",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living public guide; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Its exception/standard policy is not universal; preserve the owning project policy and C ABI."
+    },
+    {
+      "id": "ms-sal",
+      "publisher": "Microsoft",
+      "title": "Understanding SAL",
+      "url": "https://learn.microsoft.com/en-us/cpp/code-quality/understanding-sal?view=msvc-170",
+      "section": "Parameter preconditions and output guarantees",
+      "checkedAt": "2026-11-08",
+      "versionScope": "MSVC170 documentation view",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "SAL is an optional toolchain-specific expression, not a portable mandatory annotation."
+    },
+    {
+      "id": "aws-retry",
+      "publisher": "AWS",
+      "title": "Timeouts, retries and backoff with jitter",
+      "url": "https://aws.amazon.com/builders-library/timeouts-retries-and-backoff-with-jitter/",
+      "section": "Timeouts, bounded retries and retry amplification",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Article dated 2019-12-05; official Builder Center redirect",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Retry only semantically safe operations within a total budget; failure classes alone do not grant write replay."
+    },
+    {
+      "id": "aws-idempotency",
+      "publisher": "AWS",
+      "title": "Making retries safe with idempotent APIs",
+      "url": "https://aws.amazon.com/builders-library/making-retries-safe-with-idempotent-APIs/",
+      "section": "Caller intent, duplicate requests and atomic recording",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Builders Library; revision unknown",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "A process-local example does not establish database/multi-process exactly-once."
+    },
+    {
+      "id": "react-effects",
+      "publisher": "React project",
+      "title": "useEffect",
+      "url": "https://react.dev/reference/react/useEffect",
+      "section": "Cleanup and fetching race conditions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; use installed project API",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "Abort and stale-result checks complement each other; no React upgrade implied."
+    },
+    {
+      "id": "react-act",
+      "publisher": "React project",
+      "title": "act",
+      "url": "https://react.dev/reference/react/act",
+      "section": "Applying updates before assertions",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed React19.3; verify sample versions",
+      "licenseStatus": "unknown",
+      "adoption": "adopt",
+      "limits": "DOM simulation is not browser E2E or native desktop execution."
+    },
+    {
+      "id": "vue-watchers",
+      "publisher": "Vue project",
+      "title": "Watchers",
+      "url": "https://vuejs.org/guide/essentials/watchers.html",
+      "section": "Side-effect cleanup",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Vue3; onWatcherCleanup requires3.5+ and synchronous registration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use supported callback cleanup on older Vue3; no framework migration."
+    },
+    {
+      "id": "tauri-permissions",
+      "publisher": "Tauri project",
+      "title": "Permissions",
+      "url": "https://v2.tauri.app/security/permissions/",
+      "section": "Command allow/deny and capability scope",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Tauri2 docs; check installed version/configuration",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Rust command-unit tests do not activate webview permissions or prove packaged GUI security."
+    },
+    {
+      "id": "electron-security",
+      "publisher": "Electron project",
+      "title": "Security",
+      "url": "https://www.electronjs.org/docs/latest/tutorial/security",
+      "section": "IPC sender checks and renderer trust",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living docs; match installed Electron",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Handler tests do not prove sandbox/context isolation is active in a packaged app."
+    },
+    {
+      "id": "spring-tests",
+      "publisher": "Spring project",
+      "title": "Testing Spring Boot applications",
+      "url": "https://docs.spring.io/spring-boot/3.5/reference/testing/spring-boot-applications.html",
+      "section": "Test slices and application tests",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Boot3.5 docs observed3.5.16; preserve sample/project versions",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Test scope matters; MVC tests do not establish live DB/transaction or deployment behavior."
+    },
+    {
+      "id": "fastapi-lifespan",
+      "publisher": "FastAPI project",
+      "title": "Lifespan events",
+      "url": "https://fastapi.tiangolo.com/advanced/events/",
+      "section": "Acquire and release application resources",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living FastAPI documentation; match pinned dependencies",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Use actual lifespan execution in tests; import does not own a live connection."
+    },
+    {
+      "id": "gin-binding",
+      "publisher": "Gin project",
+      "title": "Binding",
+      "url": "https://gin-gonic.com/en/docs/binding/",
+      "section": "Binding errors and validation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living Gin documentation; match pinned module",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Writing/aborting a response does not replace explicit control-flow return in the current handler."
+    },
+    {
+      "id": "axum-extractors",
+      "publisher": "Axum project",
+      "title": "Extractors",
+      "url": "https://docs.rs/axum/latest/axum/extract/",
+      "section": "Extractor order and rejections",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Latest route observed0.8.9; fixed0.8.9 route unavailable via browser tool",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Pinned existing example is authoritative for compilation; do not assume source signatures across releases."
+    },
+    {
+      "id": "drogon-filters",
+      "publisher": "Drogon project",
+      "title": "Middleware and Filter",
+      "url": "https://github.com/drogonframework/drogon/wiki/ENG-05-Middleware-and-Filter",
+      "section": "Filter callbacks and continuation",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Living wiki; match compiled example version",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Synthetic role headers are not authentication; callback lifetime must follow actual ownership."
+    },
+    {
+      "id": "node-typescript",
+      "publisher": "Node.js project",
+      "title": "Modules: TypeScript",
+      "url": "https://nodejs.org/api/typescript.html",
+      "section": "Type-stripping history, enabling, and separate type checking",
+      "checkedAt": "2026-11-08",
+      "versionScope": "Page observed26.13.0; sample>=22.18, actual24.14.1 tested; product Node>=22 unchanged",
+      "licenseStatus": "unknown",
+      "adoption": "conditional",
+      "limits": "Native stripping is not type checking and ignores tsconfig. Missing sample capability is MISSING, not a product runtime upgrade."
+    }
+  ]
+}

package/localized/zh-CN/skills/cc-typescript-project-standard/references/engineering-practices.md

@@ -0,0 +1,106 @@
+---
+practiceCards:
+  - id: "cc-typescript-project-standard:input-validation"
+    level: "required"
+    sourceIds: ["google-ts"]
+    caseIds: ["EP-TS-01"]
+    evidence: "case"
+  - id: "cc-typescript-project-standard:async-errors"
+    level: "required"
+    sourceIds: ["google-ts","aws-idempotency"]
+    caseIds: ["EP-TS-01","EP-UI-01"]
+    evidence: "review-only"
+  - id: "cc-typescript-project-standard:package-contract"
+    level: "required"
+    sourceIds: ["typescript-publishing","google-ts"]
+    caseIds: ["EP-TS-01"]
+    evidence: "review-only"
+---
+
+# 本入口工程决策
+
+先定位项目角色、工具链及已有约定，再按需读取[公共原则](common/engineering-practices.md)。下列条件仅约束当前语言/场景；结构检查不证明全部语义或实际运行。
+
+<a id="cc-typescript-project-standard:input-validation"></a>
+## 副作用前校验外部数据
+
+级别: required
+
+### 风险
+类型断言可能把非法JSON伪装为可信领域值。
+
+### 适用
+适用于网络、IPC、文件和插件输入；已有不变量的内部值不必重复建立schema。
+
+### 决策
+接收unknown，用已有schema/类型守卫收窄，协议值转换为领域类型后才产生副作用；明确金额单位、枚举和失败输出。
+
+### 例外
+生成客户端有用，但不能校验远端实际响应；刻意信任的边界须记录可信来源。
+
+### 正反示意
+正例：字符串金额被拒绝，零副作用。反例：as Payment使扣款回调接收坏输入。
+
+### 验证
+运行本地非法/成功配对；消费项目再补空响应、非法枚举等协议场景。
+
+### 来源
+google-ts — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-TS-01; case. [本入口可运行案例](../examples/engineering/README.md)。 执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。
+
+<a id="cc-typescript-project-standard:async-errors"></a>
+## 经已负责的异步链传播失败
+
+级别: required
+
+### 风险
+漂浮异步任务和吞拒绝可能过早发布成功。
+
+### 适用
+适用于本单元创建的Promise/回调，不向通用库强加UI hook。
+
+### 决策
+返回/await所属Promise，安全保留unknown错误上下文，显式表达待处理/失败/成功；脱离任务必须有刻意指定的生命周期拥有者。
+
+### 例外
+Abort仅说明调用方结束等待，不代表远端写回滚；不确定写先核对再重试，并沿用已有错误类型。
+
+### 正反示意
+正例：已提交写超时后进入待确认。反例：catch返回空成功值或悄悄重试扣款。
+
+### 验证
+在负责单元注入拒绝和迟到完成；本地TS例只覆盖校验，UI/服务ID指向独立证据。
+
+### 来源
+google-ts, aws-idempotency — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-TS-01, EP-UI-01; review-only.  执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。
+
+<a id="cc-typescript-project-standard:package-contract"></a>
+## 在真实消费者验证声明
+
+级别: required
+
+### 风险
+工作区别名和未声明类型依赖可能在打包后消失。
+
+### 适用
+适用于库/SDK/CLI导出；仅应用内部模块不必变成发布包。
+
+### 决策
+exports、types、files、模块解析匹配已声明消费者，离开workspace验证tarball；沿用已有严格配置，改变时记录局部迁移。
+
+### 例外
+Google内部namespace/enum/断言风格有条件适用；skipLibCheck可作为依赖政策，但不能证明自身公共边界正确；exactOptionalPropertyTypes并非strict所包含。
+
+### 正反示意
+正例：归档消费者解析已声明类型依赖。反例：为了模仿指南更改所有包的模块模式。
+
+### 验证
+执行已有类型/构建及归档消费者检查；输入校验样例本身不证明声明兼容。
+
+### 来源
+typescript-publishing, google-ts — [来源与适用限制](common/engineering-practices.sources.json).
+
+证据标识: EP-TS-01; review-only.  执行状态及覆盖范围见实际记录；关联ID不证明该卡全部语义。

package/localized/zh-CN/skills/cc-typescript-project-standard/references/type-safety-patterns.md

@@ -0,0 +1,73 @@
+# 类型安全模式
+
+## 类型边界审查清单
+
+- DTO 应与外部载荷对应，并在 API 边界处进行转换。
+- 领域模型或视图模型使用前端命名和稳定的联合类型。
+- 组件 props 需命名明确，仅在该文件外复用时才导出。
+- 公开函数必须有显式的参数和返回值类型。
+- 外部输入必须从 `unknown` 开始，通过 schema 校验或类型守卫逐步收窄。
+- 配置映射表优先使用 `as const` 和 `satisfies`，避免宽泛断言。
+
+## 使用 `satisfies` 的配置映射表
+
+```ts
+type Tone = "neutral" | "success" | "warning" | "danger";
+
+const STATUS_TONE = {
+  draft: "neutral",
+  paid: "success",
+  overdue: "danger",
+} as const satisfies Record<string, Tone>;
+
+type InvoiceStatus = keyof typeof STATUS_TONE;
+```
+
+这样既保留了字面量值，又验证了映射表符合预期的值域。
+
+## 映射类型用于表单错误
+
+```ts
+type FieldErrors<TValues extends Record<string, unknown>> = {
+  [Key in keyof TValues]?: string;
+};
+
+interface ProfileFormValues {
+  email: string;
+  displayName: string;
+}
+
+type ProfileFormErrors = FieldErrors<ProfileFormValues>;
+```
+
+## 模板字面量类型用于事件命名
+
+```ts
+interface AnalyticsPayloads {
+  checkoutStarted: { cartId: string };
+  checkoutCompleted: { orderId: string };
+}
+
+type AnalyticsEventName = keyof AnalyticsPayloads;
+type AnalyticsHandlerName = `on${Capitalize<string & AnalyticsEventName>}`;
+```
+
+当项目中已有事件命名规范时使用此模式。不要为一次性字符串引入。
+
+## 泛型选择器契约
+
+```ts
+interface Entity { id: string }
+export function selectEntity<T extends Entity>(items: readonly T[], id: string): T | undefined {
+  return items.find(item => item.id === id);
+}
+```
+
+## 类型审查反馈
+
+报告类型安全问题时，需包含：
+
+- 过于宽泛、过于狭窄或不合理的类型边界。
+- 尽管通过 TypeScript 但可能在运行时失败的行为。
+- 最小替换类型或守卫方案。
+- 该变更是否需要测试或类型测试。