dsh-knit 0.18.0 → 0.19.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,250 @@
1
+ /**
2
+ * Knit · **文件分类层**(v0.19)
3
+ *
4
+ * ## 为什么要有这一层
5
+ *
6
+ * v0.18 之前,「这个文件 Knit 管不管」只由一个 `kindOfName(name)` 回答:
7
+ * `md` / `image` / `video`,其余一律丢掉。v0.19 要把代码纳入检索,如果继续在
8
+ * scanner、retrieval、preview、UI 里各写一段 `if (ext === '.js')`,同一个判断会散成
9
+ * 四五份互相漂移的副本 —— 加一个扩展名要改四个地方,漏一个就是一个静默的 bug。
10
+ *
11
+ * 所以判断收拢到这里:**`classifyFile(name)` 是唯一的事实来源。**
12
+ * 其余模块只消费它的结果,不再看扩展名。
13
+ *
14
+ * ## 返回的不是一个字符串,而是一组「这个文件能用来做什么」
15
+ *
16
+ * 三个布尔位是这一层的核心,它们回答的是三个**互相独立**的问题:
17
+ *
18
+ * - `searchable` —— 能不能进 BM25 语料(能不能被任务检索到)
19
+ * - `contextual` —— 能不能成为 Context Pack 候选(Primary / Supporting / Related)
20
+ * - `previewable` —— Knit 面板能不能内联预览它
21
+ *
22
+ * 三者**不等价**,`.map` 就是那个把它们撕开的例子:
23
+ * 它是文本(`previewable`)、但它不是上下文(`searchable:false, contextual:false`)。
24
+ * 把这三件事压成一个「类型」字段,`.map` 这种边界就只能靠特判活下去。
25
+ *
26
+ * ## 边界(v0.19 需求 §5 §6 §7)
27
+ *
28
+ * - 代码白名单**严格限定**第一批高频 AI Coding 扩展名;`.go` / `.rs` / `.java` ...
29
+ * 这一版明确不支持(返回 `ignored`),不是遗漏,是范围控制。
30
+ * - `.map` / `.min.js` / `.bundle.js` / `.generated.js` / `.gen.js` / `*.lock`
31
+ * 归为 `generated`:**能预览,但不进检索、不进上下文、不进列表**。
32
+ * - 未知扩展名归为 `ignored`:Knit 不管它(不做 plain-text 兜底 —— `/knit/api/doc`
33
+ * 是按路径读文件的接口,兜底等于把「读工作区里任意文件」的口子重新打开)。
34
+ *
35
+ * 这一层是**纯函数、零 I/O、零依赖**:给一个文件名,立刻得到一个答案。
36
+ */
37
+
38
+ /** 列表条目类型。前四个是「会出现在列表里」的产物类型,后两个是**不出现**的。 */
39
+ export const KIND_DOCUMENT = 'md'
40
+ export const KIND_CODE = 'code'
41
+ export const KIND_IMAGE = 'image'
42
+ export const KIND_VIDEO = 'video'
43
+ /** 生成/调试产物:可预览,但不参与检索与上下文(`.map` / minified / lock ...)。 */
44
+ export const KIND_GENERATED = 'generated'
45
+ /** Knit 不管的类型(这一版不支持的代码语言、二进制、未知扩展名)。 */
46
+ export const KIND_IGNORED = 'ignored'
47
+
48
+ /**
49
+ * 允许内联渲染的图片类型白名单。
50
+ *
51
+ * `/knit/api/raw` 是按路径读文件的接口,口子必须收窄:只有在这个表里的扩展名才放行,
52
+ * 否则就成了「能读工作区里任意文件」的后门。
53
+ */
54
+ export const IMAGE_TYPES = new Map([
55
+ ['png', 'image/png'],
56
+ ['jpg', 'image/jpeg'],
57
+ ['jpeg', 'image/jpeg'],
58
+ ['gif', 'image/gif'],
59
+ ['webp', 'image/webp'],
60
+ ['avif', 'image/avif'],
61
+ ['bmp', 'image/bmp'],
62
+ ['ico', 'image/x-icon'],
63
+ ['svg', 'image/svg+xml'],
64
+ ])
65
+
66
+ /**
67
+ * 允许内联渲染的视频类型白名单。
68
+ * 与 IMAGE_TYPES 同样的口径:只放行表里的扩展名,/raw 不读其它任何文件。
69
+ */
70
+ export const VIDEO_TYPES = new Map([
71
+ ['mp4', 'video/mp4'],
72
+ ['m4v', 'video/mp4'],
73
+ ['webm', 'video/webm'],
74
+ ['mov', 'video/quicktime'],
75
+ ['ogv', 'video/ogg'],
76
+ ])
77
+
78
+ /**
79
+ * **第一批**支持的代码语言(v0.19 需求 §4)。
80
+ *
81
+ * 严格控制范围是这一版的设计目标之一:先验证「代码上下文有没有用」,
82
+ * 而不是「支持了多少语言」。所以 `.go` / `.rs` / `.java` / `.kt` / `.c` / `.cpp` /
83
+ * `.h` / `.hpp` / `.cs` / `.php` / `.rb` / `.swift` / `.sql` **刻意不在表里**。
84
+ *
85
+ * `language` 是给界面显示徽章用的稳定标识,不是语法分析结论 —— Knit 不做 AST。
86
+ */
87
+ export const CODE_LANGUAGES = new Map([
88
+ ['js', 'javascript'],
89
+ ['mjs', 'javascript'],
90
+ ['cjs', 'javascript'],
91
+ ['ts', 'typescript'],
92
+ ['tsx', 'tsx'],
93
+ ['jsx', 'jsx'],
94
+ ['py', 'python'],
95
+ ['json', 'json'],
96
+ ['html', 'html'],
97
+ ['htm', 'html'],
98
+ ['css', 'css'],
99
+ ['scss', 'scss'],
100
+ ['yaml', 'yaml'],
101
+ ['yml', 'yaml'],
102
+ ['sh', 'shell'],
103
+ ['bash', 'shell'],
104
+ ['zsh', 'shell'],
105
+ ])
106
+
107
+ /**
108
+ * 明确**不支持**的代码扩展名(v0.19 需求 §5)。
109
+ *
110
+ * 存在的意义不是分类(它们本来就落到 `ignored`),而是给测试和文档一个
111
+ * 可引用的名单:**这是被决定的边界,不是被忘掉的东西。**
112
+ */
113
+ export const UNSUPPORTED_CODE_EXTENSIONS = new Set([
114
+ 'go', 'rs', 'java', 'kt', 'c', 'cpp', 'h', 'hpp', 'cs', 'php', 'rb', 'swift', 'sql',
115
+ ])
116
+
117
+ /** 锁文件:文件名级判定(`package-lock.json` 的扩展名是 `json`,只看扩展名会漏)。 */
118
+ const LOCK_FILES = new Set([
119
+ 'package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'pnpm-lock.yml',
120
+ 'bun.lockb', 'bun.lock', 'composer.lock', 'cargo.lock', 'gemfile.lock', 'poetry.lock',
121
+ 'pipfile.lock',
122
+ ])
123
+
124
+ /** 压缩产物:`foo.min.js` / `foo.min.css`。 */
125
+ const MINIFIED_RE = /\.min\.(?:js|cjs|mjs|css)$/
126
+ /** 打包产物:`foo.bundle.js`。 */
127
+ const BUNDLE_RE = /\.bundle\.(?:js|cjs|mjs)$/
128
+ /** 生成产物:`foo.generated.js` / `foo.gen.js`。 */
129
+ const GENERATED_RE = /\.(?:generated|gen)\.(?:js|cjs|mjs|ts|tsx|jsx|css)$/
130
+
131
+ /**
132
+ * 取文件名的最后一段(同时容忍传进来的是相对路径或绝对路径)。
133
+ * @param {string} name - 文件名或路径
134
+ * @returns {string} 文件名
135
+ */
136
+ function baseName(name) {
137
+ const text = String(name == null ? '' : name)
138
+ const cut = Math.max(text.lastIndexOf('/'), text.lastIndexOf('\\'))
139
+ return cut >= 0 ? text.slice(cut + 1) : text
140
+ }
141
+
142
+ /**
143
+ * 取小写扩展名(无扩展名返回空串)。
144
+ * @param {string} base - 文件名
145
+ * @returns {string} 扩展名
146
+ */
147
+ function extName(base) {
148
+ const dot = base.lastIndexOf('.')
149
+ if (dot <= 0 || dot === base.length - 1) return ''
150
+ return base.slice(dot + 1).toLowerCase()
151
+ }
152
+
153
+ /**
154
+ * 造一条分类结果。字段固定,避免调用方拿到 undefined 再各自兜底。
155
+ * @param {string} kind - 产物类型
156
+ * @param {string|null} language - 语言标识(没有就 null)
157
+ * @param {{previewable?:boolean, searchable?:boolean, contextual?:boolean,
158
+ * generated?:boolean, sourceMap?:boolean}} flags - 三个能力位与两个标记
159
+ * @returns {object} 分类结果
160
+ */
161
+ function record(kind, language, flags) {
162
+ return {
163
+ kind,
164
+ language: language || null,
165
+ previewable: flags.previewable !== false,
166
+ searchable: flags.searchable === true,
167
+ contextual: flags.contextual === true,
168
+ generated: flags.generated === true,
169
+ sourceMap: flags.sourceMap === true,
170
+ }
171
+ }
172
+
173
+ /** 生成/噪声产物:可预览,绝不进检索与上下文。 */
174
+ function generated(language, sourceMap = false) {
175
+ return record(KIND_GENERATED, language, {
176
+ previewable: true, searchable: false, contextual: false, generated: true, sourceMap,
177
+ })
178
+ }
179
+
180
+ /**
181
+ * 判定一个文件属于哪一类、能用来做什么。
182
+ *
183
+ * 顺序是**判定的一部分**,不能重排:生成规则必须在代码白名单之前
184
+ * (`app.min.js` 的扩展名也是 `js`),文件名级规则必须在扩展名规则之前
185
+ * (`package-lock.json` 的扩展名也是 `json`)。
186
+ *
187
+ * @param {string} name - 文件名(也接受路径,只取最后一段)
188
+ * @returns {{kind:string, language:string|null, previewable:boolean, searchable:boolean,
189
+ * contextual:boolean, generated:boolean, sourceMap:boolean}} 分类结果
190
+ */
191
+ export function classifyFile(name) {
192
+ const base = baseName(name).toLowerCase()
193
+ const ext = extName(base)
194
+
195
+ // ① 生成 / 噪声产物:可预览,但不进检索、不进上下文、不进列表。
196
+ if (ext === 'map') return generated(null, true)
197
+ if (ext === 'lock' || LOCK_FILES.has(base)) return generated(null)
198
+ if (MINIFIED_RE.test(base) || BUNDLE_RE.test(base) || GENERATED_RE.test(base)) {
199
+ return generated(CODE_LANGUAGES.get(ext) || null)
200
+ }
201
+
202
+ // ② Markdown 文档。
203
+ if (ext === 'md') {
204
+ return record(KIND_DOCUMENT, 'markdown', {
205
+ previewable: true, searchable: true, contextual: true,
206
+ })
207
+ }
208
+
209
+ // ③ 代码(第一批白名单)。
210
+ const language = CODE_LANGUAGES.get(ext)
211
+ if (language) {
212
+ return record(KIND_CODE, language, {
213
+ previewable: true, searchable: true, contextual: true,
214
+ })
215
+ }
216
+
217
+ // ④ 媒体:沿用 v0.18 的行为(可预览、可列出,但不进 BM25 语料)。
218
+ if (IMAGE_TYPES.has(ext)) {
219
+ return record(KIND_IMAGE, null, { previewable: true, searchable: false, contextual: false })
220
+ }
221
+ if (VIDEO_TYPES.has(ext)) {
222
+ return record(KIND_VIDEO, null, { previewable: true, searchable: false, contextual: false })
223
+ }
224
+
225
+ // ⑤ 其余:Knit 不管。
226
+ return record(KIND_IGNORED, null, { previewable: false, searchable: false, contextual: false })
227
+ }
228
+
229
+ /**
230
+ * 这个类型能不能作为 Context Pack 候选(Primary / Supporting / Related)。
231
+ *
232
+ * `all` 档是「文档 + 代码」,媒体沿用 v0.18 —— 媒体不进上下文。
233
+ * @param {string} kind - 产物类型
234
+ * @returns {boolean} 是否可作为上下文候选
235
+ */
236
+ export function isContextKind(kind) {
237
+ return kind === KIND_DOCUMENT || kind === KIND_CODE
238
+ }
239
+
240
+ /**
241
+ * 这个类型能不能被 `/knit/api/doc` 读出来预览。
242
+ *
243
+ * 只放行**文本类**产物:文档、代码、生成产物(`.map` 要能点开看)。
244
+ * 媒体走 `/knit/api/raw`,`ignored` 一律拒绝 —— 这是安全边界,不是能力边界。
245
+ * @param {string} kind - 产物类型
246
+ * @returns {boolean} 是否可预览
247
+ */
248
+ export function isPreviewKind(kind) {
249
+ return kind === KIND_DOCUMENT || kind === KIND_CODE || kind === KIND_GENERATED
250
+ }
@@ -62,9 +62,11 @@
62
62
  *
63
63
  * ## 已知边界(不要读成缺陷报告,是如实记录)
64
64
  *
65
- * - **只看 Markdown。** 工作区里的 `.js` / `.mjs` 是真实存在的「实现 / 测试」,
66
- * 但它们不进语料(v0.14 明确不做源码索引),所以
67
- * 「Supporting = 实现文件」只能由**描述该实现的 Markdown** 承担。
65
+ * - **不做符号级理解。** v0.19 起代码文件可以进语料,但进来的只是
66
+ * 「文件名 + 路径 + 正文前 N 字符」这一层词面信息 —— **没有 AST、没有符号表、
67
+ * 没有调用图**(那是后续 Deep Retrieval 的方向,不是 v0.19)。所以
68
+ * 「Supporting = 实现文件」现在可以由**代码文件本身**承担,但它凭什么进这一层
69
+ * 仍然是 BM25 的命中,不是「谁调用了谁」。
68
70
  * - **不做任务理解。** `task` 字段是**引用**,不是推断:它由调用方传入
69
71
  * (`index.js` 取「最新一条有实质内容的用户消息」原文),本模块只负责透传,
70
72
  * **永远不生成**任务描述 —— 那需要模型,违反约束 1。
@@ -75,6 +77,13 @@
75
77
  * 硬凑一篇「看起来像主文档的」是编造。`MAX_PRIMARY = 1` 是上限,不是指标。
76
78
  */
77
79
 
80
+ // v0.19:理由码要按条目类型分叉(Markdown 说「标题 / 摘要」,代码说「文件名 / 路径」),
81
+ // 所以这里要看条目的 `kind`。**看的是分类层给的常量,不是裸字符串** ——
82
+ // 本文件里出现的单引号字母串会被 `test/i18n.test.mjs` 当作理由码抽出来(那正是它的用途),
83
+ // 在这里写 `doc.kind === 'code'` 会让 `code` 被误认成一个理由码。
84
+ // `classification.js` 零依赖,import 它不会成环。
85
+ import { KIND_CODE } from './classification.js'
86
+
78
87
  /* ── 上限(对外契约的一部分,测试直接断言它们)───────────────── */
79
88
 
80
89
  /**
@@ -217,20 +226,27 @@ function fieldCount(fields) {
217
226
  * 判定顺序是**固定的**,所以同一篇文档每次拿到同一个理由:
218
227
  *
219
228
  * 1. `direct` —— 命中标题,且命中 ≥2 个话题词:作者把它写进标题、你还问了不止一个词
220
- * 2. `titleMatch` —— 命中标题
221
- * 3. `summaryMatch`—— 命中摘要(没有标题命中时)
229
+ * 2. `titleMatch` —— 命中标题(**代码**文件名沿用同一条判据,码是 `filenameMatch`)
230
+ * 3. `summaryMatch`—— 命中摘要(没有标题命中时;**代码**的「摘要」是所在目录,
231
+ * 码是 `pathMatch`)
222
232
  * 4. `bodyMatch` —— 只在正文命中(`fields` 是**焦点词**的正文命中个数,能区分
223
233
  * 「真的在讲」与「正文里蹭了一下」,且不暴露 BM25 分数)
224
234
  * 5. `linkTarget` —— 被某个 Primary 引用
225
235
  * 6. `linkSource` —— 引用了某个 Primary
226
236
  * 7. `related` —— 兜底:名次靠后的命中项
227
237
  *
228
- * @param {object} doc - 记录(`{rel, matchedTerms}`;`matchedTerms[].fields` 是字段位图)
238
+ * v0.19 给代码换的只是**两个码的名字**,不是两套判据 —— 命中位置完全一样
239
+ * (文件名占的是 `title` 槽、目录占的是 `summary` 槽,见 `index.js` 的 `readCode()`)。
240
+ * 换名字是为了让界面能说人话:对 `context-manager.ts` 说「标题命中」是错的,
241
+ * 它的「标题」就是文件名。**判据没有分叉,只有称谓分叉。**
242
+ *
243
+ * @param {object} doc - 记录(`{rel, kind, matchedTerms}`;`matchedTerms[].fields` 是字段位图)
229
244
  * @param {{linkTarget?:boolean, linkSource?:boolean}} [links] - 与 Primary 的关系
230
245
  * @returns {{code:string, terms:string[], fields:number, term:string}} 理由
231
246
  */
232
247
  export function explainContext(doc, links = {}) {
233
248
  const terms = Array.isArray(doc && doc.matchedTerms) ? doc.matchedTerms : []
249
+ const isCode = Boolean(doc && doc.kind === KIND_CODE)
234
250
  const names = terms.map((t) => t.term)
235
251
  const merged = { title: false, summary: false, body: false }
236
252
  let titleTerm = ''
@@ -254,14 +270,16 @@ export function explainContext(doc, links = {}) {
254
270
 
255
271
  if (merged.title) {
256
272
  return {
257
- code: merged.title && names.length >= 2 ? 'direct' : 'titleMatch',
273
+ code: merged.title && names.length >= 2
274
+ ? 'direct'
275
+ : (isCode ? 'filenameMatch' : 'titleMatch'),
258
276
  terms: names,
259
277
  fields: total,
260
278
  term: titleTerm || names[0] || '',
261
279
  }
262
280
  }
263
281
  if (merged.summary) {
264
- return { code: 'summaryMatch', terms: names, fields: total, term: names[0] || '' }
282
+ return { code: isCode ? 'pathMatch' : 'summaryMatch', terms: names, fields: total, term: names[0] || '' }
265
283
  }
266
284
  if (names.length > 0) {
267
285
  return { code: 'bodyMatch', terms: names, fields: bodyHits, term: bodyTerm || names[0] }
@@ -278,7 +296,11 @@ export function explainContext(doc, links = {}) {
278
296
  const REASON_ORDER = {
279
297
  direct: 0,
280
298
  titleMatch: 1,
299
+ // 代码的「文件名命中」与 Markdown 的「标题命中」是同一条判据(见 `explainContext()`),
300
+ // 所以强弱同级 —— 不能因为它是代码就排前面或后面。
301
+ filenameMatch: 1,
281
302
  summaryMatch: 2,
303
+ pathMatch: 2,
282
304
  bodyMatch: 3,
283
305
  linkTarget: 4,
284
306
  linkSource: 5,
@@ -509,7 +531,7 @@ export function buildContext(input = {}) {
509
531
  kind: record.kind,
510
532
  source: record.source,
511
533
  reason: explainContext(
512
- { rel: record.rel, matchedTerms: record.termFields },
534
+ { rel: record.rel, kind: record.kind, matchedTerms: record.termFields },
513
535
  entry,
514
536
  ),
515
537
  }