# @markless/analyzer 中文文档

规范地址：https://npmcn.com/package/%40markless/analyzer/

版本：0\.11\.0
npm 元数据更新时间：2026-11-01T19:11:25.034Z
中文译文更新时间：2026-11-01T20:00:38.624Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40markless/analyzer
原文对照：https://npmcn.com/package/%40markless/analyzer/?lang=original
项目主页：https://github.com/compiled-run/markless#readme
源码仓库：https://github.com/compiled-run/markless

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：110 kB，11 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- 运行依赖：1 个
- peer 依赖：playwright \>=1\.58\.0
- 首次发布：2026-07-16T03:59:39.922Z
- 最新版本发布：2026-11-01T19:11:24.650Z
- 已发布版本数：16（近 12 个月 16 个）

## 中文简介

便携式浏览器QA分析与一个可选的剧作家驱动程序的契约。

## 安装

```sh
npm install @markless/analyzer
```

也可以使用：`pnpm add @markless/analyzer`、`yarn add @markless/analyzer`、`bun add @markless/analyzer`

## README

# `@markless/analyzer`

`@markless/analyzer` 是浏览器通道不变检查Markless 应用程序。它转换应用程序拥有的路由/动作策略和浏览器证据 分为MLA不变结果和版本化判决报告。包的根目录是 runtime-agnostic;可选 `@markless/analyzer/playwright` 入口点集合 来自剧作家的证据 `Page`.

消费者应该将分析器检查作为合并阻塞应用程序或控制来运行 盖茨，拥有他们的矩阵，策略，预算和持久收据，并保留 更强的特定于包的断言：在现有的基础上添加分析器证据 定制证明，建立宇称，然后只删除重复的机制——永远不会 用较弱的一般性结论替换较强的断言。

## 浏览器不变量

浏览器通道当前发出遗留 `BQA-*` 别名, `normalizeInvariantId` 和 `createVerdictReport` 规范化为以下MLA id。新的持久化判决使用规范id。

-   `MLA-I1-CONSOLE` 检查捕获的 `console.error` 和未捕获 `pageerror` 操作窗口的条目。失败意味着页面至少报告了一个错误 浏览器错误。
    
-   `MLA-I2-NETWORK` 生成的请求记录 `classifyRequest`,再加上 network-liveness错误。根据消费者已知的证据进行评估 文档路径和特定阶段的API契约；失败意味着请求失败 未申报、不成功、畸形或在测量窗口后泄漏。
    
-   `MLA-I3-BOUNDARY-MISSING`， `MLA-I3-PENDING-TIMEOUT`, `MLA-I3-REJECTED` 检查debug-channel `BoundarySnapshot` 与行动的值相对 `PendingPolicy` 期望拒绝边界列表。它们分别表示 图读或快照丢失，边界超出了自己的活度 策略，或者发生了意外的拒绝。默认的活动截止日期为 归 `QA_LIVENESS_DEADLINE_MS` 在 `src/invariants.ts`.
    
-   `MLA-I4-WIRING-MISSING` 和 `MLA-I4-UNCLASSIFIED` 检查可见语义 交互候选项和调试通道的交互解释。一个 失败意味着所需的事件没有有效的框架注册(包括 router delegation for Markless links)，或者一个可聚焦/ARIA候选对象没有 可识别语义或矩阵声明的事件。标记的发现 报告消费者拥有的已知审计，而不会导致结果阻塞。
    
-   `MLA-I5-BOOTSTRAP-BUDGET` 和 `MLA-I5-ACTION-BUDGET` 比较同源V8 使用消费者提供的执行javascript字节 `AnalyzerBudgets`． 一个失败 指测量的自举或作用超过其提供的上限；这个 包不拥有应用程序预算值。
    

## MLA缝段

### `MLA-S1-PRELOAD-INTEGRITY`

`evaluatePreloadIntegrity` 使用声明的模块预加载url和阶段性的 引导、导航和操作请求观察。交互失败时 模块在操作窗口中获取，而不是预先加载； 导航允许目的地加载，直到声明的解决点和失败 之后的模块加载。已声明但从未加载的预加载作为警告返回， 不是不变的失败。

### `MLA-S2-PAYLOAD-WIRING`

`parsePayloadEventClaims` 从服务中读取事件声明 `markless/view` 数据和 初始或流臂记录。 `reconcilePayloadWiring` 比较这些说法 使用运行时调试通道注册。失败意味着承诺的有效载荷失效 运行时未确认的事件注册。无人认领的登记是 单独返回 `runtimeOnly`;运行时生成的CSR、回调-prop，以及 路由器注册不会被视为失败。

### `MLA-S3-LOCATOR-RESOLUTION`

`locatorPlansFromView` 派生由服务对象表示的定位器类型的计划 视图和 `evaluateLocatorResolution` 遍历调用者提供的DOM根 `WalkableDomAdapter`． 每个计划都必须精确地解析到一个具有预期的节点 形状。零匹配或模糊匹配使不变量失效；不能扩展的种类 从所服务的有效负载中列出 `coverage.skipped` 而不是沉默 索赔包括在内。

### `MLA-S4-STRIP-GUARANTEE`

`evaluateDebugChannelStrip` 扫描HTML和JavaScript文本工件 `DEBUG_CHANNEL_SENTINELS`． 如果任何哨兵仍然存在，则未标记的构建失败。一个 标记的构建是积极的控制，如果没有标记则失败。导入 从 `@markless/analyzer`;不要将其协议字符串复制到 消费者。

## 覆盖车道

`executedJavaScriptBytes` 消耗V8覆盖条目，合并重叠 正范围，减去嵌套的零计数范围，并计算UTF-8字节 同源脚本。缺少同源计数条目的源文本是 错误。 `collectExecutedJavaScriptBytes` 和 `measurePageWindow` 提供 剧作家集成。消费者提供的引导和行动天花板通过 来 `compareExecutedBytes` 或者 `evaluateActionInvariants`.

## 路线/行动矩阵

`validateMatrixDocument` 验证应用程序拥有的 `RouteActionMatrix`， 包括fixture url、动作定位器和操作、API契约、设置 依赖项、挂起/拒绝策略、导航意图和重置安全性。 `assertMatrixFileSetEquality` 能否另外证明矩阵路由文件相等 消费者发现的路由文件。验证持久化JSON [`route-action-matrix.schema.json`](https://npmcn.com/package/%40markless/analyzer/route-action-matrix.schema.json);导入 TypeScript契约和验证器，而不是在 利用。

## 定位器和有效载荷收集

剧作家帮助者 `collectLocatorResolution` 和 `collectPayloadWiring` 适应 将实时文档发送到便携式S3和S2评估器。他们互相检查 `data-async-container`，它自己的有效负载脚本，以及Markless调试通道 分析器所需的子集。缺失的或不兼容的通道是一个集合 错误，不是传递不变量。

## 剧作家司机

使用时安装剧作家 `@markless/analyzer/playwright`. `ConsoleLedger` 和 `RequestLedger` 保留控制台和分类请求证据； `waitForBoundaryLiveness`， `inventoryCandidates`, `collectCandidateExpectations` 收集浏览器通道的证据； `performMatrixAction` 执行一个经过验证的矩阵动作；和 `measurePageWindow` 结合了动作窗口，活跃性，网络安静，候选库存，V8 覆盖，以及S1评估。 `collectServedBuildArtifacts` 提供文本工件 S4。还为负控制测试导出故障帮助程序。

## 见证判决和报告

`createWitnessVerdict` 将证人箱结果转换为 `MLA-EXT-WITNESS`． 将它与浏览器和接缝结果结合起来 `createVerdictReport` 或者 `appendInvariantResult`. `validateVerdictReport` 验证 当前报告形状，而 `readVerdictReport` 还升级了遗留的浏览器qa 报告和规范化被接受 `BQA-*` 别名。报告版本和接受情况 拥有不变id `src/contracts.ts` 和 `src/verdicts.ts`.

## 最小的集成

此示例假设调用方已经打开了启用调试的应用程序页面。 收集两次缝检，验证带钢正控制，集成一次 见证结果，并创造一个规范的判决。

```ts
import {
    createVerdictReport,
    createWitnessVerdict,
    evaluateDebugChannelStrip,
} from '@markless/analyzer';
import {
    collectLocatorResolution,
    collectPayloadWiring,
    collectServedBuildArtifacts,
} from '@markless/analyzer/playwright';
import type { Page } from 'playwright';

export async function analyze(page: Page) {
    const [payload, locators, artifacts] = await Promise.all([
        collectPayloadWiring(page),
        collectLocatorResolution(page),
        collectServedBuildArtifacts(page),
    ]);
    const strip = evaluateDebugChannelStrip({ debugEnabled: true, artifacts });
    const witness = createWitnessVerdict({
        name: 'application-browser-lane',
        tags: ['browser'],
        passed: true,
        receiptPath: 'artifacts/application-browser-lane.json',
    });

    return createVerdictReport({
        source: 'application',
        lane: 'browser-invariants',
        results: [payload.invariant, locators.invariant, strip, witness],
    });
}
```

## 常见问题

### @markless/analyzer 是什么？

便携式浏览器QA分析与一个可选的剧作家驱动程序的契约。

### 如何安装 @markless/analyzer？

在项目目录运行 npm install @markless/analyzer，或使用 pnpm add / yarn add / bun add。

### @markless/analyzer 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @markless/analyzer 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @markless/analyzer 可以商用吗？

@markless/analyzer 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @markless/analyzer 还在维护吗？

最新版本 0\.11\.0 发布于 2026/11/02（1 天前）；至今共发布 16 个版本，其中过去 12 个月发布了 16 个；首次发布于 2026/07/16。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。