diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/LINTING.txt | 194 | ||||
| -rw-r--r-- | docs/POLICY.txt | 18 | ||||
| -rw-r--r-- | docs/TYPESCRIPT.txt | 18 |
3 files changed, 219 insertions, 11 deletions
diff --git a/docs/LINTING.txt b/docs/LINTING.txt new file mode 100644 index 0000000..6185b0d --- /dev/null +++ b/docs/LINTING.txt @@ -0,0 +1,194 @@ +Copyright (C) 2026 Doan Luu Duc Tai <doan@luuduct.ai> + +This program is free software: you can redistribute it and/or modify +it under the terms of the GNU Affero General Public License as +published by the Free Software Foundation, either version 3 of the +License, or (at your option) any later version. + +This program is distributed in the hope that it will be useful, +but WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the +GNU Affero General Public License for more details. + +You should have received a copy of the GNU Affero General Public License +along with this program. If not, see <https://www.gnu.org/licenses/>. + +STRICT LINT POLICY + + Work is on linting/strict, based on the TypeScript migration. Main and + production are separate until this branch is explicitly merged and deployed. + Cargo.toml is the workspace policy; all four packages inherit it. + + Forbid rejects source-level attempts to lower a lint. Deny rejects a + violation but permits a narrower source-level override. Neither prevents + someone from changing the build configuration itself. Compiler/tool versions + are pinned, and the checked build is the supported development path. + +RUST AND CLIPPY + + Every previously denied individual Clippy rule and every enabled Clippy + group now uses forbid. There are no blanket Clippy allow entries. This + includes all, correctness, suspicious, cargo, style, complexity, perf, + pedantic, nursery, multiple_crate_versions, and redundant_pub_crate. + All Rustdoc lints in its supported all group are forbidden too. + + Rust safety, documentation, visibility, casts, edition/future compatibility, + underscore bindings, and warnings use forbid. Unused-group members that do + not conflict with generated code are independently forbidden. Additional + restrictions cover panic/unimplemented/unreachable paths, panic inside Result + functions, unsafe allowance attributes, numeric/pointer casts, native-endian + data, string slicing, infinite loops, and test placement. Cargo.toml lists + the precise rules. Contradictory restriction groups are not enabled wholesale. + + The supported workarounds were implemented instead of lowering these rules: + + Clap derives became explicit checked Clap builders. All argument parsing + stays in Clap; application code does not implement a shell parser. + Both command schemas have regression tests for modes, required paths, + listener parsing, global --root, and maintenance conflicts. Help flags + and rejected-option exit codes were compared against the previous binaries. + The unused Clap derive feature and its lockfile dependency were removed. + + Tokio's runtime attribute became an explicit checked runtime builder. + Runtime construction errors propagate through the existing error path. + The broad generated expect/style/complexity allowances are no longer needed. + + Management and server implementations live inside private app namespaces. + Internal interfaces use pub(super), narrower than crate visibility. Only + the documented program entry point is re-exported at the binary root. + This satisfies both redundant_pub_crate and unreachable_pub without + exposing helper modules or allowing either lint. + + Serde containers specify crate = "serde". This supported attribute avoids + the generated extern-crate branch and its unused_extern_crates and + clippy::useless_attribute allowances. File and wire representations retain + their existing field names, ordering, tagging, and unknown-field checks. + + Result-returning tests report failed checks with anyhow::ensure instead + of panicking. This permits panic_in_result_fn without suppressions. + +THREE REMAINING RUST DENY SETTINGS + + unused, nonstandard_style, and unused_qualifications remain deny. This is + a generated-code compatibility requirement, not permission to add source + allowances. clippy::allow_attributes and allow_attributes_without_reason + are forbidden for first-party source. + + The pinned Serde derive implementation unconditionally emits allowances for + non_upper_case_globals, unused_attributes, unused_qualifications, and + clippy::absolute_paths in serde_derive/src/dummy.rs. Its generated field + identifier visitor also allows non_camel_case_types. These are generated + attributes even when the first-party type has correct names and no redundant + qualification. They cannot be removed by renaming fields or imports. + + The supported crate-path workaround was applied and all macros were inspected. + Repeating Clippy with -F unused, -F nonstandard_style, or + -F unused_qualifications still rejects the pinned Serde expansion. There is + no supported derive setting to suppress that unconditional wrapper. Further + changes would require forking the generator or replacing the serialization + implementation, including security-sensitive identity/envelope/request formats. + Those are explicit upstream/format migrations, not configuration fixes. + + Every other unused-group member and non_snake_case is independently forbidden. + warnings itself is forbidden; the explicit deny groups provide the narrowly + required effective levels for the generated attributes. No first-party + allow/expect attributes were added. + +DUPLICATE DEPENDENCIES + + clippy.toml restricts allowed-duplicate-crates to generic-array, getrandom, + and syn: the names actually diagnosed in this workspace. The Clippy lint + and cargo group remain forbidden for every other dependency. + + The incompatible lines come from the pinned crypto/parser/build graph: + generic-array 0.14.7 and 1.4.5 + getrandom 0.2.17 and 0.4.3 + syn 2.0.119 and 3.0.9 + + These are different semver compatibility lines, not duplicate patch releases. + Unifying them requires upstream API changes or older dependencies. No crypto + algorithm/backend changes or dependency downgrades were made for a lint. + cargo-deny continues to enforce its exact reviewed version exceptions in + deny.toml, including build/development dependencies. Clippy's name-only + configuration does not replace that stronger version-specific audit. + +TYPESCRIPT + + The compiler checks strict mode and the additional indexed access, optional + property, unused, return, switch, override, and import checks. noCheck and + allowJs are explicitly false. Both declaration-library skip flags are false. + isolatedModules, erasableSyntaxOnly, and verbatimModuleSyntax remain enabled. + Browser/worker configurations use Bundler resolution with Preserve output; + they contain no runtime imports. Tests and tooling use NodeNext separately. + + eslint.config.ts extends the typed strict and stylistic TypeScript presets. + All diagnostics are errors and any warning fails the check. Inline config + is disabled; suppression directives and unsafe assertions are prohibited. + Additional rules reject ambiguous boolean coercion, unhandled/misused promises, + explicit or leaked any, non-null assertions, unsafe calls/returns/arguments, + eval, unsafe casts, and unchecked discriminated-union switches. Functions + expose checked return types; callback contexts retain their declared contracts. + + UI async tasks now have explicit rejection handlers at the DOM boundary. + Test HTTP handlers also catch rejected work rather than returning unobserved + promises to Node. WASI validates its start export before calling it, and the + shared host is installed as a frozen, non-writable global property. Dynamic + JSON and worker boundaries still validate unknown values at runtime. + + TypeScript 7.0.2 remains the emitting compiler, installed under the explicit + typescript-native npm alias. typescript-eslint 8.72.1 supports TypeScript + >=4.8.4 <6.1.0 and requires the JavaScript compiler API, so TypeScript 6.0.3 + supplies that supported lint API. Sources are checked by both compilers; + no unsupported-peer or ignore-peer-dependency install flags are used. + Every invocation names the intended compiler path to avoid npm bin collisions. + + Isolated declaration emission is a library-distribution constraint, not an + additional application safety check. This project serves classic scripts + for the tested LibreJS path and does not publish a TypeScript library. + moduleDetection=force is used for tests/tools; changing browser scripts to + ESM solely for that setting would change their loading/LibreJS contract. + TypeScript 7 removed allowSyntheticDefaultImports=false, so that obsolete + switch is not used. Typed linting checks unsafe interop at use sites. + +DEVELOPMENT DEPENDENCY ADVISORY + + ESLint and typescript-eslint currently request minimatch 10. The public + GHSA-g3hv-75wg-m249 advisory affects minimatch <11.0.1. The root npm override + pins the patched 11.0.3 release instead of ignoring the advisory or applying + npm audit fix --force. Its supported exports and Node engine were reviewed; + typed linting and rule-selection/negative-control checks exercise compatibility. + Remove the override when upstream ranges admit a patched version naturally. + + npm audit --audit-level=info is part of npm run check and therefore the Cargo + check/release path. Development dependency findings fail the build too. + Installed tools preserve their original notices and machine SPDX identifiers. + Human documentation calls SPDX MIT the Expat License. No third-party + JavaScript dependency is delivered to visitors. + +CHECKS AND EXPORTS + + npm run build + cargo stack check + cargo stack release + + The first checks both TypeScript compilers, typed ESLint, and npm advisories, + then emits the browser/worker/test artifacts. Cargo also runs formatting, + strict Clippy, all workspace tests, strict Rustdoc, cargo-deny, and cargo-about. + Browser checks and GNU LibreJS controls are documented in TYPESCRIPT.txt. + + clippy.toml, eslint.config.ts, every tsconfig, and both lockfiles are included + in corresponding sources, releases, and backups. Installed node_modules, + runtime state, and the private .env remain outside public exports. Nothing + introduces another deployment environment file or a production Node runtime. + +PRIMARY REFERENCES + + https://doc.rust-lang.org/stable/rustc/lints/levels.html + https://doc.rust-lang.org/clippy/lints.html + https://doc.rust-lang.org/clippy/lint_configuration.html + https://serde.rs/container-attrs.html + https://github.com/serde-rs/serde/blob/v1.0.229/serde_derive/src/dummy.rs + https://www.typescriptlang.org/tsconfig/ + https://typescript-eslint.io/users/configs/ + https://typescript-eslint.io/users/dependency-versions/ + https://github.com/advisories/GHSA-g3hv-75wg-m249 diff --git a/docs/POLICY.txt b/docs/POLICY.txt index 1f54398..4c6c6d3 100644 --- a/docs/POLICY.txt +++ b/docs/POLICY.txt @@ -45,12 +45,14 @@ PROJECT CONVENTIONS STRICTNESS - Preserve the requested Rust and Clippy deny groups, including pedantic - and nursery. The one additional exception is redundant_pub_crate: its - advice to make internal binary items public conflicts with unreachable_pub, - which remains denied. Internal interfaces remain explicitly crate-private. - No unsafe code, unwrap, expect, todo, debug output, arithmetic shortcuts, - or broad warning suppression is introduced. + All enabled Clippy groups and individual rules are forbidden, with no + blanket allow entries. Rust and Rustdoc checks use forbid wherever supported + by generated code. Three Rust settings remain deny for pinned Serde derives; + their unaffected members are independently forbidden. First-party lint + allowances are forbidden. See LINTING.txt for tested workarounds, generated + attribute evidence, and the narrow duplicate-dependency configuration. + Private app namespaces retain narrow internal visibility while both + redundant_pub_crate and unreachable_pub are enforced. cargo-deny rejects duplicate crate versions, wildcard requirements, unknown registries, unknown Git sources, and yanked versions. The chat prototype has @@ -63,7 +65,9 @@ STRICTNESS Browser logic and automation use strict TypeScript configurations with separate browser/worker/Node environments and checked untrusted responses. npm dependencies are exact, development-only, integrity-locked, and installed - with lifecycle scripts disabled. See TYPESCRIPT.txt for the build contract. + with lifecycle scripts disabled. Typed ESLint forbids unsafe any/assertions, + unchecked promises, and suppression directives. Both supported compiler APIs + and npm advisories are checked. See TYPESCRIPT.txt and LINTING.txt. Human license names follow https://www.gnu.org/licenses/license-list.html. In particular, display Expat License for SPDX MIT. Do not alter original diff --git a/docs/TYPESCRIPT.txt b/docs/TYPESCRIPT.txt index d50ea95..7fbc5a4 100644 --- a/docs/TYPESCRIPT.txt +++ b/docs/TYPESCRIPT.txt @@ -40,6 +40,10 @@ SOURCE LAYOUT tests/browser-support.ts Checked fixture parsing and typed browser-automation helpers. + eslint.config.ts and tsconfig.tools.json supply the typed lint-tool checks. + src/app and crates/chat-server/src/app contain the private Rust CLI + implementations; their parser and runtime changes are recorded in LINTING.txt. + tsconfig.json supplies shared strict checks. The browser, worker, and test configurations use separate DOM, WebWorker, and Node environments. Production browser builds cannot accidentally rely on Node APIs. @@ -53,6 +57,10 @@ DEVELOPMENT Install Node >=22.18.0 and npm on the development machine. Root package.json and package-lock.json pin TypeScript 7.0.2, Playwright 1.64.1, Node type declarations, platform compiler packages, and their integrity hashes. + ESLint 10.14.0 and typescript-eslint 8.72.1 provide typed strict linting. + TypeScript 6.0.3 supplies their supported JavaScript API; the pinned native + TypeScript 7.0.2 alias remains the emitting compiler. Both check the sources. + LINTING.txt documents the advisory-driven minimatch override. There are no npm application/runtime dependencies. TypeScript and Playwright use the Apache License, Version 2.0; Node declarations and undici-types use the Expat License. Original notices remain in the @@ -63,7 +71,8 @@ DEVELOPMENT npm run build infra/chat/build-typescript.sh installs the locked development packages - with lifecycle scripts disabled, checks all three configurations, and + with lifecycle scripts disabled, checks browser/worker/test/tool configurations, + typed ESLint, both compiler versions, and npm advisories, then emits JavaScript under var/build/typescript. The npm cache stays under .tools/npm-cache. node_modules and generated outputs are ignored by Git. Generated scripts are readable and unminified; no bundler is needed. @@ -72,7 +81,7 @@ DEVELOPMENT cargo-about license generation. cargo stack release builds TypeScript before packaging the complete production release. - Check without installing packages or emitting output after npm run build: + Recheck without reinstalling packages after npm run build: npm run check @@ -92,8 +101,9 @@ DEVELOPMENT .tools/librejs.xpi as documented in CHAT-APPLICATION.txt. The complete chat test proves LibreJS is active and rejects an unlicensed control. Run chat variants sequentially because they share the default test port. - npm audit checks the development dependency lock separately from - cargo-deny; it does not audit Rust, browser-delivered code, or containers. + npm audit checks development dependencies as part of npm run check and the + Cargo check/release path. It does not audit Rust, browser-delivered code, or + containers; cargo-deny remains the separate strict Rust dependency audit. RELEASES, SOURCE, AND LIBREJS |