✨ feat(vscode): 代码阅读加异常卡片，Python、TypeScript 的异常类画成同一张表（属性、构造参数），方法照常是子块

vscode/src/codeReader/contract.ts

@@ -4,7 +4,7 @@ import type { Disposable } from 'vscode'
 export type { Node }
 
 export type BlockKind
-  = | 'import' | 'function' | 'class' | 'enum' | 'type' | 'field' | 'const' | 'variable'
+  = | 'import' | 'function' | 'class' | 'enum' | 'exception' | 'type' | 'field' | 'const' | 'variable'
     | 'if' | 'else' | 'loop' | 'try' | 'catch' | 'finally' | 'return' | 'statement' | 'comment'
 
 /** 源码里一段的下标：源码字符串下标（web-tree-sitter 的 startIndex / endIndex），end 为开区间。 */
@@ -101,6 +101,35 @@ export interface EnumFacts {
   members: EnumMemberFacts[]
 }
 
+/** 异常类的一个类属性：Python 类主体里给一个名字赋值的语句（带不带注解、有没有值），TypeScript 的类字段（含 static）；节点都指向源码。 */
+export interface FieldFacts {
+  name: Node
+  type?: Node
+  value?: Node
+  /** 属性的说明文字节点，同 EnumMemberFacts.docs：紧挨在上面单独成行的注释 / JSDoc、这一行行尾的注释、Python 紧跟在后面的属性 docstring。 */
+  docs: Node[]
+}
+
+/**
+ * 异常类：父类是语言自带的异常类、同一文件里认出来的异常类，或名字按命名习惯以 Error / Exception（Python 还有 Warning）结尾。
+ * Python、TypeScript 都由语言插件报，同一种块、同一张属性表。块的头部是整个类（类属性在属性表里讲），留下的方法等是子块。
+ */
+export interface ExceptionFacts {
+  /** 同 ClassFacts.name。 */
+  name?: Node
+  /** 同 ClassFacts.doc。 */
+  doc?: Node
+  /** 同 ClassFacts.access。 */
+  access?: Access
+  decorators: Node[]
+  /** 照源码写的父类，同 ClassFacts.bases。 */
+  bases: BaseFacts[]
+  /** 类属性，照源码顺序。 */
+  fields: FieldFacts[]
+  /** 构造函数的参数（Python 的 `__init__` 去掉 self，TypeScript 的 `constructor(...)`）；类里没写构造函数时没有。 */
+  parameters?: ParameterFacts[]
+}
+
 /** 导入的一项。 */
 export type ImportItem
   = | { kind: 'named', name: Node, alias?: Node } // import { a as b }、from m import a as b
@@ -176,7 +205,7 @@ export interface VariableFacts {
  * - kind：块的种类（BlockKind）；
  * - access：访问级别，'public' | 'private' | 'protected'，语言可以加自己的值（Kotlin 的 'internal'，见 BlockShape.attributes）；
  * - async、abstract、typeOnly：异步、抽象、仅类型，值是 'true' | 'false'。
- * 宿主从块的 kind 和 facts 推出它们（FunctionFacts.access / async、ClassFacts.access / abstract、EnumFacts.access、ImportFacts.typeOnly、VariableFacts.access），
+ * 宿主从块的 kind 和 facts 推出它们（FunctionFacts.access / async、ClassFacts.access / abstract、EnumFacts.access、ExceptionFacts.access、ImportFacts.typeOnly、VariableFacts.access），
  * 语言插件不用另报；facts 里没填的（语言没有这个概念、块没有这一项），块就没有这个属性，也不受这个属性的筛选影响。
  */
 export const COMMON_ATTRIBUTES = ['kind', 'access', 'async', 'abstract', 'typeOnly'] as const
@@ -207,12 +236,14 @@ export interface FunctionBlock extends BlockShape { kind: 'function', facts: Fun
 export interface ClassBlock extends BlockShape { kind: 'class', facts: ClassFacts }
 /** 枚举块的头部是整个枚举（成员都在属性表里讲），没有子块；库规则认出来的枚举（Python）是整个类，留下的方法等是子块。 */
 export interface EnumBlock extends BlockShape { kind: 'enum', facts: EnumFacts }
+/** 异常块的头部是整个类（类属性都在属性表里讲），留下的方法（含构造函数）等是子块。 */
+export interface ExceptionBlock extends BlockShape { kind: 'exception', facts: ExceptionFacts }
 export interface ImportBlock extends BlockShape { kind: 'import', facts: ImportFacts }
 export interface VariableBlock extends BlockShape { kind: 'const' | 'variable', facts: VariableFacts }
-export type FactBlock = FunctionBlock | ClassBlock | EnumBlock | ImportBlock | VariableBlock
+export type FactBlock = FunctionBlock | ClassBlock | EnumBlock | ExceptionBlock | ImportBlock | VariableBlock
 
 /** 带说明（facts.doc）的块。 */
-export type DocumentedBlock = FunctionBlock | ClassBlock | EnumBlock | VariableBlock
+export type DocumentedBlock = FunctionBlock | ClassBlock | EnumBlock | ExceptionBlock | VariableBlock
 
 /** 属性表块的种类和 facts，不带块的形状（节点、头部、子块）：库规则把一块认成现成的一种属性表块时给它（RuleFacts）。 */
 export type BlockFacts = FactBlock extends infer B ? B extends FactBlock ? Pick<B, 'kind' | 'facts'> : never : never