✨ feat(vscode): 代码阅读类块改成属性表并默认折叠，类的说明进「说明」行

vscode/src/codeReader/languages/python.ts

@@ -1,4 +1,4 @@
-import type { Access, BlockShape, CodeBlock, FunctionFacts, ImportFacts, ImportItem, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
+import type { Access, BlockShape, ClassFacts, CodeBlock, FunctionFacts, ImportFacts, ImportItem, LanguageAdapter, Node, ParameterFacts, TextKind, TokenRole } from '../contract'
 import type { CommentRules } from './shared'
 import * as path from 'node:path'
 import { children, compoundShape, leafBlock, leafShape, listBlocks, named, sameNode, syntaxChildren } from './shared'
@@ -9,7 +9,7 @@ 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'])
-// 只有 # 行注释；函数的说明是主体开头的 docstring，不是写在前面的注释
+// 只有 # 行注释；函数、类的说明是主体开头的 docstring，不是写在前面的注释
 const COMMENTS: CommentRules = { isLine: () => true, isDoc: () => false }
 
 function statements(items: Node[], scope: Scope, afterRow: number, docstring: boolean): CodeBlock[] {
@@ -73,14 +73,12 @@ function statementBlocks(node: Node, scope: Scope, docstring: boolean): CodeBloc
 /** function_definition / class_definition；outer 是带装饰器的整体时头部从装饰器开始。 */
 function definitionBlock(definition: Node, outer: Node, scope: Scope): CodeBlock {
   const body = definition.childForFieldName('body')
-  if (definition.type === 'class_definition')
-    return { kind: 'class', ...bodyShape(outer, body, 'class', true) }
   const doc = docstringOf(body)
-  return {
-    kind: 'function',
-    ...(body && doc ? documentedShape(outer, body, doc) : bodyShape(outer, body, 'other')),
-    facts: functionFacts(definition, outer, scope, doc),
-  }
+  const inner: Scope = definition.type === 'class_definition' ? 'class' : 'other'
+  const shape = body && doc ? documentedShape(outer, body, doc, inner) : bodyShape(outer, body, inner)
+  if (definition.type === 'class_definition')
+    return { kind: 'class', ...shape, facts: classFacts(definition, outer, scope, doc) }
+  return { kind: 'function', ...shape, facts: functionFacts(definition, outer, scope, doc) }
 }
 
 /** 主体开头的 docstring：第一条语句（注释不算）是单独一个字符串表达式时，返回那个字符串节点。 */
@@ -97,10 +95,10 @@ function docstringIn(statement: Node): Node | undefined {
   return rest.length === 0 && (expression?.type === 'string' || expression?.type === 'concatenated_string') ? expression : undefined
 }
 
-/** 函数的 docstring 是它自己的说明：算进头部（连同它前面的注释），子块从它后面开始。 */
-function documentedShape(outer: Node, body: Node, doc: Node): BlockShape {
+/** 函数、类的 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, 'other', afterRow, false))
+  return compoundShape(outer, doc.endIndex, rest, (list, afterRow) => statements(list, scope, afterRow, false))
 }
 
 /** 单下划线开头的名字是私有（`_x`、`__x`），前后双下划线的特殊方法（`__init__`）是公共。 */
@@ -140,7 +138,7 @@ function functionFacts(definition: Node, outer: Node, scope: Scope, doc: Node |
     doc,
     access: name ? scopeAccess(name, scope) : undefined,
     async: children(definition).some(child => child.type === 'async'),
-    decorators: named(outer).filter(child => child.type === 'decorator'),
+    decorators: decoratorsOf(outer),
     parameters: syntaxChildren(definition.childForFieldName('parameters'))
       .filter(param => !PARAMETER_SEPARATORS.has(param.type))
       .map(parameterFacts),
@@ -148,6 +146,26 @@ function functionFacts(definition: Node, outer: Node, scope: Scope, doc: Node |
   }
 }
 
+/** 父类是类名后面括号里的参数列表，照写的顺序一项一项取，`metaclass=…` 这类关键字参数也在里面。 */
+function classFacts(definition: Node, outer: Node, scope: Scope, doc: Node | undefined): ClassFacts {
+  const name = definition.childForFieldName('name')
+  return {
+    name: name ?? undefined,
+    doc,
+    access: name ? scopeAccess(name, scope) : undefined,
+    decorators: decoratorsOf(outer),
+    // Python 3.12 的 `class G[T]:`
+    typeParameters: syntaxChildren(definition.childForFieldName('type_parameters')),
+    bases: syntaxChildren(definition.childForFieldName('superclasses')).map(value => ({ value })),
+    implements: [],
+  }
+}
+
+/** 装饰器在 decorated_definition 里，和被装饰的定义是兄弟节点。 */
+function decoratorsOf(outer: Node): Node[] {
+  return named(outer).filter(child => child.type === 'decorator')
+}
+
 /** 带注解的参数（typed_parameter）语法没给名字起字段名，名字是第一个具名子节点（可能是 `*args`）。 */
 function parameterFacts(param: Node): ParameterFacts {
   switch (param.type) {
@@ -301,6 +319,9 @@ function identifierRole(leaf: Node): TokenRole {
     return 'function'
   if (parent.type === 'class_definition' && sameNode(parent.childForFieldName('name'), leaf))
     return 'type'
+  // 父类：类名后面括号里直接写的名字
+  if (parent.type === 'argument_list' && parent.parent?.type === 'class_definition')
+    return 'type'
   if (parent.type === 'decorator' || isCallee(leaf))
     return 'function'
   if (parent.type === 'attribute' && sameNode(parent.childForFieldName('attribute'), leaf) && isCallee(parent))