summaryrefslogtreecommitdiff
path: root/docs/LINTING.txt
blob: bd1cdacedba7e88258ba4601e7f93a6be88906b7 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
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

    Cargo.toml defines workspace policy; all four packages inherit it.
    forbid rejects source-level lowering; deny permits narrower source overrides.
    Neither prevents build-config edits. Pin compiler/tools; use checked builds.

RUST AND CLIPPY

    Every formerly denied individual Clippy rule and enabled group uses forbid.
    No blanket allows. Groups include all, correctness, suspicious, cargo, style,
    complexity, perf, pedantic, nursery; multiple_crate_versions and
    redundant_pub_crate also remain forbidden. Forbid Rustdoc's supported all group.

    Forbid Rust safety/docs/visibility/cast/edition/future-compatibility checks,
    underscore bindings, and warnings. Independently forbid unused-group members
    compatible with generated code. Also restrict panic/unimplemented/unreachable
    paths, panic in Result, unsafe allowance attributes, numeric/pointer casts,
    native-endian data, string slices, infinite loops, and test placement.
    Exact rules: Cargo.toml. Do not enable contradictory restriction groups wholesale.

    Workarounds preserve strictness:

        Explicit checked Clap builders replace derives. Clap still parses all
        arguments; no application shell parser. Both command schemas test modes,
        required paths, listeners, global --root, and maintenance conflicts.
        Help/rejected-option exit codes were compared with previous binaries.
        Removed unused derive feature and its lockfile dependency.

        Explicit checked Tokio runtime builder replaces runtime attribute.
        Construction failures use existing error path; no broad generated
        expect/style/complexity allowances remain.

        Management/server implementations use private app namespaces and
        pub(super), narrower than crate visibility. Re-export only documented
        entry point at binary root. Enforce redundant_pub_crate/unreachable_pub
        without exposing helpers or allowing either lint.

        Serde containers set crate = "serde", avoiding generated extern-crate
        branch and unused_extern_crates/clippy::useless_attribute allowances.
        Preserve file/wire field names, ordering, tagging, unknown-field checks.

        Result-returning tests use anyhow::ensure instead of panicking, permitting
        panic_in_result_fn without suppressions.

THREE REMAINING RUST DENY SETTINGS

    unused, nonstandard_style, unused_qualifications stay deny for generated-code
    compatibility, not permission for source allowances. First-party
    clippy::allow_attributes and allow_attributes_without_reason are forbidden.

    Pinned serde_derive/src/dummy.rs unconditionally allows non_upper_case_globals,
    unused_attributes, unused_qualifications, clippy::absolute_paths. Generated
    field-identifier visitor also allows non_camel_case_types. Correct first-party
    names/qualifications cannot remove these generated attributes.

    Applied supported crate-path workaround; inspected all macros. Clippy with
    -F unused, -F nonstandard_style, or -F unused_qualifications still rejects
    pinned Serde expansion. No supported derive setting removes its unconditional
    wrapper. Further changes require a generator fork or serialization replacement,
    including security-sensitive identity/envelope/request formats: explicit
    upstream/format migrations, not configuration fixes.

    Independently forbid every other unused member and non_snake_case. warnings
    remains forbidden; explicit deny groups supply narrow effective levels needed
    by generated attributes. Added no first-party allow/expect attributes.

DUPLICATE DEPENDENCIES

    clippy.toml allowed-duplicate-crates contains only diagnosed names:
    generic-array, getrandom, syn. Lint/cargo group forbid all other duplicates.
    Pinned crypto/parser/build graph needs incompatible semver lines:

        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 not duplicate patch releases. Unification needs upstream API changes
    or older dependencies. No crypto/backend changes or downgrades for lint.
    cargo-deny enforces exact reviewed deny.toml exceptions, including build/dev
    dependencies. Clippy's name-only allowance cannot replace that stronger audit.

TYPESCRIPT

    Check strict mode, indexed access, optional properties, unused, returns,
    switches, overrides, imports. Explicitly disable noCheck/allowJs and both
    declaration-library skip flags. Enable isolatedModules, erasableSyntaxOnly,
    verbatimModuleSyntax. Browser/worker: Bundler resolution, Preserve output,
    no runtime imports. Tests/tools: separate NodeNext configurations.

    eslint.config.ts extends typed strict/stylistic presets. All diagnostics are
    errors; warnings fail. Disable inline config; prohibit suppression directives
    and unsafe assertions. Reject ambiguous boolean coercion, unhandled/misused
    promises, explicit/leaked any, non-null assertions, unsafe calls/returns/
    arguments, eval, unsafe casts, unchecked discriminated-union switches.
    Functions expose checked return types; callbacks retain declared contracts.

    DOM async tasks and test HTTP handlers catch rejections; Node receives no
    unobserved promises. WASI validates start export before calling it. Shared
    host is a frozen, non-writable global. JSON/worker boundaries validate unknown
    values at runtime.

    TypeScript 7.0.2 emits through explicit typescript-native npm alias.
    typescript-eslint 8.72.1 supports >=4.8.4 <6.1.0 and requires JavaScript
    compiler API; TypeScript 6.0.3 supplies it. Both compilers check sources.
    No unsupported-peer/ignore-peer-dependency install flags. Name intended
    compiler path in every invocation to avoid npm bin collisions.

    Isolated declaration emission constrains library distribution, not application
    safety. This app publishes no TypeScript library; classic scripts preserve
    tested LibreJS loading. moduleDetection=force applies to tests/tools. Do not
    change browser scripts to ESM solely for that setting. TypeScript 7 removed
    allowSyntheticDefaultImports=false; omit obsolete switch. Typed lint checks
    unsafe interop at use sites.

DEVELOPMENT DEPENDENCY ADVISORY

    ESLint/typescript-eslint request minimatch 10. GHSA-g3hv-75wg-m249 affects
    minimatch <11.0.1. Root npm override pins patched 11.0.3; no advisory ignore
    or npm audit fix --force. Reviewed exports/Node engine; typed lint and rule-
    selection/negative-control checks exercise compatibility. Remove override
    when upstream ranges naturally admit a patched version.

    npm audit --audit-level=info runs in npm run check and Cargo check/release.
    Development findings fail too. Tools retain original notices/machine SPDX.
    Human docs call MIT the Expat License. Visitors receive no third-party JS.

CHECKS AND EXPORTS

        npm run build
        cargo stack check
        cargo stack release

    npm build checks both compilers, typed ESLint, npm advisories; emits browser/
    worker/test artifacts. Cargo adds formatting, strict Clippy, all workspace
    tests, strict Rustdoc, cargo-deny, cargo-about. Browser/LibreJS controls:
    TYPESCRIPT.txt.

    Corresponding sources/releases/backups include clippy.toml, eslint.config.ts,
    every tsconfig, both lockfiles. Public exports exclude installed node_modules,
    runtime state, private .env. No extra deployment env file or production Node.

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