TO REMOVE: kiro spec docs

Author: weihanglo

.kiro/specs/spdx-license-validation/design.md

@@ -0,0 +1,334 @@
+# Design Document
+
+## Overview
+
+This design outlines the implementation of a new Cargo lint called `invalid_license_expression` that validates `package.license` fields against SPDX license expression standards. The lint will be integrated into Cargo's existing linting infrastructure and will help package authors ensure their license expressions are properly formatted and parseable by tools that consume SPDX data.
+
+## Architecture
+
+The lint will be implemented as part of Cargo's existing lint system in `src/cargo/util/lints.rs`. It will follow the same patterns as other Cargo lints like `unknown_lints` and `im_a_teapot`, integrating seamlessly with the current lint infrastructure.
+
+### Key Components
+
+1. **Lint Definition**: A new `Lint` constant that defines the lint's metadata, default level, and edition-specific behavior
+2. **Validation Function**: A function that checks license expressions using the SPDX crate
+3. **Error Reporting**: Integration with Cargo's diagnostic system to provide helpful error messages
+4. **Edition-based Defaults**: Different default levels for different Cargo editions
+
+## Components and Interfaces
+
+### Lint Definition
+
+```rust
+const INVALID_LICENSE_EXPRESSION: Lint = Lint {
+    name: "invalid_license_expression",
+    desc: "invalid SPDX license expression",
+    groups: &[],
+    default_level: LintLevel::Warn,
+    edition_lint_opts: Some((Edition::Edition2027, LintLevel::Deny)),
+    feature_gate: None,
+    docs: Some(/* documentation */),
+};
+```
+
+### Validation Function
+
+The main validation function will:
+1. Extract the license field from the package manifest
+2. Use the `spdx` crate to parse and validate the expression
+3. Generate appropriate diagnostics for invalid expressions
+4. Provide helpful suggestions for common mistakes
+
+```rust
+pub fn check_invalid_license_expression(
+    pkg: &Package,
+    path: &Path,
+    pkg_lints: &TomlToolLints,
+    error_count: &mut usize,
+    gctx: &GlobalContext,
+) -> CargoResult<()>
+```
+
+### SPDX Integration
+
+The lint will use the `spdx` crate for validation. Based on research, we'll use a recent version that aligns with current SPDX standards:
+- SPDX specification version 2.3 (as referenced in Cargo documentation)
+- Compatible with crates.io's validation requirements
+
+## Data Models
+
+### License Expression Validation
+
+The validation will handle:
+- **Valid expressions**: `MIT`, `Apache-2.0`, `MIT OR Apache-2.0`, `GPL-3.0-or-later WITH Classpath-exception-2.0`
+- **Invalid expressions**: `MIT / Apache-2.0`, `MIT and Apache-2.0`, malformed expressions
+- **Edge cases**: Empty strings, whitespace-only strings, case sensitivity
+
+### Error Context
+
+Error messages will include:
+- The invalid expression
+- Specific location in the manifest file
+- Suggestions for common fixes (e.g., replacing `/` with `OR`)
+- Reference to SPDX documentation
+
+## Error Handling
+
+### Diagnostic Generation
+
+The lint will generate structured diagnostics using Cargo's `annotate-snippets` system:
+
+```rust
+let message = level
+    .title("invalid SPDX license expression")
+    .snippet(
+        Snippet::source(manifest.contents())
+            .origin(&manifest_path)
+            .annotation(level.span(license_span))
+            .fold(true),
+    )
+    .footer(Level::Help.title("use valid SPDX operators like 'OR' instead of '/'"));
+```
+
+### Common Error Patterns
+
+1. **Slash operator**: `MIT / Apache-2.0` → suggest `MIT OR Apache-2.0`
+2. **Lowercase operators**: `mit and apache-2.0` → suggest `MIT AND Apache-2.0`
+3. **Invalid license identifiers**: `Apache2` → suggest `Apache-2.0`
+4. **Malformed expressions**: Missing parentheses, invalid syntax
+
+## Testing Strategy
+
+### Unit Tests
+
+Unit tests will be located in `src/cargo/util/lints.rs` and will focus on testing the core validation logic:
+
+1. **SPDX parsing**: Test the `spdx` crate integration directly
+2. **Lint level calculation**: Test edition-based and configuration-based lint levels
+3. **Error message generation**: Test diagnostic message formatting
+4. **Edge cases**: Empty strings, whitespace, malformed input
+
+### Integration Tests
+
+Integration tests will follow Cargo's established patterns and be located in `tests/testsuite/lints.rs` alongside existing lint tests. These will use functional tests with the `project()` builder pattern.
+
+#### Functional Tests
+
+All integration tests will be functional tests using programmatically defined fixtures and in-source snapshots:
+
+```rust
+use crate::prelude::*;
+use cargo_test_support::str;
+use cargo_test_support::project;
+
+#[cargo_test]
+fn invalid_license_expression_warns_by_default() {
+    let p = project()
+        .file("Cargo.toml", r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+            license = "MIT / Apache-2.0"
+        "#)
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("check")
+        .with_stderr_data(str![[r#"
+[WARNING] invalid SPDX license expression: `MIT / Apache-2.0`
+  --> Cargo.toml:4:23
+   |
+ 4 |             license = "MIT / Apache-2.0"
+   |                       ^^^^^^^^^^^^^^^^^^
+   |
+   = help: use valid SPDX operators like 'OR' instead of '/'
+   = note: `cargo::invalid_license_expression` is set to `warn` by default
+[CHECKING] foo v0.1.0 ([ROOT]/foo)
+[FINISHED] [..]
+"#]])
+        .run();
+}
+
+#[cargo_test]
+fn valid_license_expression_no_warning() {
+    let p = project()
+        .file("Cargo.toml", r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+            license = "MIT OR Apache-2.0"
+        "#)
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("check")
+        .with_stderr_data(str![[r#"
+[CHECKING] foo v0.1.0 ([ROOT]/foo)
+[FINISHED] [..]
+"#]])
+        .run();
+}
+
+#[cargo_test]
+fn lint_level_deny_fails_build() {
+    let p = project()
+        .file("Cargo.toml", r#"
+            [package]
+            name = "foo"
+            version = "0.1.0"
+            license = "MIT / Apache-2.0"
+
+            [lints.cargo]
+            invalid_license_expression = "deny"
+        "#)
+        .file("src/lib.rs", "")
+        .build();
+
+    p.cargo("check")
+        .with_status(101)
+        .with_stderr_data(str![[r#"
+[ERROR] invalid SPDX license expression: `MIT / Apache-2.0`
+  --> Cargo.toml:4:23
+   |
+ 4 |             license = "MIT / Apache-2.0"
+   |                       ^^^^^^^^^^^^^^^^^^
+   |
+   = help: use valid SPDX operators like 'OR' instead of '/'
+   = note: `cargo::invalid_license_expression` is set to `deny` in `[lints]`
+"#]])
+        .run();
+}
+```
+
+#### Test Organization
+
+Tests will be added to the existing `tests/testsuite/lints.rs` file alongside other lint tests like `unknown_lints` and `im_a_teapot`. This follows the established pattern of grouping related lint tests together.
+
+#### Test Categories
+
+1. **Basic Validation Tests**
+   - Valid SPDX expressions (MIT, Apache-2.0, MIT OR Apache-2.0)
+   - Invalid expressions (MIT / Apache-2.0, mit and apache)
+   - Malformed expressions (unclosed parentheses, invalid operators)
+   - Edge cases (empty strings, whitespace-only)
+
+2. **Edition Behavior Tests**
+   - Edition 2024: Default warn level
+   - Edition 2027: Default deny level
+   - Edition transitions and compatibility
+
+3. **Configuration Tests**
+   - Lint level overrides in `[lints.cargo]`
+   - Workspace-level lint configuration
+   - Package-level overrides of workspace settings
+
+4. **Workspace Tests**
+   - Workspace root license inheritance
+   - Member package license validation
+   - Mixed valid/invalid licenses across workspace
+
+5. **Error Reporting Tests**
+   - Diagnostic message format and content
+   - Span highlighting accuracy
+   - Helpful suggestions for common mistakes
+
+6. **Command Integration Tests**
+   - Behavior during different Cargo commands (check, build, publish)
+   - Interaction with other lints
+
+### Test Implementation Details
+
+#### Functional Test Pattern
+
+All tests will follow the established functional test pattern:
+- Use `project()` to create test fixtures programmatically
+- Use `str![[]]` macros for in-source snapshots
+- Use pattern matching with `[..]` for variable content
+- Self-contained test cases that can be easily shared in issues
+
+#### Cross-Platform Considerations
+
+- Use `/` for paths in expected output (automatically converted on Windows)
+- Use `[ROOT]` placeholder for project root paths
+- Pattern matching handles platform-specific variations
+
+### Performance Testing
+
+- Benchmark lint execution time with large workspaces
+- Test memory usage with many license expressions
+- Verify no significant impact on build times
+
+## Implementation Plan
+
+### Phase 1: Core Implementation
+1. Add SPDX crate dependency to Cargo.toml
+2. Define the lint constant in `lints.rs`
+3. Implement basic validation function
+4. Add lint to the `LINTS` array
+
+### Phase 2: Error Handling
+1. Implement comprehensive error messages
+2. Add suggestions for common mistakes
+3. Handle edge cases and malformed input
+4. Test error reporting
+
+### Phase 3: Integration
+1. Integrate with existing lint infrastructure
+2. Add edition-specific behavior
+3. Ensure proper workspace inheritance
+4. Add comprehensive tests
+
+### Phase 4: Documentation
+1. Write lint documentation with examples
+2. Update Cargo documentation
+3. Add migration guide for common issues
+4. Create examples of valid/invalid expressions
+
+## Dependencies
+
+### New Dependencies
+
+The implementation will require adding the `spdx` crate as a dependency. Based on research of SPDX standards and crates.io compatibility:
+
+```toml
+[dependencies]
+spdx = "0.10"  # Latest stable version supporting SPDX 2.3
+```
+
+### Existing Dependencies
+
+The lint will leverage existing Cargo infrastructure:
+- `annotate-snippets` for error reporting
+- `toml` for manifest parsing
+- `cargo-util-schemas` for manifest structure
+- Existing lint framework in `src/cargo/util/lints.rs`
+
+## Compatibility
+
+### Backward Compatibility
+
+The lint is designed to be non-breaking:
+- Default level is `Warn` in Edition 2024, so existing builds continue to work
+- Only becomes `Deny` by default in future editions (2027+)
+- Can be disabled by setting lint level to `Allow`
+
+### Forward Compatibility
+
+- Uses stable SPDX specification (2.3)
+- Aligns with crates.io validation requirements
+- Extensible for future SPDX specification updates
+
+## Performance Considerations
+
+### Validation Performance
+
+- SPDX parsing is performed only when the lint is enabled and not set to `Allow`
+- Validation occurs only during manifest processing, not during builds
+- Caching of parsed expressions within the same Cargo invocation
+- Minimal impact on build times
+
+### Memory Usage
+
+- SPDX crate has minimal memory footprint
+- License expressions are typically short strings
+- No persistent state or large data structures required