agentcss 0.0.0-stage → 0.11.2

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,64 @@
+# 贡献者行为准则
+
+## 我们的承诺
+
+为了营造开放、友好的环境，我们承诺：参与本项目的每个人都不会因为
+年龄、体型、可见或不可见的残障、族裔、性别认同与表达、经验水平、
+教育程度、社会经济状况、国籍、个人外貌、种族、宗教、
+或性取向与性别认同而受到骚扰。
+
+## 我们的标准
+
+有助于营造积极环境的行为：
+
+- 对不同的观点与经验保持同理与尊重
+- 给出并坦然接受**建设性的反馈**
+- 承认错误、向受影响的人道歉，并从中学习
+- 关注什么对整个社区最好，而不只是个人偏好
+
+不可接受的行为：
+
+- 性化的言语或图像，以及任何形式的性关注或挑逗
+- 挑衅、侮辱或贬损性的评论，人身或政治攻击
+- 公开或私下的骚扰
+- 未经明确许可发布他人的私人信息（如住址、邮箱）
+- 其他在专业场合下可被合理认为不当的行为
+
+## 执行责任
+
+维护者负责澄清并执行上述标准，会对其认为不当、威胁、冒犯或有害的
+行为采取适当且公平的纠正措施。
+
+维护者有权移除、编辑或拒绝不符合本准则的评论、提交、代码、issue
+与其他贡献，并在适当时说明理由。
+
+## 适用范围
+
+本准则适用于所有项目空间，也适用于个人在公开场合**代表本项目**时。
+
+## 执行
+
+遇到辱骂、骚扰或其他不可接受的行为，请通过以下渠道报告：
+
+- 一般行为问题：开一个 issue（若涉及具体的人，请先私下沟通）
+- **安全相关**：走 [`SECURITY.md`](SECURITY.md) 里的私有渠道，**不要**开公开 issue
+
+所有投诉都会被及时、公正地审阅与调查。
+
+维护者有义务尊重事件报告者的隐私与安全。
+
+## 执行指南
+
+维护者按以下四档处理：
+
+| 档 | 行为 | 处置 |
+|---|---|---|
+| 1 · 纠正 | 不当措辞，或被认为不专业的行为 | 私下书面警告，说明为何不当；可能要求公开道歉 |
+| 2 · 警告 | 单次或系列违规 | 警告并**限定期限内**不得与相关人员互动 |
+| 3 · 暂时封禁 | 严重违规，含持续不当行为 | 限定期限内禁止任何形式的互动 |
+| 4 · 永久封禁 | 持续违规、骚扰个人、攻击某类人群 | 永久禁止参与本项目 |
+
+## 出处
+
+本准则改编自 [Contributor Covenant](https://www.contributor-covenant.org/)
+2.1 版（<https://www.contributor-covenant.org/version/2/1/code_of_conduct/>）。

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# 参与贡献
+
+## 先跑一遍门禁（这一步别跳）
+
+```bash
+npm ci                 # 按锁文件装（验证 lockfile 真能装）
+npm run gate           # 全量：含浏览器类
+npm run gate:fast      # 只跑静态层，不用装浏览器
+```
+
+全量是 **177 道门禁**（本机约 10 分钟）。
+
+⚠️ 上面的数字写在**代码块外**是有意的：`doc-facts-gate` 会核对
+「文档里的门禁数」与 `check-all.sh` 的真实注册数，而**代码块内的内容被豁免**
+（那是示例、不是事实声明）—— 所以写在块里等于没人守它。
+本文件那两行原来正是写在块里的（写着 135 道，而真值早已不是）⇒ 已挪出来。
+
+三个分层用哪个、各自跳什么，见 `05-audit/check-all.sh` 的文件头说明。
+它跑完会打一行「本轮：执行 N 道 · 按层跳过 M 道」——
+**看到"全部通过"时先看这一行**，否则容易把"跳过一半"读成"全都过了"。
+
+**你的改动必须让 `npm run gate` 从头绿到尾。** 不是"我改的那几个绿了"就行 ——
+门禁是整体的，改 CSS 可能撞到体积上限、改注释可能撞到文档事实门禁。
+
+### 为什么门禁有一百多道而不是 5 道
+
+（这里**故意不写具体数字**：写了就成第二个真源，`doc-facts` 只能守它认得的
+一种写法，守不住散文里的数字。真值以 `check-all.sh` 的注册数为准，
+它每次跑完会打印「执行 N 道 · 按层跳过 M 道」。）
+
+这个库的核心卖点之一就是"每条契约都有门禁守着"。因此：
+
+- 改组件 ⇒ 至少跑组件自己的 `--check` 门禁 + 全量
+- 改令牌 ⇒ `token-parse` / `token-tree` / `cascade-layer` 三道都会看
+- 改文档 ⇒ `doc-facts` 会核对里面的数字与仓库是否一致
+- **只跑相关的几道是不够的** —— 曾经有一批门禁在自己的调用方式下扫 0 个文件
+  仍判通过（`ERRORS.md` E41），所以现在每道门禁都有「零文件即失败」的守卫
+
+## 提交信息怎么写
+
+```
+fix: <一句话说清改了什么、为什么>
+
+<为什么这么做 / 踩了什么坑 / 放弃了哪个方案及其理由>
+```
+
+**关键是第二段**。第一段说"改了什么"（git 已经有了），第二段说
+**为什么** —— 半年后你查这件事时，第二段才是有用的。
+
+参考本仓库已有的提交（`git log`）：
+
+- `fix: 门禁 combobox-inst 当场抓到一个真 bug —— destroy() 漏摘微行为核`
+- `fix: 内容组件 max-width 的 68ch 是拉丁语系那一档 ⇒ 改 var(--measure-prose)`
+
+## 几条硬规矩
+
+1. **一次性迁移脚本用完即删。** 别留在仓库里 ——
+   本库曾有一个 `leak-fix-paths.py`，它的正则匹配任意引号字符串，
+   一次运行把 **80 个文件**的每个字符串字面量都改了（见 `ERRORS.md` E42）。
+2. **新增门禁必须带反向控制。** 一道不会红的门禁不算门禁。
+   写法见 `05-audit/token-parse-gate.py` 的 `selftest()`。
+3. **同一个判定不要写两遍。** 判据分散在两个文件里必然漂移
+   （`ERRORS.md` E31）。要复用就 import，不要复制。
+4. **修门禁前先证明它现在真的会红。** 用 `--dir <目录>` 与无参各跑一次，
+   两者的差别就是问题的形状（这正是 E41 的发现方式）。
+5. **豁免要写清理由，并列举式。** 「这份代码的使用者控制不了它」是唯一的豁免理由；
+   新增豁免必须显式列出来，否则会被抓到 —— 宁可多报一次，也不要默默放过。
+
+## 提 PR 之前
+
+- [ ] `npm run gate` 全绿（或说明为什么某些门禁在你的环境跑不了）
+- [ ] 改动涉及 UI ⇒ 在 `10-review/shots/` 里有截图对比
+- [ ] 改了行为 ⇒ `ai/components.json` 已重新生成（`npm run ai`）
+- [ ] 改了令牌或组件 ⇒ `npm run dist` 已重建，dist 与源码一致
+- [ ] 有踩坑 ⇒ 写进 `ERRORS.md`（症状 / 根因 / 规则三件套）
+
+## 代码风格
+
+- **JS 必须过 ES5 门禁**：不用 `const` `let`、箭头函数、模板串、`class`、`async`、
+  `?.`、`??`。范围是 `01-tokens` ~ `09-assets`（`es5-gate.py` 守着）。
+- **状态写在 DOM 属性上**，不写在 class 里（INVARIANT I-8）。
+- **CSS 用 `@layer` 吗？** 现在不用，理由与切换判据见 `docs/GUIDANCE.md`。
+- 注释写**为什么**，不写是什么。取舍理由、踩过的坑、放弃的方案 ——
+  这些半年后有用；`.foo { color: red }` 没有。
+
+## 报告 bug
+
+请附上：浏览器与版本、复现步骤、你的代码（能缩到最小最好）。
+无障碍相关的问题请在标题里写 `a11y`，会优先处理（见 `SECURITY.md` 的理由）。