docs(adr): ADR 007 — stable finding fingerprint schema

[Krishan27]

Defines the v1.0 fingerprint schema: provider:callType:flagKey:normalizedFilePath. Foundation for baseline mode and SARIF stability. Part of the v1.0.0 milestone.

Summary by CodeRabbit

Release Notes

• Documentation
  • Added comprehensive architecture documentation for stable finding fingerprints, enabling reliable baseline mode functionality and consistent SARIF identities across scans. Includes fingerprint schema specifications, file path normalization rules, dynamic key handling, refactoring behavior guidelines, known limitations, and implementation guidance.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds docs/adr/007-stable-finding-fingerprints.md, a new Architecture Decision Record defining the v1.0 stable finding fingerprint schema (provider:callType:flagKey:normalizedFilePath), file path normalization rules, dynamic-key indexing, known collision and rename limitations, an implementation checklist, and a consequences summary.

Changes

ADR 007: Stable Finding Fingerprints

Layer / File(s)	Summary
Fingerprint schema, normalization rules, and edge cases docs/adr/007-stable-finding-fingerprints.md	Documents the ADR purpose and primary consumers (baseline matching, SARIF identity), specifies the provider:callType:flagKey:normalizedFilePath schema, path normalization rules (scan-root relative, forward slashes, no ./, no trailing slash), dynamic-key sequential indexing, the known same-file collision case, and rename/move behavior.
Implementation checklist and consequences docs/adr/007-stable-finding-fingerprints.md	Lists implementation steps: add fingerprint to FlagUsage, introduce generateFingerprint(), populate during scanning, include in JSON output, reuse for SARIF identity and baseline artifacts. Summarizes additive schema impact, line-number resilience, v1.1 collision plan, and rename guidance.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~5 minutes

Possibly related issues

• ADR 007: Define stable finding fingerprint schema for FlagLint v1.0 #163: This PR delivers the ADR 007 document that the issue directly requests, including the provider:callType:flagKey:normalizedFilePath schema.
• feat(core): add stable fingerprints to findings and machine-readable output #164: This PR is the ADR specification that the issue's implementation task is based on, covering the FlagUsage fingerprint field and JSON output integration design.
• ADR 007: Define stable finding fingerprint schema for FlagLint v1.0 #149: This PR addresses all acceptance criteria listed in the issue: schema definition, normalization rules, collision tradeoffs, and baseline/SARIF consumer references.
• feat(core): add stable fingerprints to findings and machine-readable output #150: This PR is the ADR specification that the issue tracks as the feature implementation, with matching acceptance criteria for FlagUsage changes and fingerprint stability.
• ADR 008: Define baseline mode for CI adoption #151: This PR documents ADR 007, which is listed as an explicit dependency for ADR 008 (baseline mode for CI adoption) tracked in the issue.

Possibly related PRs

• flaglint/flaglint#160: Adds the same ADR 007 document defining the v1.0 stable finding fingerprints schema, normalization rules, and limitations — directly overlapping content.

Poem

🐇 Hoppity-hop through the codebase I roam,
No line numbers to follow — just fingerprints shown!
provider:callType:flagKey:path in a row,
Stable and tidy wherever flags go.
My baseline won't break when the lines rearrange,
(Just re-run --write-baseline after a file rename!) 🌿

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly and directly describes the main change: documenting ADR 007 for the stable finding fingerprint schema, which is the primary content of the pull request.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/adr-007-stable-fingerprints

---

_{Comment @coderabbitai help to get the list of available commands.}

[cloudflare-workers-and-pages]

Deploying flaglint with    Cloudflare Pages

Latest commit:	ac21535
Status:	⚡️  Build in progress...

View logs

[coderabbitai]

Actionable comments posted: 2

🧹 Nitpick comments (1)

docs/adr/007-stable-finding-fingerprints.md (1)

25-25: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Add language specifiers to fenced code blocks.

The markdownlint linter (MD040) flags three code blocks without language specifiers. Add text to each code fence for compliance:

• Line 25: Schema definition block
• Line 37: Example fingerprints block
• Line 54: Dynamic key example block

📝 Proposed fixes for fenced code block language specifiers

 ### v1.0 fingerprint schema
 
-```
+```text
 provider:callType:flagKey:normalizedFilePath

```diff
 **Example fingerprints:**
-```
+```text
 launchdarkly:boolVariation:checkout-v2:src/checkout/service.ts
 launchdarkly:stringVariation:payment-provider:src/payments/processor.ts

```diff
 For dynamic keys (`isDynamic: true` or `flagKey === "*"`), include a
 sequential index within the file to differentiate multiple dynamic calls:
 
-```
+```text
 launchdarkly:boolVariation:*:src/service.ts:0
 launchdarkly:boolVariation:*:src/service.ts:1

</details>



Also applies to: 37-37, 54-54

<details>
<summary>🤖 Prompt for AI Agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In @docs/adr/007-stable-finding-fingerprints.md at line 25, The markdownlint
linter (MD040) requires all fenced code blocks to have language specifiers. Add
the text language specifier to the opening backticks of the three code blocks
that currently lack them: the Schema definition block (showing the format with
provider:callType:flagKey:normalizedFilePath), the Example fingerprints block
(showing launchdarkly examples), and the Dynamic key example block (showing
dynamic key usage with asterisks). Change each code fence opening from triple
backticks to triple backticks followed by text to satisfy the linter
requirement.

</details>

<!-- cr-comment:v1:b716f6bc887ff35eae073ca5 -->

_Source: Linters/SAST tools_

</blockquote></details>

</blockquote></details>

<details>
<summary>🤖 Prompt for all review comments with AI agents</summary>

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @docs/adr/007-stable-finding-fingerprints.md:

• Around line 49-60: The Dynamic key handling section acknowledges that index
  order may shift but does not sufficiently document the implications. Enhance the
  documentation in this section to explicitly state that sequential indices are
  unstable when code is refactored or reordered, and that developers should
  re-baseline their findings after any refactoring that modifies the order or
  presence of dynamic calls (isDynamic: true or flagKey === "*"). Add a clear
  warning or note that clarifies this limitation and its impact on existing
  baselines.
• Around line 86-87: ADR 007 contains unresolved references to a non-existent
  ADR 008 in the lines discussing SARIF consumer fingerprint usage and baseline
  artifact storage. To fix this, either create the missing ADR 008 document that
  formally documents how SARIF consumers should use fingerprints as result
  identities and how baseline artifacts should store fingerprint arrays, or
  alternatively, inline these design decisions directly into ADR 007 by replacing
  the references to ADR 008 with the actual decision content, ensuring all
  architectural decisions referenced in the document are either documented
  elsewhere or contained within the document itself.

---

Nitpick comments:
In @docs/adr/007-stable-finding-fingerprints.md:

• Line 25: The markdownlint linter (MD040) requires all fenced code blocks to
  have language specifiers. Add the text language specifier to the opening
  backticks of the three code blocks that currently lack them: the Schema
  definition block (showing the format with
  provider:callType:flagKey:normalizedFilePath), the Example fingerprints block
  (showing launchdarkly examples), and the Dynamic key example block (showing
  dynamic key usage with asterisks). Change each code fence opening from triple
  backticks to triple backticks followed by text to satisfy the linter
  requirement.

</details>

<details>
<summary>🪄 Autofix (Beta)</summary>

Fix all unresolved CodeRabbit comments on this PR:

- [ ] <!-- {"checkboxId": "4b0d0e0a-96d7-4f10-b296-3a18ea78f0b9"} --> Push a commit to this branch (recommended)
- [ ] <!-- {"checkboxId": "ff5b1114-7d8c-49e6-8ac1-43f82af23a33"} --> Create a new PR with the fixes

</details>

---

<details>
<summary>ℹ️ Review info</summary>

<details>
<summary>⚙️ Run configuration</summary>

**Configuration used**: defaults

**Review profile**: CHILL

**Plan**: Pro Plus

**Run ID**: `ce638c87-0d39-4174-8b3f-5e005d5bf842`

</details>

<details>
<summary>📥 Commits</summary>

Reviewing files that changed from the base of the PR and between 44c8fc5a16946496f121b1924a56f8b4a880d03b and 76485f08b6f6d1e09309e439227be1d781d71a8c.

</details>

<details>
<summary>📒 Files selected for processing (1)</summary>

* `docs/adr/007-stable-finding-fingerprints.md`

</details>

</details>

<!-- This is an auto-generated comment by CodeRabbit for review status -->