🐛 fix(vscode): 代码阅读把 Python 赋值后面的字符串当变量说明，其余单独的字符串显示成注释

vscode/src/codeReader/languages/python.test.ts

@@ -1,7 +1,7 @@
 import type { IterationFacts, Node } from '../contract'
 import type { Outline } from '../testSupport'
 import { describe, expect, it } from 'vitest'
-import { factsByLine, nodesToText, outline, readFixture, runtime, WASM_DIR, withBlocks } from '../testSupport'
+import { factsByLine, nodesToText, outline, readFixture, runtime, walk, WASM_DIR, withBlocks } from '../testSupport'
 import { createPythonAdapter } from './python'
 
 const adapter = createPythonAdapter(WASM_DIR)
@@ -79,15 +79,89 @@ describe('python 代码块树', () => {
     ])
   })
 
-  it('docstring 只认主体开头；不是开头的字符串表达式是语句', async () => {
+  it('docstring 只认主体开头；不是开头、也没挂到赋值上的字符串是注释块，f-string、字节串照旧是语句', async () => {
     const source = [
       'def f():',
       '    x = 1',
       '    """not a docstring"""',
+      '    "a" \'b\'',
+      '    f"{x}"',
+      '    b"x"',
+      '    "a" f"b"',
     ].join('\n')
     expect(await tree(source)).toEqual([
-      { at: 1, kind: 'function', kids: [{ at: 2, kind: 'variable' }, { at: 3, kind: 'statement' }] },
+      { at: 1, kind: 'function', kids: [
+        { at: 2, kind: 'variable' },
+        { at: 3, kind: 'comment' },
+        { at: 4, kind: 'comment' },
+        { at: 5, kind: 'statement' },
+        { at: 6, kind: 'statement' },
+        { at: 7, kind: 'statement' },
+      ] },
     ])
+    expect(await tree('def f(): f"not a docstring"')).toEqual([{ at: 1, kind: 'function', kids: [{ at: 1, kind: 'statement' }] }])
+  })
+})
+
+describe('python 属性 docstring', () => {
+  /** 字段（一行译文的块）的说明，按 header 起始行（1 起）索引。 */
+  function fieldDocs(source: string): Promise<Record<number, unknown>> {
+    return withBlocks(adapter, 'python', source, (blocks) => {
+      const byLine: Record<number, unknown> = {}
+      walk(blocks, (block) => {
+        if (block.kind === 'field' && block.doc)
+          byLine[block.header.startRow + 1] = nodesToText(block.doc)
+      })
+      return byLine
+    })
+  }
+
+  it('attributeDocs.py：模块、类主体里紧跟在赋值后面的字符串并进那块，头部延到字符串结尾；隔着注释、不跟在赋值后面的是注释块', async () => {
+    expect(await tree(readFixture('attributeDocs.py'))).toEqual([
+      { at: 1, kind: 'comment' },
+      { at: [3, 4], kind: 'const' },
+      { at: [6, 8], kind: 'variable' },
+      { at: [11, 12], kind: 'class', kids: [
+        { at: [14, 15], kind: 'variable' },
+        { at: [17, 19], kind: 'field' },
+        { at: 21, kind: 'comment' },
+        { at: 22, kind: 'comment' },
+      ] },
+      { at: 25, kind: 'function', kids: [
+        { at: 26, kind: 'variable' },
+        { at: [27, 30], kind: 'comment' },
+        { at: 31, kind: 'statement' },
+        { at: 32, kind: 'statement' },
+        { at: 33, kind: 'return' },
+      ] },
+    ])
+  })
+
+  it('进常量、变量的 facts.doc 和字段的 doc，是那个字符串节点；函数体里的赋值没有', async () => {
+    const source = readFixture('attributeDocs.py')
+    const found = await facts(source)
+    expect(found[3]).toMatchObject({ doc: '"""一 deployment 一案例的唯一约束名; 入库侧按它认"重复入库", 故与建表同源。"""' })
+    expect(found[6]).toMatchObject({ doc: '"""隔着空行、赋值行尾有注释也算。"""' })
+    expect(found[14]).toMatchObject({ doc: '"""正在分析源 deployment."""' })
+    expect(found[26]).not.toHaveProperty('doc')
+    expect(await fieldDocs(source)).toEqual({ 17: '"""案例标题,\n    用户可编辑."""' })
+  })
+
+  it('只挂到紧跟着的下一条语句：两个字符串只有第一个是说明；没有值的注解、拼接的字符串也算；条件分支里的赋值不算', async () => {
+    const source = [
+      'class K:',
+      '    a: int',
+      '    "A" "B"',
+      '    "又一个"',
+      'if DEBUG:',
+      '    X = 1',
+      '    """不算"""',
+    ].join('\n')
+    expect(await tree(source)).toEqual([
+      { at: 1, kind: 'class', kids: [{ at: [2, 3], kind: 'field' }, { at: 4, kind: 'comment' }] },
+      { at: 5, kind: 'if', kids: [{ at: 6, kind: 'variable' }, { at: 7, kind: 'comment' }] },
+    ])
+    expect(await fieldDocs(source)).toEqual({ 2: '"A" "B"' })
   })
 })
 

vscode/src/codeReader/languages/python.ts

@@ -9,11 +9,41 @@ type Scope = 'module' | 'class' | 'other'
 const CONSTANT_NAME = /^[A-Z][A-Z0-9_]*$/
 const PARAMETER_SEPARATORS = new Set(['keyword_separator', 'positional_separator'])
 const PATTERNS = new Set(['pattern_list', 'tuple_pattern', 'list_pattern'])
+/** 字符串开头（string_start）：普通字符串的前缀只有 r / u 或没有；f、t、b 开头的不是。 */
+const STRING_PREFIX = /^[ru]?["']/i
 // 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释
 const COMMENTS: CommentRules = { isLine: () => true, isDoc: () => false }
 
-function statements(items: Node[], scope: Scope, afterRow: number, docstring: boolean): CodeBlock[] {
-  return listBlocks(items, afterRow, (item, first) => statementBlocks(item, scope, docstring && first), COMMENTS)
+function statements(items: Node[], scope: Scope, afterRow: number): CodeBlock[] {
+  const docs = attributeDocs(items, scope)
+  const attached = new Set([...docs.values()].map(statement => statement.startIndex))
+  return listBlocks(items, afterRow, (item) => {
+    if (attached.has(item.startIndex))
+      return []
+    const docStatement = docs.get(item.startIndex)
+    return statementBlocks(item, scope, docStatement && docstringIn(docStatement))
+  }, COMMENTS)
+}
+
+/**
+ * 属性 docstring（PEP 257）：模块、类主体里紧跟在一条赋值后面的字符串是这个变量的说明。返回赋值语句的起始下标 → 那条字符串语句。
+ * 同 JSDoc 挂到下一条语句：中间可以隔空行和赋值的行尾注释，隔着别的注释、语句就不算。
+ */
+function attributeDocs(items: Node[], scope: Scope): Map<number, Node> {
+  const docs = new Map<number, Node>()
+  if (scope === 'other')
+    return docs
+  items.forEach((item, i) => {
+    if (!assignmentIn(item))
+      return
+    let next = i + 1
+    while (items[next]?.type === 'comment' && items[next].startPosition.row === item.endPosition.row)
+      next++
+    const statement = items[next]
+    if (statement && docstringIn(statement))
+      docs.set(item.startIndex, statement)
+  })
+  return docs
 }
 
 /** 冒号后面的主体：body / consequence 字段，except / finally 子句里是不带字段名的 block。 */
@@ -25,17 +55,18 @@ function bodyOf(node: Node): Node | null {
   return blocks.at(-1) ?? null
 }
 
-function bodyShape(outer: Node, body: Node | null, scope: Scope, docstring = false): BlockShape {
+function bodyShape(outer: Node, body: Node | null, scope: Scope): BlockShape {
   if (!body)
     return leafShape(outer)
-  return compoundShape(outer, body.startIndex, named(body), (list, afterRow) => statements(list, scope, afterRow, docstring))
+  return compoundShape(outer, body.startIndex, named(body), (list, afterRow) => statements(list, scope, afterRow))
 }
 
 function bodyBlock(kind: TextKind, outer: Node, body: Node | null, scope: Scope): CodeBlock {
   return { kind, ...bodyShape(outer, body, scope) }
 }
 
-function statementBlocks(node: Node, scope: Scope, docstring: boolean): CodeBlock[] {
+/** doc 是紧跟在这条赋值后面的属性 docstring（见 attributeDocs）。 */
+function statementBlocks(node: Node, scope: Scope, doc: Node | undefined): CodeBlock[] {
   switch (node.type) {
     case 'import_statement':
     case 'import_from_statement':
@@ -64,7 +95,7 @@ function statementBlocks(node: Node, scope: Scope, docstring: boolean): CodeBloc
     case 'return_statement':
       return [leafBlock('return', node)]
     case 'expression_statement':
-      return [expressionBlock(node, scope, docstring)]
+      return [expressionBlock(node, scope, doc)]
     default:
       return [leafBlock('statement', node)]
   }
@@ -87,18 +118,30 @@ function docstringOf(body: Node | null): Node | undefined {
   return first && docstringIn(first)
 }
 
-/** 语句是单独一个字符串表达式（docstring 的写法）时返回那个字符串节点。 */
+/**
+ * 语句是单独一个字符串字面量（docstring 的写法，隐式拼接的几段也算）时返回那个字符串节点。
+ * f-string、t-string、字节串不算：Python 不把它们当 docstring。
+ */
 function docstringIn(statement: Node): Node | undefined {
   if (statement.type !== 'expression_statement')
     return undefined
   const [expression, ...rest] = named(statement)
-  return rest.length === 0 && (expression?.type === 'string' || expression?.type === 'concatenated_string') ? expression : undefined
+  if (!expression || rest.length > 0)
+    return undefined
+  const parts = expression.type === 'concatenated_string' ? named(expression) : [expression]
+  return parts.every(isTextString) ? expression : undefined
+}
+
+/** 普通字符串字面量：前缀只有 r / u（不分大小写）或没有。 */
+function isTextString(node: Node): boolean {
+  const start = node.type === 'string' ? node.firstChild : null
+  return start?.type === 'string_start' && STRING_PREFIX.test(start.text)
 }
 
 /** 函数、类的 docstring 是它自己的说明：算进头部（连同它前面的注释），子块从它后面开始。 */
 function documentedShape(outer: Node, body: Node, doc: Node, scope: Scope): BlockShape {
   const rest = named(body).filter(item => item.startIndex >= doc.endIndex)
-  return compoundShape(outer, doc.endIndex, rest, (list, afterRow) => statements(list, scope, afterRow, false))
+  return compoundShape(outer, doc.endIndex, rest, (list, afterRow) => statements(list, scope, afterRow))
 }
 
 /** 单下划线开头的名字是私有（`_x`、`__x`），前后双下划线的特殊方法（`__init__`）是公共。 */
@@ -219,28 +262,40 @@ function isConstantTarget(target: Node | null): boolean {
   return false
 }
 
-/** 赋值 → 字段 / 常量 / 变量；主体开头的字符串是 docstring；其余表达式是语句。 */
-function expressionBlock(node: Node, scope: Scope, docstring: boolean): CodeBlock {
-  if (docstring && docstringIn(node))
+/**
+ * 赋值 → 字段 / 常量 / 变量，doc 是它的属性 docstring：进字段的 doc、常量和变量的 facts.doc，头部往下延到字符串结尾；
+ * 单独一个字符串（模块开头的 docstring、写在语句中间当注释用的字符串）是注释；其余表达式是语句。
+ */
+function expressionBlock(node: Node, scope: Scope, doc: Node | undefined): CodeBlock {
+  if (docstringIn(node))
     return leafBlock('comment', node)
-  const expression = named(node)[0]
-  const left = expression?.type === 'assignment' ? expression.childForFieldName('left') : null
+  const expression = assignmentIn(node)
+  const left = expression?.childForFieldName('left')
   if (!expression || !left)
     return leafBlock('statement', node)
+  const leaf = leafShape(node)
+  const shape = doc ? { ...leaf, header: { ...leaf.header, endIndex: doc.endIndex, endRow: doc.endPosition.row } } : leaf
   const type = expression.childForFieldName('type')
   if (scope === 'class' && type)
-    return leafBlock('field', node)
+    return { kind: 'field', ...shape, doc }
   const value = expression.childForFieldName('right')
   return {
     kind: scope === 'module' && isConstantTarget(left) ? 'const' : 'variable',
-    ...leafShape(node),
+    ...shape,
     facts: {
       access: scopeAccess(left, scope),
+      doc,
       declarators: [{ name: left, type: type ?? undefined, value: value ?? undefined, entries: dictionaryEntries(value) }],
     },
   }
 }
 
+/** 语句是一条赋值（带不带注解、有没有值）时返回那个 assignment 节点。 */
+function assignmentIn(statement: Node): Node | undefined {
+  const expression = statement.type === 'expression_statement' ? named(statement)[0] : undefined
+  return expression?.type === 'assignment' ? expression : undefined
+}
+
 /** 字典字面量的各项：`键: 值`（值又是字典时连它的各项）、`**other`；值不是字典字面量时没有。 */
 function dictionaryEntries(value: Node | null): EntryFacts[] | undefined {
   if (value?.type !== 'dictionary')
@@ -428,7 +483,7 @@ export function createPythonAdapter(wasmDir: string): LanguageAdapter {
     id: 'python',
     languageIds: ['python'],
     grammarPath: () => path.join(wasmDir, 'tree-sitter-python.wasm'),
-    toBlocks: root => statements(named(root), 'module', -1, true),
+    toBlocks: root => statements(named(root), 'module', -1),
     tokenRole: pythonTokenRole,
     iteration: pythonIteration,
   }

vscode/src/codeReader/languages/shared.ts

@@ -104,19 +104,18 @@ function documented<B extends DocumentedBlock>(block: B, doc: Node): B {
  * 文档注释和下一条语句之间只有空白、下一条语句是函数或类块时，它是这个函数、类的说明，不单独成块；
  * 中间隔着的装饰器（不出块的语句）不算隔开。
  * afterRow 是这串语句之前的最后一行（头部结尾行），模块顶层传 -1；
- * toBlocks 的 first 表示它是这串里第一条非注释语句（Python 认 docstring 用）。
+ * toBlocks 可以返回空数组：这条语句不出块（装饰器、并进上一块的属性 docstring），和它同一行的注释照样算行尾注释。
  */
 export function listBlocks(
   items: Node[],
   afterRow: number,
-  toBlocks: (item: Node, first: boolean) => CodeBlock[],
+  toBlocks: (item: Node) => CodeBlock[],
   comments: CommentRules,
 ): CodeBlock[] {
   const out: CodeBlock[] = []
   let lastRow = afterRow
   let lineRun: CodeBlock | undefined
   let doc: Node | undefined
-  let first = true
   const flushDoc = (): void => {
     if (doc)
       out.push(leafBlock('comment', doc))
@@ -143,7 +142,7 @@ export function listBlocks(
       }
     }
     else {
-      const blocks = toBlocks(item, first)
+      const blocks = toBlocks(item)
       const [head] = blocks
       if ((head?.kind === 'function' || head?.kind === 'class') && doc) {
         blocks[0] = documented(head, doc)
@@ -153,7 +152,6 @@ export function listBlocks(
         flushDoc()
       }
       out.push(...blocks)
-      first = false
       lineRun = undefined
     }
     lastRow = item.endPosition.row

vscode/src/codeReader/languages/typescript.test.ts

@@ -224,6 +224,23 @@ describe('typeScript 代码块树', () => {
       { at: 6, kind: 'statement' },
     ])
   })
+
+  it('单独一个字符串的语句（\'use strict\' 这类指令，赋值后面的字符串）照旧是语句，不挂到赋值上', async () => {
+    const source = [
+      '\'use strict\'',
+      'const x = 1',
+      '\'not a doc\'',
+      'function f() {',
+      '  \'use client\'',
+      '}',
+    ].join('\n')
+    expect(await tree(source, 'javascript')).toEqual([
+      { at: 1, kind: 'statement' },
+      { at: 2, kind: 'const' },
+      { at: 3, kind: 'statement' },
+      { at: 4, kind: 'function', kids: [{ at: 5, kind: 'statement' }] },
+    ])
+  })
 })
 
 describe('typeScript 函数的 JSDoc', () => {