An toàn kiểu

Đầu vào là mã đã viết xong — một tệp, một mẩu diff. Đầu ra là một phán quyết: tệp có nằm trong phạm vi hay không, rule đã xuất bản nào nổ, nó báo cái gì và ở nút nào, mã luật tương ứng là mã nào, và cửa còn mở nào lẽ ra đã che đúng lỗi ấy. Mô-đun này không chọn gì cả. Nó từ chối, và nó phải chỉ được ra đúng ký tự mà nó từ chối.

Luật

Hệ kiểu là phần canon mà máy giữ hộ mà không cần ai nhắc. Phần lớn các luật khác được giữ bằng một union đóng hoặc một alias kiểu chứ không phải bằng rule — nghĩa là giá trị của hệ kiểu ở đây không phải “ít bug hơn” một cách chung chung, mà là phần lớn canon thôi không còn là tuỳ chọn nữa. Vì thế rule ở tầng này chỉ có một việc: canh những chỗ có người tắt hệ kiểu đi.

Mô-đun này không chép lại luật. Nó ghi lại việc thi hành: máy nhìn thấy đúng cú pháp nào, và — phần không ai chịu viết ra — cùng một phép xoá ấy còn viết được bằng những cách nào mà máy hoàn toàn không thấy.

Luật nêu năm mã. Đúng một mã có rule, và một mã thứ hai được giữ dưới dạng sự vắng mặt của chính rule ấy trên một tập tên tệp. Mô-đun rule nói rõ vì sao nó ở một mình: dạng viết tắt của phép xoá kiểu và cách viết mảng đã có rule của bộ plugin TypeScript lo, mà chép lại rule của người khác thì có thêm một bản phải giữ cho khớp — và bản không ai sửa chính là bản ngừng khớp. Cái còn lại là cast hai tầng, thứ không bộ rule sẵn có nào từ chối, vì phần lớn codebase coi nó là một lối thoát chính đáng.

Luật máy đã xuất bản

TYPE-SAFETY-4 (tệp kiểm thử được dựng giá trị sai có chủ đích) không có rule riêng: nó được thi hành dưới dạng vắng mặt của rule trên bốn hậu tố tên tệp, nên nó không nằm trong bảng.

TYPE-SAFETY-2 (dạng viết tắt của phép xoá kiểu) và TYPE-SAFETY-3 (một cách viết duy nhất cho mảng) không có rule nào ở đây. Chúng được uỷ thác cho một gói mà mô-đun này không phát hành — rule no-explicit-any của bộ plugin TypeScript và rule array-type của nó với mặc định generic. Một kho nhận gói này rồi cấu hình bộ plugin TypeScript lỏng tay vẫn qua cổng lint của mình trong khi phá hai mã đã công bố, và không gói nào để ý. Uỷ thác không phải là được che.

TYPE-SAFETY-5 (một phép cast sống sót qua review phải mang theo lý do ngay trên dòng) không có rule nào giữ, ở đây cũng như ở chỗ được uỷ thác. Không có gì đọc comment viết cạnh một phép cast. Đó là luật thật và nó hoàn toàn không được thi hành.

Đọc một diff

1. Quyết định phạm vi trước mọi thứ khác, và ghi lại. Ngoài phạm vi ở đây không có nghĩa là tệp đã qua — nghĩa là cổng tệp hỏng, create trả về một object visitor rỗng, và rule không tồn tại với tệp đó.
2. Cổng là hai phép thử trên một chuỗi. Đường dẫn, đã đổi sang gạch chéo, phải chứa /src/ và không kết thúc bằng .test.ts, .test.tsx, .spec.ts hay .spec.tsx. Chỉ bốn hậu tố ấy được miễn trừ; không gì khác cấp được miễn trừ này.
3. Đọc nút, đừng đọc câu lệnh. Thăm từng TSAsExpression, đọc node.expression, đòi nó cũng là TSAsExpression, và đòi typeAnnotation của cast bên trong đúng là TSUnknownKeyword.
4. Mỗi phát hiện một khối, neo ở cast ngoài, một nút vi phạm là một báo cáo.
5. Viết dòng hatch mỗi khi một cửa còn mở lẽ ra đã che đúng lỗi ấy — nhất là khi sự im lặng đến từ một từ khoá khác ở giữa, một nút chen vào giữa hai phép cast, một phép xoá bị tách thành hai câu lệnh, hoặc một đường dẫn nằm ngoài /src/.
6. Đừng báo thứ không rule nào canh. Hai trong năm mã nằm ở gói khác và một mã không có máy nào giữ; một phán quyết nói khác đi là nói sai về mô-đun này.

no-double-cast — TYPE-SAFETY-1

Nó báo cái gì. double — mỗi nút ngoài vi phạm một báo cáo, neo ở cast ngoài, nên một comment tắt rule đặt trên câu lệnh che đúng một phép xoá. Không có bản vá tự động, vì mọi bản sửa thật đều phải cho giá trị một hình dạng mà nó chưa từng có, và máy không chọn được hình dạng ấy.

Nó phát hiện bằng gì. Cổng tệp, xét một lần trong create trước khi cài bất kỳ visitor nào: lấy context.filename (không có thì context.getFilename()), ép chuỗi bằng String(… || ""), đổi mọi dấu gạch ngược thành gạch chéo, rồi đòi kết quả chứa chuỗi con /src/ và không khớp /\.(?:test|spec)\.(?:ts|tsx)$/. Cổng hỏng thì create trả về một object visitor rỗng. Phép thử nút: thăm TSAsExpression, đọc node.expression, đòi node.expression.type === "TSAsExpression", rồi đòi typeAnnotation.type của cast bên trong đúng là TSUnknownKeyword. Khớp thì báo tại nút NGOÀI, với messageId: "double".

Nó không thấy gì. Ba tính chất của cách phát hiện ấy quyết định tất cả. Nó thuần cú pháp — không giải module, không hỏi kiểu, không chạy code. Nó khớp một nút từ khoá, không khớp một ý nghĩa: payload as any as Target, payload as never as Target, payload as {} as Target, và payload as Loose as Target với type Loose = unknown, đều xoá đúng ngần ấy và đều vô hình ở đây. Và nó khớp một quan hệ kề nhau: (payload as unknown)! as Target chen một nút vào giữa cha và con, cặp ấy thôi không còn tồn tại, giá đúng một ký tự. Cách viết ngoặc nhọn <Target><unknown>payload được phân tích thành TSTypeAssertion, một loại nút rule này không bao giờ thăm. payload as Array<unknown> as Array<Target> đẩy từ khoá xuống sâu một tầng trong chú thích, mà rule chỉ đọc nút trên cùng. Còn một giá trị vốn đã mang dạng viết tắt thì gán thẳng vào hình dạng đã khai báo, không có nút cast nào — không có gì về mặt cú pháp để báo.

Ranh giới. Chú thích vế trong đúng là từ khoá unknown mới là thứ khiến một phép xoá thuộc phần việc của rule này; dạng viết tắt thuộc rule được uỷ thác của bộ plugin TypeScript, với mức nghiêm khắc riêng, cấu hình riêng và comment tắt rule riêng. Cast một tầng, và cast mở rộng sang riêng từ khoá, cũng cố ý hợp lệ và cũng không phải việc của rule này.

Cách phát hiện

Không bộ phận nào ở đây với ra ngoài tệp đang lint. Không giải module, không hỏi kiểu, không chạy code.

Lối thoát hợp lệ

Đã đóng — người đọc có thể tưởng những cách viết này lọt qua, nhưng không.

Còn mở — chỗ mù đã phát hành. Một phán quyết không được nói rằng những chỗ này đã được xét.

Đầu vào

Quy tắc

1. Danh tính của rule là tên đã công bố — chuỗi hiện ra trong log dựng và trong comment tắt rule. Không có chỗ nào ở đây gán cho nó một con số.
2. Phát hiện là thuần cú pháp. Không giải module, không hỏi kiểu, không chạy code.
3. Cổng tệp được xét một lần cho mỗi tệp, trước khi cài visitor. Ngoài phạm vi, rule không tồn tại chứ không phải im lặng — vì thế không báo cáo nào lấy lại được bằng cách chuyển tệp về chỗ cũ mà không chạy lint lại.
4. Miễn trừ là một đường dẫn và chỉ là đường dẫn. Không phán đoán, không comment và không tuỳ chọn cấu hình nào cấp được nó, và nó không cấp được theo từng nơi gọi.
5. Một nút ngoài vi phạm là một báo cáo, neo ở cast ngoài, nên một comment tắt rule trên câu lệnh che đúng một phép xoá.
6. Báo cáo là toàn bộ phương thuốc. Rule không phát hành bản vá tự động, vì mọi bản sửa thật đều cho giá trị một hình dạng mà nó chưa từng có, và máy không chọn được hình dạng ấy.
7. Ý kiến về mức nghiêm khắc của chính mô-đun là error; cấu hình bên tiêu thụ vẫn là nơi có thẩm quyền quyết định thứ gì thực sự được bật.

Ngoại lệ

• Tệp kiểm thử. Bốn hậu tố tên tệp — .test.ts, .test.tsx, .spec.ts, .spec.tsx — miễn trừ trọn gói. Đây là TYPE-SAFETY-4 viết thành đường dẫn, và mô-đun rule nói rõ vì sao phải là đường dẫn chứ không phải một phán đoán: chứng minh một API đóng từ chối dữ liệu sai thì phải dựng được dữ liệu sai, mà không có cách nào dựng một giá trị mà kiểu cấm nếu không bảo trình biên dịch quên kiểu đi. Bản dựa trên phán đoán sẽ bị đem ra cãi lại ở từng nơi gọi; một đường dẫn thì cãi một lần. Nó giải phóng TYPE-SAFETY-1 khỏi những tệp ấy hoàn toàn.
• Mọi thứ ngoài /src/. Không phải một ân huệ cấp cho ai — là một quyết định về việc cái gì được tính là mã nguồn sản phẩm. Nó giải phóng TYPE-SAFETY-1 khỏi mọi thư mục khác, và đó là nơi chứa khối lượng mã không được soi lớn nhất.
• Cast một tầng. Không phải sơ suất, cũng không phải ân huệ: một phép thu hẹp mà trình biên dịch còn kiểm được một phần là một hành vi khác hẳn một phép xoá, và bộ kiểm thử song sinh của rule ghim chính xác sự khác biệt đó. Nó không giải phóng gì cả, vì TYPE-SAFETY-1 chưa bao giờ nhận phần ấy.
• Cast mở rộng sang riêng từ khoá. Hợp lệ theo thiết kế; đó là hình dạng luật đòi khi hình dạng thật sự chưa được biết.

Đầu ra

Mỗi phát hiện một khối:

rule:    no-double-cast
file:    <path as the gate saw it, forward-slashed>
scope:   <in | out — which half of the file gate decided it>
node:    TSAsExpression (outer)
inner:   TSAsExpression -> TSUnknownKeyword
message: double
report:  <double | none>
hatch:   <the open hatch that would have hidden this, or none>

Một tệp trong phạm vi mà sạch thì phát ra một khối với scope: in, report: none, các dòng node:, inner: và message: viết là —, kèm một dòng hatch mỗi khi một cửa còn mở có thể đã tạo ra chính sự im lặng ấy.

Một tệp ngoài phạm vi phát ra một khối với scope: out, report: none, và một dòng hatch gọi tên nửa nào của cổng đã loại nó ra. Nó không hề “qua”; không visitor nào được cài.

Ví dụ đã giải

Đầu vào. src/data/profile.ts, đúng chỗ dữ liệu từ ngoài chương trình đi vào:

const response = await fetch(url)
const row = (await response.json()) as unknown as ProfileRow
 
const SEED_ROW = fixture as unknown as ProfileRow
export const seed = () => insert(SEED_ROW)

Đường dẫn chứa /src/ và không kết thúc bằng một trong bốn hậu tố, nên cổng qua và visitor được cài. Hai nút ngoài vi phạm, hai khối.

rule:    no-double-cast
file:    src/data/profile.ts
scope:   in — contains /src/, no test or spec suffix
node:    TSAsExpression (outer)
inner:   TSAsExpression -> TSUnknownKeyword
message: double
report:  double
hatch:   none

rule:    no-double-cast
file:    src/data/profile.ts
scope:   in — contains /src/, no test or spec suffix
node:    TSAsExpression (outer)
inner:   TSAsExpression -> TSUnknownKeyword
message: double
report:  double
hatch:   none

Gom giá trị vào một hằng số không rửa được cái thứ hai: nút vi phạm đi theo vào phần khởi tạo của hằng và bị thăm y như cũ.

Bản đã sửa. Phép xoá được thay bằng một phép mở rộng công khai cùng một phép kiểm mà máy đi theo được, còn hàng dữ liệu mẫu do một hàm dựng có kiểu tạo ra:

const response = await fetch(url)
const payload: unknown = await response.json()
if (!isProfileRow(payload)) throw new InvalidPayloadError()
const row = payload
 
const SEED_ROW: ProfileRow = buildProfileRow({ id: "seed" })
export const seed = () => insert(SEED_ROW)

Nhưng cũng chính tệp ấy, sửa cho trông y hệt như trên rồi xoá đi phép kiểm, thì cũng im lặng:

const loose: unknown = await response.json()
const row = loose as ProfileRow

rule:    no-double-cast
file:    src/data/profile.ts
scope:   in — contains /src/, no test or spec suffix
node:    —
inner:   —
message: —
report:  none
hatch:   the erasure split across two statements — no double cast exists, the erasure is intact, and
         the compliant shape and the evasion are syntactically identical. Only the check between the
         two lines separates them, and nothing requires a check

Phạm vi

Mô-đun này ghi lại đúng một rule do mô-đun rule của luật type-safety công bố, phát hành trong @starci/eslint-canon-fe. Nó không ghi rule đáng-lẽ-phải-có: một rule không chỉ ra được là một đề xuất, không phải một sự thi hành. Nó không xét dạng viết tắt của phép xoá kiểu và cũng không xét cách viết mảng — hai thứ ấy thuộc rule no-explicit-any của bộ plugin TypeScript và rule array-type của nó với mặc định generic — và nó không xét việc một phép cast sống sót có mang theo lý do hay không, thứ không mô-đun nào sở hữu.