Skip to content

chore(lint): 新增设置行归属检查 - #1771

Merged
qqqqqf-q merged 3 commits into
felinics:mainfrom
qqqqqf-q:chore/memoh-289-settings-rows-check
Nov 12, 2026
Merged

qqqqqf-q merged 3 commits into
felinics:mainfrom
qqqqqf-q:chore/memoh-289-settings-rows-check

Conversation

@qqqqqf-q

@qqqqqf-q qqqqqf-q commented Nov 12, 2026 •

Copy link
Copy Markdown
Member

Author

  • Human
  • Agent

Type

  • bug
  • feat
  • test

Summary

问题:#1749 之后,设置卡片(SettingsSection)负责左右 16px 缩进,列表(SettingsSection 或 SettingsList)负责行高、上下留白和行间分隔线,行本身只排内容;卡片专属出血原语(SettingsBleed、ModelListRow)依赖外层卡片提供内缩。违反这套约定的三类写法,类型检查、ESLint 和 check-ui-contract 都发现不了,因为它们取决于节点在渲染树里的位置,而不是单行上的 class:

  • 行不在列表里:设置行直接放进弹窗正文或 SettingsSection 的 #actions / #footer 插槽,失去行高、留白和分隔线,相邻两行挤在一起。
  • 卡片内手写卡片缩进:卡片内容(含 SettingsRow 自身或 #footer)自己又写了 px-4 / mx-4 / -mx-4 / --settings-inset,结果多缩进 16px,或被拉出卡片边缘。
  • 卡片外使用卡片出血原语:SettingsBleed 或 ModelListRow 放进 SettingsList 或裸表面,反向拉出 -mx-(--settings-inset) 导致横向溢出 16px。

#1749 的 review 里实际出现过这类问题(渠道设置 Advanced 弹窗、MCP 详情、Provider 表单),都是人工审出来的。

做法:新增 scripts/check-settings-rows.mjs 与回归单测 scripts/check-settings-rows.test.mjs。

  • 用 apps/web 已依赖的 vue/compiler-sfc 解析 apps/web/src 下所有 .vue 模板,并沿模板中实际作为组件标签渲染的本地 .vue 引用追踪组合,不新增依赖。
  • 拆分 list 与 card 两套上下文,对每个组件不动点推导 rootRows、rootInsets、rootBleeds 与具名插槽上下文(含同名 <slot> 在多分支出口的保守合并,以及 SettingsSection 的 default / #actions / #footer 区分)。
  • 仅真正 teleport 到 <body> 的弹层内容面(DialogContent、DialogPanel、PopoverContent 等,以及 ConfirmPopover / FormDialogShell 的非 #trigger 插槽)重置列表与卡片上下文;原位触发器与包装组件保留父级上下文。没有任何父模板直接以标签渲染的组件(路由页及 <component :is> 动态挂载面板),若根上存在游离行或卡片出血原语会直接报出精确行号与传播链。
  • 有意的例外在元素前写 <!-- ui-allow-loose-row: 原因 --> 或 <!-- ui-allow-card-inset: 原因 -->,原因必填(不少于 10 个字符)。写在组件使用处前面时,同样豁免该组件根上传播上来的问题。

接入:

  • mise run lint 新增 lint:settings-rows 一步,也可以单独运行。
  • CI 的 Lint job 在 pnpm install 之后运行 node scripts/check-settings-rows.mjs,Test job 运行 node --test scripts/check-settings-rows.test.mjs。
  • 根 AGENTS.md 的 UI 检查一节补充说明。

main 上现有两处有意的“行不在列表里”,补上了例外注释,只改注释,不改模板结构:

  • 外观设置的 Advanced 弹窗:正文里只有一个设置行,不需要行节奏。
  • Bot 用户访问控制的嵌入模式:沿用原有注释说明的原因,改为例外注释格式。

Related Issues

Validation

以下为 Agent 自检,不是真人 QA。

  • main 上通过:mise run lint:settings-rows 输出 ✓ settings rows OK (346 components);mise run lint:contract 与 pnpm --filter @memohai/web typecheck 通过。
  • 单测覆盖:node --test scripts/check-settings-rows.test.mjs 10 组用例全部通过,覆盖合法组合、弹窗游离行与豁免原因长度、跨多层组件根缩进传播、SettingsList 与 SettingsSection 区分(ModelListRow / SettingsBleed 溢出拦截)、SettingsSection #actions / #footer 插槽、<component :is> 动态容器与脚本动态页签、原位弹层触发器与 teleport 内容分离、同名 <slot> 多分支合并,以及 CLI 退出码。
  • 正向对照:在 refactor: 设置卡片缩进与行节奏改由外壳和列表负责 #1749 review 修复前的提交 cd67ed26b 上运行,检查失败(exit 1),报出 review 中人工发现的 4 处问题——渠道设置 Advanced 弹窗的行不在列表里、MCP 详情 1 处与 Provider 表单 2 处卡片内 mx-4——以及上面两处尚未加注释的有意例外。修复后这 4 处全部消失。
  • ESLint:两个改动的 .vue 文件、检查脚本和单测均通过。
  • 覆盖边界:
    • 只看模板里的组件组合。CSS 覆盖、h() 渲染函数和异步组件不在检查范围内;当前 apps/web 中没有用渲染函数渲染设置行,3 个异步组件都不含设置行。

Screenshots / Recordings

两个 .vue 文件只改了模板注释。为确认注释不影响渲染,在本地开发环境里打开了这两处界面并截图:本分支的宿主机 vite(127.0.0.1:8611)连接本地 OSS 开发栈(server 18080),用 admin 账号登录,只查看,没有保存。

外观设置 → 高级弹窗:正文里唯一的设置行(侧边栏示例入口)正常显示,左边缘与弹窗标题对齐(均为 409px)。这个弹窗就是脚本里那处 ui-allow-loose-row 例外。

外观设置高级弹窗(浅色)
外观设置高级弹窗(深色)

新建 Bot → 工作区成员(Bot 用户访问控制的嵌入模式,另一处例外):成员列表在“基本设置”卡片内,和上面的行共用卡片的行节奏:行高 60–63px,上下内边距 12px,行间有分隔线,左边缘一致。

新建 Bot 页的工作区成员(浅色)
新建 Bot 页的工作区成员(深色)

截图只说明这两处界面的渲染没有变化;lint 脚本本身的正确性见上面的 Validation。

Human QA

  • Human QA passed

scripts/check-settings-rows.mjs 解析 apps/web 的 Vue 模板并沿本地组件 import
推导上下文,检查两类问题:设置行不在任何 SettingsSection / SettingsList 里;
设置卡片内容手写了卡片自己的横向缩进。接入 mise run lint 与 CI Lint job。

Refs: MEMOH-289
@github-actions github-actions Bot added change:web Changes web frontend or shared frontend packages size:S PR size uses the larger of added or deleted lines, excluding generated files test Adds or updates tests labels Nov 12, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: ef03a13ad2

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment on lines +194 to +196
<!-- ui-allow-loose-row: a single setting alone in the dialog body. With
no neighbouring rows it needs no row height or hairline, and the
body's own padding already lines it up with the dialog title. -->

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P1 Badge Provide the required real-application screenshot evidence

The commit's Screenshots / Recordings section explicitly substitutes guard runs for application screenshots because the changes are scripts and comments. Root AGENTS.md requires runtime UI verification and screenshots for every change and states, “Alternative checks do not waive these requirements.” The documented verification is therefore incomplete: exercise the relevant settings flows in the current application and provide screenshot evidence, or report the concrete blocker rather than treating the lint controls as a substitute.

AGENTS.md reference: AGENTS.md:L128-L128

Useful? React with 👍 / 👎.

Comment thread scripts/check-settings-rows.mjs Outdated
Comment on lines +144 to +145
if (child && here.list === 'yes' && !here.row && !here.bleed) {
for (const inset of child.rootInsets) out.errors.push(`${inset} inside a settings card (rendered by ${where(node)}) — the card already insets its content by --settings-inset.`)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Propagate root insets through intermediate component wrappers

When a card renders Wrapper.vue, which renders an imported Inset.vue containing <div class="mx-4">, the analysis reports success even though the margin still doubles the card's inset. This branch checks child.rootInsets only when the immediate caller already has list === 'yes'; an intermediate component analyzed with list === 'root' never copies those insets into its own summary. Consequently, the fixed-point passes cannot propagate them across the wrapper, and extracting the same offending markup into a second component bypasses the guard. Propagate child insets through the root context as well.

AGENTS.md reference: AGENTS.md:L107-L107

Useful? React with 👍 / 👎.

Comment thread scripts/check-settings-rows.mjs Outdated

const visit = (node, ctx, siblings, index) => {
if (node.type !== NODE_ELEMENT) return
if (node.tag === 'slot') { out.slotCtx ??= ctx.list; return }

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Derive slot context from the matching slot outlet

For a wrapper whose template is <slot name="header" /><SettingsSection><slot /></SettingsSection>, this line records the named header slot's root context and ignores the default slot's list context. A page rendering <Wrapper><SettingsRow /></Wrapper> consequently fails the routed-page check even though its rendered row is inside a SettingsSection. Track contexts by slot name, or at least derive the default-slot summary from the default outlet, so a preceding named slot cannot make the mandatory lint step reject a valid layout.

AGENTS.md reference: AGENTS.md:L107-L107

Useful? React with 👍 / 👎.

Comment thread scripts/check-settings-rows.mjs Outdated
Comment on lines +144 to +145
if (child && here.list === 'yes' && !here.row && !here.bleed) {
for (const inset of child.rootInsets) out.errors.push(`${inset} inside a settings card (rendered by ${where(node)}) — the card already insets its content by --settings-inset.`)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Honor inset exemptions when checking imported children

When an imported component contains a root inset, placing the documented ui-allow-card-inset: <reason> comment immediately before its use inside a card still fails lint. The earlier allowed(...) check suppresses only classes on the use-site node; this separate child.rootInsets error path ignores the marker. Thus the escape hatch works for inline markup but not for the same markup extracted into a component, forcing callers to exempt the reusable child's source globally instead of documenting a deliberate exception at one usage. Honor the marker on this error path too.

AGENTS.md reference: AGENTS.md:L107-L107

Useful? React with 👍 / 👎.

@chatgpt-codex-connector

Copy link
Copy Markdown
Codex Review Summary: ✅ Completed

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-11-12T07:12:04.316516Z ef03a13 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

- 卡片缩进经中间包装组件传递时也会被检查到,不再因抽成第二个组件而漏判。
- 插槽上下文按插槽名记录,具名插槽不再决定默认插槽的上下文,避免误判。
- 组件使用处的 ui-allow-card-inset 注释同样豁免该组件根上的缩进。

Refs: MEMOH-289
@github-actions github-actions Bot added size:M PR size uses the larger of added or deleted lines, excluding generated files and removed size:S PR size uses the larger of added or deleted lines, excluding generated files labels Nov 12, 2026
@qqqqqf-q
qqqqqf-q merged commit 92bed75 into felinics:main Nov 12, 2026
23 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

change:web Changes web frontend or shared frontend packages size:M PR size uses the larger of added or deleted lines, excluding generated files test Adds or updates tests

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant