# @g48in/reqfile-colocation 中文文档

规范地址：https://npmcn.com/package/%40g48in/reqfile-colocation/

版本：0\.4\.0
npm 元数据更新时间：2026-11-01T16:43:44.094Z
中文译文更新时间：2026-11-15T20:25:14.718Z
软件包许可：MIT OR Apache-2\.0

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

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

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

- 包体积（解压后）：1.2 MB，4 个文件
- 模块格式：ES Module
- TypeScript 类型：未声明
- 运行依赖：3 个
- 首次发布：2026-09-28T15:23:11.160Z
- 最新版本发布：2026-11-01T16:43:43.791Z
- 近 30 天下载量：7752（2026-10-16 至 2026-11-14，npm 官方下载统计）
- 已发布版本数：4（近 12 个月 4 个）

## 中文简介

reqfile checker for COLOCATION:每个功能拥有其代码,曝光一个接口,可以自行删除

## 安装

```sh
npm install @g48in/reqfile-colocation
```

也可以使用：`pnpm add @g48in/reqfile-colocation`、`yarn add @g48in/reqfile-colocation`、`bun add @g48in/reqfile-colocation`

## README

# reqfile- 同一地点

可分享 [req 文件](https://reqfile.dev/) 要求: **合并**,每个 特性拥有其代码,暴露出一个接口,可以自行删除.

这是社区需求包的一快之快: 要求、其核对器和标有标签的基准,在一个存储库中 与任何项目内的要求相同的布局.

```
Reqfile.yaml                      # the requirement, same format as a local one
.reqfile/COLOCATION/examples/     # labeled benchmark: example.yaml (label, expected findings, rationale) + files/
src/                              # the checker, in TypeScript, published to npm
```

## 用这个

尝试它,然后通过它(reqfile 0.3或以后,与 [阿宝](https://bun.sh/) 已安装 :

```sh
reqfile eval --use gabsn/reqfile-colocation@v0.4.0    # its score on its examples
reqfile check --use gabsn/reqfile-colocation@v0.4.0   # its findings on your code
reqfile add gabsn/reqfile-colocation@v0.4.0           # writes the line below
```

写道:

```yaml
code:
  - { id: COLOCATION, use: gabsn/reqfile-colocation@<commit> }  # v0.4.0
```

检查运行 `bunx @g48in/reqfile-colocation@0.4.0 verify` (堵塞)和 `... suggest` (咨询): Bun 获取检查器及其依赖性 (TypeScript 6,web-tree-sitter, yaml) 从npm一次并缓存它们. 蟒 仓库需要蟒蛇3号。 仅使用节点,使用 `npx -y` 改为 `bunx`。 。 。 .

## 检查器

`reqfile-colocation` 从寄存器根运行并读取整个 存储器( 尊重. gitignore) 。 它有两个命令,宣布为两个 核查合作情况:

-   **`verify`挡住.** 规则取自解决的依赖性图表和a 很少明确公约(一项) `index.ts` 或再出口 `__init__.py` 是一个 界面,测试文件由名称识别,工作流程步骤为 8 个或更多 线条是一个特性的逻辑)。 一个发现是关于解密代码的事实 这些公约不是建筑结论的证据: 公约是样式选择,下文对此作了说明。 每个判断文件以一个结尾 3个州,计为:
    
    -   **达标**: 一个SARIF `pass` 结果;
    -   **违反**: 一个SARIF `fail` 结果命名其规则、文件和行;
    -   **无法核实**: 本地导入, 解析为无, 文件 不解析, a `mod x;` 没有文件, 一个 stale 例外, Python 没有 python3 的文件 。 在 stderr 上列出; 运行出入口 2, 该出入口为 req 文件 报告为失败运行的错误.
    
    仅当每个文件被验证且没有规则被打破时退出 0; 1 当 有违反规定的情况,而且所有情况都经过了核实;2 当情况并非如此时.
    
-   **`suggest`咨询.** 需要知道哪些文件构成一个的休克 特性,代码未表示: 所有权从进口商读取, 1 功能分割到分级文件夹( e)`split`: 一个共享文件夹名称和 a 依赖性,作为应用/花园和下等/花园,或 oss/widget旁 部件/ evals ),仅在文件下方使用的项目,抓取包文件, 特性 打开文件夹,层名文件夹。 每项发现都有概率; 没有街区.
    

### 如何读取代码

| 语言 | 解析器 | 决议 | 边界(接口) |
| --- | --- | --- | --- |
| 类型脚本, JavaScript | TypeScript 6 的语法树 | TypeScript 模块分辨率与最近的 tsconfig/jsconfig ()`extends`, (中文(简体) ), `paths`, (中文(简体) ), `baseUrl`); 工作空间软件包按其软件包. json `name`, (中文(简体) ), `exports`, (中文(简体) ), `main`; 资产通过别名 | 一个文件夹 `index.*` 出口 |
| 蟒 | 蟒蛇3级 `ast` | 输入文件夹、 pyproject/设置根及其 `src/`,寄存器根; 一个正则软件包胜过命名空间文件夹; 名称绑在 `if`编号 :`try` 计数 | 一个包裹,它的 `__init__.py` 再出口或定义 `__all__`; 它导出的名称通过它 |
| 锈 | 树保姆的rust语法 | 每个箱子根的模块树通过 `mod` (与 `#[path]`(三); `use` 树、 合格路径、 宏参数内路径 | rustc 强制可见度, 因此编译的路径都不是绕行 |

外部进口的依赖性也计算:工作流程步骤中的路径, shell 脚本, package.json 脚本/`bin`编号 :`exports`,任务和运行文件 (mise.toml, Makefile, Dockerfile, wrangler.toml...), 列表和字符串 字义. 进入另一套件的路径取决于该套件.

### 缓存

在一棵没有改变的树上进行第二次运行,只检查它是否没有改变,而且 编辑后的文件再次单独解析(自0.4.0起). 缓存在 `$REQFILE_CACHE/colocation`,在git文件夹中, `.git/reqfile/colocation`除了reqfile的作品之外 答对. 它跟随寄存器: CI 任务开始冷, 除非它保持 运行之间的文件夹。 每个条目都按分析内容排序:

-   **一个文件自己写的是什么** (其导入,路径正文,解析错误) 以它 git blob 散列键取名 : 编辑后的文件已解析 其它文件则不是( TypeScript、 JavaScript 和 Python; Rust 文件) 当结果重新计算时,将再次解析.
-   **整个结果**,分析和报告,由检查者自行键入 代码,它的运行时间和依赖的版本,寄存器的文件夹和 每个文件的 blob 散列列表: 索引, 否则字节 分析读取(修改后的文件和未跟踪的文件,链接到它们的 目标, 文件标记 `assume-unchanged` 或者说 `skip-worktree`) (中文(简体) ). 任何变动 重算它:模块解析和 Rust 解析然后全部运行. 模块解析度还读取 git 不列出的内容( node modules, 忽略) 建立输出, 从软件包扩展的 tsconfig : 每个这样的查询都是 以答案录入,结果只有在每次检索时才会重复使用 答案还是一样. `verify` 接下来 `suggest` 在一个树上分享一个 分析.

缓存没有改变报告的证据: 4个冷冻的蝎子 和arkadia,冷而温暖的字节 0.3.0个指纹,版本外(未更改的树); `src/cache.test.ts` 一次更改一个输入( 编辑、 返回、 符号链接的目标、 标记) 文件, tsconfig 和 package.json, 一个新删除或被忽略的文件, 一个已安装 并检查热跑 打印一个冷的。 没有 覆盖: git clean/ smodge 过滤器,其工作副本与 blob a 不同 事实已锁定 。 删除文件夹开始冷 .

在arkadia上(约2,300个文件,其中1,000个为TypeScript;中值为5) 在笔记本电脑上互换运行:

| 运行 | 0.3.0 (中文(简体) ) | 0.4.0 (中文(简体) ) |
| --- | --- | --- |
| `verify`空缓存 | 1.54 s (中文(简体) ) | 1.38s (中文(简体) ) |
| `verify` 接下来 `suggest`空缓存 | 3.23节 | 1.84 s (中文(简体) ) |
| `verify`,没有改变 | 1.54 s (中文(简体) ) | 0.20 s (简体中文) |
| `verify`,一个文件已编辑 | 1.54 s (中文(简体) ) | 0.76 s (简体中文) |

### 封锁规则

| 规则 | 断开时 |
| --- | --- |
| `interface` | 从边界外部导入一个执行文件而不是其接口(一个软件包自己的文件可能会超过其根索引;生成的代码不受限制) |
| `tests` | 测试在它所测试的代码文件夹( 其名称, 否则它所导入的生产代码) 之外; 对一个软件包的入口或几个特性的测试可能活在软件包根; Rust `tests/`, (中文(简体) ), `benches/`, (中文(简体) ), `examples/` 和迁移需要工具 |
| `entry` | 一个工作流程步骤在寄存器的文件夹上运行了8行或8行以上的 shell , 而不是调用脚本( 8 是“ 有线” 的样式公约, 而不是证明这些行是特性的逻辑) |
| `roots` | 在同一个地点宣布的根下面。 yaml, 一个文件, 其若干特性的使用既不被宣布共享, 也不在一个特性内 |

### 并用. yaml( 可选, 严格)

```yaml
roots:                       # make ownership checkable where it matters
  - path: src                # each direct file or folder of src/ is a feature
    shared: [src/format.rs]  # the modules several features share, by decision
exceptions:                  # explicit, limited, reported in every run
  - path: test/**
    rule: tests
    reason: the deployment image runs test/ only
```

未知的密钥、 不存在的已声明的路径或例外 匹配未找到失败运行( exit 2): 例外不能超过代码 他们原谅。 除调查结果外,在SARIF中属于公认的抑制.

## 措施

同一被冻结的人身保护令上的所有版本`corpus-v4`,73个实例):45个 发展实例(主要工程师审查的最后五个),16+ 两名独立作者撰写的12个确认实例 单凭要求,从不用于调音(两个重贴上作者的标签 见LABELS.md)。 发现违反/虚假警报 正确实例:

| 版本 | 发展 | 确认1 | 2\. 确认 2 |
| --- | --- | --- | --- |
| 1.1.3 国家 | 第10/20、3/25号决定 | 0/7, 第4/9页 | 1/5, 0/7 (中文(简体) ) |
| 0.2.0 (中文(简体) ) | 第17/20、4/25号决定 | 第1/7、3/9号决定 | 1/5, 2/7 (中文(简体) ) |
| **0.3.0 (中文(简体) ) `verify` (屏蔽声)** | 8/20,第8段), **0/25 (中文(简体) )** | 1/7, (英语), **0/9 (英语)** | 1/5, (英语), **0/7 (英语)** |
| 0.3.0 (中文(简体) ) `verify` + 键 `suggest` | 第20/20和1/25号决定 | 第2/7和2/9号决议 | 2/5, 2/7 (中文(简体) ) |

首次与被冻结的候选人(0人被抓到, 0假警报). 错过了 `violation-ts-monorepo-emails` 显示工作空间 没有节点模块软件包无法解析;随后的修补 因此,上面的1/5 已经污染了 已经看到这个案例.

号码上面写着: 封堵支票没有引起41号错误警报 例如,其中25个是发展实例,16个得到确认 实例并非如此;经证实,发现的违规行为很少(12起中有2起) 他们被污染。 多数 人身保护权中的侵权行为涉及所有权(档案构成一个特征), 仅由代码决定。 0的16/19 发展到 有关独立案例的2/12:其欣欣向荣的学说符合它们自己的例子.

### 在真正的仓库

`verify` 在8个储存所上(arkadia、reqfile-同处一地、吸毒器、, 平台, skoolradar, 大脑, 迷你, 焦树 : 0.3 s至 2 s; 每 无法验证的导入左侧是真实的已损坏的导入( 3 in voxrouter) 。 独立 审查人员打开了随机抽样调查结果后面的代码:

| 规则 | 对 | 虚假 | 不确定 |
| --- | --- | --- | --- |
| 测试 | 页:1 | 0 个 | 2个 |
| 接口(两回合) | 页:1 | 1个 | 3个 |
| 条目 | 页:1 | 1(当时为固定:8行阈值) | 1个 |
| 拆分( 然后移动到 `suggest`,见下文) | 第9条 | 1个 | 2个 |
| 所有人,从进口商读取 | 1个 | 16个 | 1人 迁至 `suggest` |

一名审查员还搜索了36个未加标记的任意文件,以查清遗漏的违规行为 发现 17, 最需要的特性知识( 级别相同, 文件名) 前缀)或仅链接导入回 src/ 显示; 接口绕过 测试和测试树支持文件随后被固定。 细节 : [洛杉矶,md](https://npmcn.com/package/%40g48in/reqfile-colocation/LABELS.md) 财务报告和审定财务报表 [设计](https://npmcn.com/package/%40g48in/reqfile-colocation/DESIGN.md)。 。 。 .

### 限制

-   编码中不包含所有权:一个表面使用的一个域可能是: 表面,或一个领域 表面只是使用. `verify` 只有决定 根据申报 `roots`; 其它处 `suggest` 指点它.
-   `split` 是咨询: 共享文件夹名称和依赖性不能证明一个 特征的身份。 每个域一个 `api/` 层,一个叫 其它接口, 读作分割; 添加无关 `api/` 文件夹制作 查找消失(重复三次以上的名称为层)。 这个 只有当特性或分级被宣布时,才能被封禁.
-   不同名称的文件的分割( Name`src/public/wrap.ts` 财务报告和审定财务报表 `src/internal/break-words.ts`)不见.
-   路径引用从字面路径读取:运行时所计算的路径, 和固定装置仅按路径测试名称,没有被看到.
-   共用工具及其相同名称的用户之一(`platform/agent-evals`, (中文(简体) ), `voxrouter/agent-evals`当没有其他代码使用该工具时,读作分割.
-   Python 动态导入和由宏生成的 Rust 项不读取 .
-   在不计算任何寄存器路径名称的工作流程中内置逻辑 .

## 把它当作封存支票

做一个 `verify` 检查 `mode: blocking` 当:

1.  它的规则不会引起任何虚假的警报、发展和 等同确认(比0.3.0:0/35);
2.  在寄存器上,它从0或1出口,从2: 每一个本地的进口解决, 或例外说为什么不;
3.  每项调查结果都被视为真实、固定或例外 理由;
4.  手审查的未标记文件样本显示没有丢失封存 规则;
5.  它运行在10 s以下那里.

保留 `suggest` 咨询。 所有权只能通过 `roots`。 。 。 .

## 测量一下

```sh
bun install && bun test          # unit and end-to-end tests of the checker
reqfile eval                     # the labeled corpus, as published
```

每个违规者姓名 `findings` 每个文件都必须标出正确的检查符 (reqfile要求他们全部). `split: holdout` 标记确认 实例,由独立作者编写,从未用于调音. `reqfile eval` 运行 Reqfile 中命名的版本。 Yaml; 测量工作 抄写:, `bun run build` 将检查指向 `node dist/main.js`。 。 。 .

## 释放

弹出 `version` 包装 `run:` 然后推出一个 标签 `vX.Y.Z`通过信任的 CI 测试、构建和发布到 npm 出版,没有存储的代币.

## 常见问题

### @g48in/reqfile-colocation 是什么？

reqfile checker for COLOCATION:每个功能拥有其代码,曝光一个接口,可以自行删除

### 如何安装 @g48in/reqfile-colocation？

在项目目录运行 npm install @g48in/reqfile-colocation，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 reqfile-colocation，可以用 npx reqfile-colocation 直接运行。

### @g48in/reqfile-colocation 支持 TypeScript 吗？

该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/g48in\_\_reqfile-colocation 是否存在。

### @g48in/reqfile-colocation 支持 ESM 还是 CommonJS？

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

### @g48in/reqfile-colocation 可以商用吗？

@g48in/reqfile-colocation 使用 MIT OR Apache-2\.0 许可。可在 MIT、Apache-2\.0 中任选其一遵守。选择 MIT 时，宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @g48in/reqfile-colocation 的下载量有多少？

根据 npm 官方下载统计，@g48in/reqfile-colocation 在 2026/10/16 – 2026/11/14 这 30 天内被下载 7,752 次，日均约 258 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

### @g48in/reqfile-colocation 还在维护吗？

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