From e5802c7b6d61d54db5552662d105ad462f839456 Mon Sep 17 00:00:00 2001 From: Krishan Kant Sharma Date: Wed, 1 Jul 2026 09:03:18 -0500 Subject: [PATCH] docs: post-v1 accuracy and coverage update MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit New pages: - docs/cli/init.md — flaglint init command reference - docs/cli/completion.md — flaglint completion command reference Sidebar: - astro.config.mjs: add init (before audit) and completion (after exit-codes) to CLI section Accuracy fixes: - supported-scope.md: React SDK hooks/HOC/provider now detected (was 'No') Add React SDK detection section with import provenance examples - configuration.md: document wrappers object form {import, function, flagKeyArgument} with field table and false-positive prevention explanation Changelog: - changelog.md: add v1.1.0 block covering PRs #194-#200 (React SDK detection, wrapper v2, init, completion, --quiet/--verbose, action version input, provider guard, micromatch) Global flags on all command pages: - scan.md, audit.md, migrate.md, validate.md: add --quiet/-q and --verbose rows Quickstart: - quickstart.md: add step 0 for flaglint init before step 1 (audit) Signed-off-by: Krishan Kant Sharma --- astro.config.mjs | 2 + src/content/docs/docs/cli/audit.md | 4 +- src/content/docs/docs/cli/completion.md | 96 +++++++++++++++++++ src/content/docs/docs/cli/configuration.md | 43 ++++++++- src/content/docs/docs/cli/init.md | 86 +++++++++++++++++ src/content/docs/docs/cli/migrate.md | 4 +- src/content/docs/docs/cli/scan.md | 4 +- src/content/docs/docs/cli/validate.md | 4 +- src/content/docs/docs/quickstart.md | 14 ++- src/content/docs/docs/reference/changelog.md | 20 +++- .../docs/docs/reference/supported-scope.md | 29 +++++- 11 files changed, 294 insertions(+), 12 deletions(-) create mode 100644 src/content/docs/docs/cli/completion.md create mode 100644 src/content/docs/docs/cli/init.md diff --git a/astro.config.mjs b/astro.config.mjs index 041e1cd..5fbcf20 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -80,6 +80,7 @@ export default defineConfig({ label: "CLI", collapsed: true, items: [ + { label: "init", slug: "docs/cli/init" }, { label: "audit", slug: "docs/cli/audit" }, { label: "Effort Estimation", slug: "docs/cli/effort-estimate" }, { label: "scan", slug: "docs/cli/scan" }, @@ -88,6 +89,7 @@ export default defineConfig({ { label: "Configuration", slug: "docs/cli/configuration" }, { label: "Report Formats", slug: "docs/cli/report-formats" }, { label: "Exit Codes", slug: "docs/cli/exit-codes" }, + { label: "completion", slug: "docs/cli/completion" }, ], }, { diff --git a/src/content/docs/docs/cli/audit.md b/src/content/docs/docs/cli/audit.md index c1a112b..09f190b 100644 --- a/src/content/docs/docs/cli/audit.md +++ b/src/content/docs/docs/cli/audit.md @@ -1,7 +1,7 @@ --- title: flaglint audit description: Generate a local flag debt audit report with risk scoring. No API key required. -lastUpdated: 2026-06-07 +lastUpdated: 2026-07-01 --- `flaglint audit` scans your source code and classifies every detected LaunchDarkly Node.js SDK @@ -30,6 +30,8 @@ npx flaglint audit ./src | `--effort-estimate` | Add a directional migration-effort estimate to audit output. | | `--hourly-rate ` | Add an optional engineering-cost range using a user-supplied hourly rate. Valid only with `--effort-estimate`. | | `--write-baseline ` | Write current finding fingerprints to a baseline file for use with `validate --baseline --fail-on-new`. | +| `--quiet` / `-q` | Suppress all progress output. Only errors appear on stderr. Useful in scripts and CI pipelines where only the exit code matters. | +| `--verbose` | Show per-file scan progress (updates on every file instead of every 50). | ## Risk Levels diff --git a/src/content/docs/docs/cli/completion.md b/src/content/docs/docs/cli/completion.md new file mode 100644 index 0000000..818807c --- /dev/null +++ b/src/content/docs/docs/cli/completion.md @@ -0,0 +1,96 @@ +--- +title: flaglint completion +description: Output a shell completion script for bash, zsh, or fish. +lastUpdated: 2026-07-01 +--- + +`flaglint completion` prints a shell completion script to stdout. Source it once and your shell will tab-complete subcommands, flags, and flag values (format choices, shell names, and more). + +## Command + +```bash +flaglint completion +``` + +Supported shells: `bash`, `zsh`, `fish`. + +## Installation + +### Bash + +Load for the current session only: + +```bash +source <(flaglint completion bash) +``` + +Load permanently (add to `~/.bashrc` or `~/.bash_profile`): + +```bash +flaglint completion bash >> ~/.bash_completion +``` + +### Zsh + +Load for the current session only: + +```bash +source <(flaglint completion zsh) +``` + +Load permanently (requires `~/.zsh/completions` in your `$fpath`): + +```bash +mkdir -p ~/.zsh/completions +flaglint completion zsh > ~/.zsh/completions/_flaglint +``` + +Then ensure `$fpath` includes the directory before `compinit` runs — add to `~/.zshrc`: + +```zsh +fpath=(~/.zsh/completions $fpath) +autoload -Uz compinit && compinit +``` + +### Fish + +```bash +flaglint completion fish > ~/.config/fish/completions/flaglint.fish +``` + +Fish auto-sources files in `~/.config/fish/completions/` on startup — no extra configuration needed. + +## What Gets Completed + +- **Subcommands** — `audit`, `scan`, `migrate`, `validate`, `init`, `completion` +- **Flags** — all per-command flags and global flags (`--quiet`, `--verbose`) +- **Flag values** — `--format` values (`json`, `markdown`, `html`, `sarif`, `text`), completion shell names (`bash`, `zsh`, `fish`) +- **File arguments** — `--output`, `--config`, `--baseline`, `--write-baseline` complete against the filesystem + +## Examples + +```bash +# Print the bash completion script +flaglint completion bash + +# Activate immediately in the current bash session +source <(flaglint completion bash) + +# Write the zsh completion script to the standard completions directory +flaglint completion zsh > ~/.zsh/completions/_flaglint + +# Write the fish completion file +flaglint completion fish > ~/.config/fish/completions/flaglint.fish +``` + +## Exit Codes + +| Code | Meaning | +| --- | --- | +| `0` | Script printed successfully. | +| `2` | No shell argument provided, or unsupported shell name. | + +## Feedback + +- [Edit this page on GitHub](https://github.com/flaglint/flaglint.dev/edit/main/src/content/docs/docs/cli/completion.md) +- [Report an unsupported pattern](https://github.com/flaglint/flaglint/issues/new?template=unsupported_pattern.yml) diff --git a/src/content/docs/docs/cli/configuration.md b/src/content/docs/docs/cli/configuration.md index 95f8265..1a130b9 100644 --- a/src/content/docs/docs/cli/configuration.md +++ b/src/content/docs/docs/cli/configuration.md @@ -1,7 +1,7 @@ --- title: Configuration description: Configure scan scope, wrappers, and imported OpenFeature client bindings. -lastUpdated: 2026-05-28 +lastUpdated: 2026-07-01 --- FlagLint reads the first matching config file from: @@ -40,10 +40,47 @@ Use `--config ` to pass a specific file. | `exclude` | common build/test output | Files to skip. | | `provider` | `launchdarkly` | Current implemented provider scope. | | `minFileCount` | `0` | Optional local source review heuristic. | -| `wrappers` | `[]` | Wrapper call names to report for manual review. | +| `wrappers` | `[]` | Wrapper functions to detect as flag evaluations. Accepts string names or object form (see below). | | `openFeatureClientBindings` | `[]` | Imported shared client allowlist for `migrate --apply`. | | `reportTitle` | unset | Optional report title. | -| `outputDir` | `.` | Reserved CLI output setting. | +| `outputDir` | `.` | Directory for generated report files. | + +## Wrappers — String and Object Form + +The `wrappers` field accepts two forms, which can be mixed in the same array. + +**String form** — any call to a function with that name is treated as a flag evaluation: + +```json +{ + "wrappers": ["evaluateFlag", "getFeature"] +} +``` + +**Object form** — the call is only detected when the function is imported from a specific package, preventing false positives from unrelated functions with the same name: + +```json +{ + "wrappers": [ + "evaluateFlag", + { + "import": "my-feature-sdk", + "function": "getFlag", + "flagKeyArgument": 0 + } + ] +} +``` + +Object form fields: + +| Field | Purpose | +| --- | --- | +| `import` | The package name that must be imported for this call to be detected. | +| `function` | The exported function name to detect. | +| `flagKeyArgument` | Zero-based index of the argument that holds the flag key. | + +With the example above, `getFlag("my-flag-key", ctx)` is detected only when `getFlag` is imported from `my-feature-sdk`. A `getFlag` call imported from any other package is ignored. ## Feedback diff --git a/src/content/docs/docs/cli/init.md b/src/content/docs/docs/cli/init.md new file mode 100644 index 0000000..dcf718d --- /dev/null +++ b/src/content/docs/docs/cli/init.md @@ -0,0 +1,86 @@ +--- +title: flaglint init +description: Scaffold a flaglint.config.json with all fields set to their defaults. +lastUpdated: 2026-07-01 +--- + +`flaglint init` writes a `flaglint.config.json` to the current directory with every configuration field set to its default value. Run it once to get a starting config you can edit — no manual JSON authoring required. + +## Command + +```bash +npx flaglint init +``` + +## Options + +| Option | Description | +| --- | --- | +| `--output ` | Write the config to a different filename or path (default: `flaglint.config.json`). | +| `--force` | Overwrite an existing config file without error. | + +## Config Template Written + +```json +{ + "include": ["**/*.{ts,tsx,js,jsx}"], + "exclude": [ + "**/node_modules/**", + "**/dist/**", + "**/build/**", + "**/.next/**", + "**/coverage/**", + "**/*.d.ts" + ], + "provider": "launchdarkly", + "minFileCount": 0, + "wrappers": [], + "openFeatureClientBindings": [], + "outputDir": "." +} +``` + +After writing, `flaglint init` prints a short explanation of each field to stderr so you know what to change. + +## Config Search Order + +FlagLint loads the first matching file from this list: + +```text +.flaglintrc +.flaglintrc.json +flaglint.config.json +``` + +If you write to `flaglint.config.json` (the default) and `.flaglintrc` already exists in the same directory, FlagLint will load `.flaglintrc` instead — it has higher precedence. `flaglint init` warns you if this situation would occur. + +Use `--output .flaglintrc` to write to the highest-precedence path instead, or `--config ` at runtime to use any file regardless of name. + +## Exit Codes + +| Code | Meaning | +| --- | --- | +| `0` | Config file written successfully. | +| `2` | Config file already exists and `--force` was not passed. | + +## Examples + +```bash +# Write flaglint.config.json in the current directory +npx flaglint init + +# Write to .flaglintrc (highest-precedence name) +npx flaglint init --output .flaglintrc + +# Overwrite an existing config without prompting +npx flaglint init --force + +# Write to a specific path +npx flaglint init --output config/flaglint.json +``` + +## Feedback + +- [Edit this page on GitHub](https://github.com/flaglint/flaglint.dev/edit/main/src/content/docs/docs/cli/init.md) +- [Report an unsupported pattern](https://github.com/flaglint/flaglint/issues/new?template=unsupported_pattern.yml) +- Next: [Configuration](/docs/cli/configuration/) diff --git a/src/content/docs/docs/cli/migrate.md b/src/content/docs/docs/cli/migrate.md index 4e7af7a..ad7f432 100644 --- a/src/content/docs/docs/cli/migrate.md +++ b/src/content/docs/docs/cli/migrate.md @@ -1,7 +1,7 @@ --- title: flaglint migrate description: Generate migration plans, preview diffs, and apply guarded OpenFeature rewrites. -lastUpdated: 2026-05-28 +lastUpdated: 2026-07-01 --- `flaglint migrate` analyzes supported LaunchDarkly Node.js server SDK evaluation calls and separates safe call-site rewrites from manual-review work. @@ -30,6 +30,8 @@ npx flaglint migrate ./src --apply | `--output ` | Write the default migration report to a file. | | `--config ` | Use an explicit config file. | | `--exclude-tests` | Exclude test/spec files and test directories. | +| `--quiet` / `-q` | Suppress all progress output. Only errors appear on stderr. Useful in scripts and CI pipelines where only the exit code matters. | +| `--verbose` | Show per-file scan progress (updates on every file instead of every 50). | ## Dry-Run Output diff --git a/src/content/docs/docs/cli/scan.md b/src/content/docs/docs/cli/scan.md index a0843ae..d605ac1 100644 --- a/src/content/docs/docs/cli/scan.md +++ b/src/content/docs/docs/cli/scan.md @@ -1,7 +1,7 @@ --- title: flaglint scan description: Inventory supported LaunchDarkly Node.js server SDK evaluation calls. -lastUpdated: 2026-05-28 +lastUpdated: 2026-07-01 --- `flaglint scan` performs AST-based inventory of supported direct LaunchDarkly Node.js server SDK calls. @@ -23,6 +23,8 @@ npx flaglint scan ./src | `--output ` | Write report to a file. | | `--config ` | Use an explicit config file. | | `--exclude-tests` | Exclude test/spec files and test directories. | +| `--quiet` / `-q` | Suppress all progress output. Only errors appear on stderr. Useful in scripts and CI pipelines where only the exit code matters. | +| `--verbose` | Show per-file scan progress (updates on every file instead of every 50). | ## Example Output diff --git a/src/content/docs/docs/cli/validate.md b/src/content/docs/docs/cli/validate.md index 76f8c38..1f5eebe 100644 --- a/src/content/docs/docs/cli/validate.md +++ b/src/content/docs/docs/cli/validate.md @@ -1,7 +1,7 @@ --- title: flaglint validate description: Enforce no-direct-LaunchDarkly policy, baseline-aware CI enforcement, and SARIF findings. -lastUpdated: 2026-06-22 +lastUpdated: 2026-07-01 --- `flaglint validate` checks whether source files comply with migration policy. @@ -18,6 +18,8 @@ lastUpdated: 2026-06-22 | `--config ` | Use an explicit config file. | | `--baseline ` | Baseline file for comparing against known debt. | | `--fail-on-new` | Exit 1 if any findings are not in the baseline. | +| `--quiet` / `-q` | Suppress all progress output. Only errors appear on stderr. Useful in scripts and CI pipelines where only the exit code matters. | +| `--verbose` | Show per-file scan progress (updates on every file instead of every 50). | ## Blocking Policy Command diff --git a/src/content/docs/docs/quickstart.md b/src/content/docs/docs/quickstart.md index 4b04ab0..1e132cb 100644 --- a/src/content/docs/docs/quickstart.md +++ b/src/content/docs/docs/quickstart.md @@ -1,7 +1,7 @@ --- title: Quickstart description: Run your first FlagLint audit, inspect inventory, preview migration, and enforce the boundary in CI. -lastUpdated: 2026-05-28 +lastUpdated: 2026-07-01 --- ## Requirements @@ -11,6 +11,18 @@ lastUpdated: 2026-05-28 Browser SDKs, React SDKs, non-Node SDKs, and non-LaunchDarkly providers are outside current detection coverage. +## 0. Scaffold a Config (Optional) + +If you don't have a `flaglint.config.json` yet, scaffold one with all fields set to their defaults: + +```bash +npx flaglint init +``` + +This writes `flaglint.config.json` to the current directory and prints a short explanation of every field to stderr. You can skip this step — FlagLint works with sensible defaults out of the box — but it's useful when you need to customize `include`/`exclude` patterns or configure `wrappers`. + +See the [`flaglint init` reference](/docs/cli/init/) and [Configuration reference](/docs/cli/configuration/) for details. + ## 1. Run an Audit ```bash diff --git a/src/content/docs/docs/reference/changelog.md b/src/content/docs/docs/reference/changelog.md index c693704..99eba5d 100644 --- a/src/content/docs/docs/reference/changelog.md +++ b/src/content/docs/docs/reference/changelog.md @@ -1,12 +1,30 @@ --- title: Changelog description: Recent FlagLint releases and what changed. -lastUpdated: 2026-06-22 +lastUpdated: 2026-07-01 tableOfContents: false --- import { LinkCard } from '@astrojs/starlight/components'; +## [1.1.0] — 2026-07-01 + +### Added + +- **React SDK import-verified detection** — hooks (`useFlags`, `useLDClient`, `useVariation`), HOC (`withLDConsumer`), and provider (`LDProvider`, `asyncWithLDProvider`) are now detected via verified import chains from `launchdarkly-react-client-sdk`. Previously these patterns were outside detection scope entirely. +- **Wrapper detection v2 — object form** — `wrappers` config now accepts `{ import, function, flagKeyArgument }` objects that match only when the function is imported from the specified package. Prevents false positives from unrelated functions with the same name. +- **`flaglint init`** — new command that scaffolds `flaglint.config.json` with all fields at their defaults. Warns if a higher-precedence config file would shadow the new file. Exits `2` if the file already exists without `--force`. +- **`flaglint completion`** — new command that outputs shell completion scripts for bash, zsh, and fish. Tab-completes subcommands, flags, and flag values. +- **`--quiet` / `--verbose` global flags** — `--quiet` (`-q`) suppresses all progress output; only errors appear on stderr. Useful in scripts and CI pipelines where only the exit code matters. `--verbose` lowers the spinner update threshold for more detailed progress on large codebases. +- **GitHub Action `version` input** — the `flaglint/flaglint` composite action now accepts a `version` input for pinning to a specific release instead of always using `@latest`. + +### Fixed + +- **Provider validation** — the `provider` config field now validates the supplied value. Unsupported providers exit `2` with a clear error message. Only `launchdarkly` is currently supported. +- **Bootstrap pattern matching** — the `--bootstrap-exclude` glob matcher now uses `micromatch` instead of a hand-rolled glob converter. Patterns that previously failed to match edge cases (e.g. complex brace expansions) now work correctly. + +--- + ## [1.0.0] — 2026-06-22 ### Summary diff --git a/src/content/docs/docs/reference/supported-scope.md b/src/content/docs/docs/reference/supported-scope.md index 3bac028..c845dc3 100644 --- a/src/content/docs/docs/reference/supported-scope.md +++ b/src/content/docs/docs/reference/supported-scope.md @@ -1,7 +1,7 @@ --- title: Supported Scope description: What FlagLint detects, migrates, reports for manual review, and excludes. -lastUpdated: 2026-05-28 +lastUpdated: 2026-07-01 --- FlagLint currently supports LaunchDarkly Node.js server-side SDK evaluation calls in JavaScript and TypeScript from: @@ -9,7 +9,7 @@ FlagLint currently supports LaunchDarkly Node.js server-side SDK evaluation call - `@launchdarkly/node-server-sdk` - legacy `launchdarkly-node-server-sdk` -Browser SDKs, React SDKs, non-Node SDKs, and non-LaunchDarkly providers are outside current detection coverage and do not appear in reports. +React SDK hooks, HOC, and provider are detected and reported for manual review. Browser SDKs, non-Node SDKs, and non-LaunchDarkly providers are outside current detection coverage and do not appear in reports. ## API Coverage @@ -27,7 +27,9 @@ Browser SDKs, React SDKs, non-Node SDKs, and non-LaunchDarkly providers are outs | Configured wrappers | Yes | No | Yes | No | | Ambiguous OpenFeature client binding | Yes | No | Yes | No | | Browser SDKs | No | No | No | Yes | -| React SDKs/hooks/HOCs | No | No | No | Yes | +| React SDK hooks (`useFlags`, `useLDClient`, `useVariation`) | Yes | No | Yes | No | +| React SDK HOC (`withLDConsumer`) | Yes | No | Yes | No | +| React SDK provider (`LDProvider`, `asyncWithLDProvider`) | Yes | No | Yes | No | | Go, Java, Python, or other SDKs | No | No | No | Yes | | Non-LaunchDarkly providers | No | No | No | Yes | @@ -52,6 +54,27 @@ const client = ldInit("sdk-key"); Unrelated functions named `init`, `ldInit`, `client`, `feature`, `flag`, or similar do not establish LaunchDarkly provenance. +## React SDK Detection + +React SDK hooks, HOC, and provider are detected via verified import chains from `launchdarkly-react-client-sdk`: + +```ts +import { useFlags, useLDClient } from "launchdarkly-react-client-sdk"; +// useFlags() and useLDClient() calls are reported for manual review +``` + +```ts +import { withLDConsumer } from "launchdarkly-react-client-sdk"; +// withLDConsumer()(Component) is reported for manual review +``` + +```ts +import { LDProvider, asyncWithLDProvider } from "launchdarkly-react-client-sdk"; +// Provider usage is reported for manual review +``` + +React SDK patterns are reported for manual review and are not auto-migrated. They fall outside the current `flaglint migrate --apply` scope because they require browser/React-specific OpenFeature provider setup that cannot be inferred statically. + ## Feedback - [Edit this page on GitHub](https://github.com/flaglint/flaglint/edit/main/docs-src/content/docs/docs/reference/supported-scope.md)