feat(validation): add static feature flag usage validation at build time

[nicokempe]

✅ PR Checklist

Please ensure the following before submitting your PR:

• My commit message follows Conventional Commits
• I’ve tested the changes and confirmed they work as expected
• I’ve updated any relevant documentation
• I’ve added tests (if applicable)

🔗 Linked Issue

No issue created.

📖 Description

This PR introduces a powerful new static validation system for feature flags.

At build time (Nuxt ready hook), the module now scans all .vue, .ts, and .js files in the project and verifies that each feature flag used via v-feature, isEnabled(), or defineFeatureFlagMiddleware() is declared in at least one environment in the featureFlags config.

This helps detect typos or forgotten declarations early in development and improves maintainability across environments.

The behavior is controlled via the new validation option:

featureFlags: {
  validation: {
    mode: 'warn', // or 'error' | 'disabled'
    includeGlobs: ['**/*.vue'],
    excludeGlobs: ['.nuxt', 'dist'],
  },
}

By default:

• mode is 'warn'
• Files in node_modules, .nuxt, and dist are excluded
• All .vue, .ts, and .js files are included

If a flag is used but not declared in any environment, a warning (or error) with file path, line, and column is shown.

🚨 Breaking Changes

• Yes
• No

🧪 Type of Change

• 🐛 Bug fix
• ✨ New feature
• 🧹 Code style / formatting
• 🔨 Refactoring (no functional changes)
• 🧰 Tooling / CI
• 📝 Docs update
• 🧪 Tests
• 💡 Other (please describe):

🧩 Additional Context

No additional context.

[Copilot]

Pull Request Overview

Adds build-time validation for feature flag usage to catch undeclared flags during the Nuxt build process.

• Introduces validateFeatureFlags to scan project files and report undeclared flags.
• Hooks validation into the Nuxt ready lifecycle with configurable mode and file globs.
• Updates the playground to demonstrate the validation in error mode and adds necessary dependencies.

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/runtime/utils/flagValidator.ts	Added logic to glob, read, and regex-scan files for flag usages
src/module.ts	Wired the validator into the Nuxt module setup and defaults
playground/pages/index.vue	Inserted example uses of undefined flags to trigger validation
playground/nuxt.config.ts	Configured validation mode and include/exclude patterns
playground/middleware/...-flag.ts	Added middleware example using a non-declared flag
package.json	Added globby dependency for file pattern matching

Comments suppressed due to low confidence (1)

src/runtime/utils/flagValidator.ts:25

• The new validation logic isn't covered by tests; adding unit tests for various usage patterns would help ensure correctness and prevent regressions.

export async function validateFeatureFlags(

[Copilot]

[nitpick] Parsing templates and code with regex can be brittle; consider using an AST-based parser for more reliable and maintainable feature-flag extraction.

[Copilot]

Pull Request Overview

This PR introduces a new build-time static validation system to ensure that all feature flags used in the project are declared in at least one environment.

• Adds a flag scanning and validation function in the runtime utility.
• Integrates the validation into the Nuxt module by invoking it on the ‘ready’ hook.
• Provides updated playground examples and configuration to showcase flag validation.

Reviewed Changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/runtime/utils/flagValidator.ts	Implements the flag scanning and validation logic using regex patterns.
src/module.ts	Integrates validation within the Nuxt module setup and updates defaults.
playground/pages/index.vue	Includes test cases for non-existing flags via directives and functions.
playground/nuxt.config.ts	Adds validation configuration to the Nuxt config.
playground/middleware/feature-not-existing-flag.ts	Demonstrates middleware handling with a feature flag check.
package.json	Adds the dependency for globby required for file scanning.