fix: correcting some non-deterministic tests and docs

Author: benjivesterby

.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,43 @@
+# Description
+
+Please describe _what does this Pull Request fix or add?_.
+
+Information that is useful here:
+
+* **The What**: What is your change doing?
+* **The Why**: Why is the change necessary? What is the use case?
+* **Type of change**
+  **Examples:**
+  * Bugfix
+  * New feature
+  * Code Quality Improvement
+  * Dependency Upgrade
+  * Documentation
+* **Breaking change**: Yes or no? Backward compatible?
+* **Related to an issue**: Does this fix or close an issue?
+
+## Examples
+
+Let us know how users can use or test this functionality.
+
+```go
+// Example code
+```
+
+## Checklist
+
+* [ ] Documentation
+  * [ ] Code
+  * [ ] Updated README or /docs/
+* [ ] Unit or Integration tests added
+  * [ ] Good Path
+  * [ ] Error Path
+* [ ] Commits follow conventions described here:
+  * [ ] [Conventional Commits 1.0.0](https://conventionalcommits.org/en/v1.0.0-beta.4/#summary)
+  * [ ] [The seven rules of a great Git commit message](https://chris.beams.io/posts/git-commit/#seven-rules)
+* [ ] Commits are squashed such that
+  * [ ] There is 1 commit per isolated change
+* [ ] I've not made extraneous commits/changes that are unrelated to my change.
+* [ ] I have read the [contributing guide][]
+
+[contributing guide]: https://github.com/devnw/.github/blob/main/CONTRIBUTING.md

README.md

@@ -35,6 +35,13 @@ cd canary
 make build
 ```
 
+## Repository
+
+The code is hosted on GitHub:
+
+- Repository: [Github](https://github.com/devnw/canary)
+- Code Ref: [pkg.go.dev](https://pkg.go.dev/go.devnw.com/canary)
+
 ### Initialize Your Project
 
 ```bash
@@ -545,11 +552,11 @@ We welcome contributions! Please:
 5. Update documentation with DOC= fields
 6. Verify before submitting: `canary scan --verify GAP_ANALYSIS.md`
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
+See [CONTRIBUTING.md](docs/CONTRIBUTING.md) for detailed guidelines.
 
 ## License
 
-Licensed under the terms found in [LICENSE](LICENSE).
+Licensed under the terms found in [LICENSE](https://github.com/devnw/canary/blob/main/LICENSE).
 
 ## Acknowledgments
 

docs/CODE_OF_CONDUCT.md

@@ -0,0 +1,46 @@
+# Community Code of Conduct v1.0
+
+This is Code of Conduct is based on the [CNCF Code of
+Conduct](https://github.com/cncf/foundation/blob/master/code-of-conduct.md).
+See the referred document for translated versions into different languages.
+
+## Contributor Code of Conduct
+
+As contributors and maintainers of this project, and in the interest of fostering
+an open and welcoming community, we pledge to respect all people who contribute
+through reporting issues, posting feature requests, updating documentation,
+submitting pull requests or patches, and other activities.
+
+We are committed to making participation in this project a harassment-free
+experience for everyone, regardless of level of experience, gender, gender
+identity and expression, sexual orientation, disability, personal appearance,
+body size, race, ethnicity, age, religion, or nationality.
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery
+* Personal attacks
+* Trolling or insulting/derogatory comments
+* Public or private harassment
+* Publishing others' private information, such as physical or electronic addresses,
+ without explicit permission
+* Other unethical or unprofessional conduct.
+
+Project maintainers have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are not
+aligned to this Code of Conduct. By adopting this Code of Conduct, project
+maintainers commit themselves to fairly and consistently applying these
+principles to every aspect of managing this project. Project maintainers who do
+not follow or enforce the Code of Conduct may be permanently removed from the
+project team.
+
+This code of conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community.
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project maintainers or [Benji Vesterby](https://github.com/benjivesterby)
+directly via email [benji@devnw.com](mailto:benji@devnw.com).
+
+This Code of Conduct is adapted from the Contributor Covenant
+(<http://contributor-covenant.org>), version 1.2.0, available at
+<http://contributor-covenant.org/version/1/2/0/>

docs/CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# Contributing
+
+We'd love to accept your patches and contributions to this project through the
+process of creating a [pull request][https://github.com/devnw/canary] (**PR**). This document details the
+process of submitting a PR so that it can be reviewed and merged into the
+codebase. It also contains some guidelines for writing good commits, reporting
+issues, and guidelines for project maintainers.
+
+---
+
+## Reporting issues
+
+Bugs, feature requests, and development-related questions should be directed to
+the specific project's issue tracker or discussion board.
+
+### Bugs
+
+If reporting a bug, please submit an issue and provide as much context as
+possible such as your operating system, architecture, library release version,
+Go version (if applicable), and anything else that might be relevant to the bug.
+
+Fill out as much information as possible in the form provided by the issue
+template.
+
+#### SECURITY BUGS
+
+We take security bugs ***VERY*** seriously!
+
+Please promptly report security related bugs to <security@devnw.com>. Please
+follow [responsible disclosure guidelines][SECURITY.md] when publicizing any security related
+information, ensuring that maintainers are aware of the issue and are able to
+address it promptly.
+
+Please include:
+
+1. Information about the vulnerability
+1. Associated CVEs (if any)
+1. Affected release(s)
+1. Affected package(s)
+
+### Feature Requests
+
+For feature requests, please explain what you're trying to do, and
+how the requested feature would help you do that.
+
+Security related bugs can either be reported in the issue tracker, or if they
+are more sensitive, emailed to <security@devnw.com>.
+
+[responsible disclosure guidelines]: https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html
+
+---
+
+## Submitting a Pull Request
+
+  1. It's generally best to start by opening a new issue describing the bug or
+     feature you're intending to fix. Even if you think it's relatively minor,
+     it's helpful to know what people are working on. Mention in the initial
+     issue that you are planning to work on that bug or feature so that it can
+     be assigned to you.
+
+  1. Follow the normal process of [forking][https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo] the project, and setup a new
+     branch to work in. It's important that each group of changes be done in
+     separate branches in order to ensure that a pull request only includes the
+     commits related to that bug or feature.
+    
+  1. This project uses `nix` and `direnv` to manage development environments.
+     Please ensure you have both installed and configured on your system.
+     See the [development environment documentation](./DEVELOPMENT.md) for more
+     information.
+---
+
+## Maintainer's Guide
+
+(These notes are mostly only for people merging in pull requests.)
+
+It is the responsibility of the maintainer to ensure that the code is passing
+all checks and tests. The maintainer should also ensure that the code is
+consistent with the project's [code style][] and [documentation][]. The
+maintainer should also ensure that the code is well-documented and tested
+before merging in a pull request.
+
+[git-aliases]: https://github.com/willnorris/dotfiles/blob/d640d010c23b1116bdb3d4dc12088ed26120d87d/git/.gitconfig#L13-L15
+[rebase-comment]: https://github.com/google/go-github/pull/277#issuecomment-183035491
+[modified-comment]: https://github.com/google/go-github/pull/280#issuecomment-184859046

docs/DEVELOPMENT.md

@@ -0,0 +1,3 @@
+# Development Environment Setup
+
+TBD

docs/SECURITY.md

@@ -0,0 +1,17 @@
+# SECURITY
+
+We take security bugs ***VERY*** seriously!
+
+Please promptly report security related bugs to <security@devnw.com>. Please
+follow [responsible disclosure guidelines][] when publicizing any security related
+information, ensuring that maintainers are aware of the issue and are able to
+address it promptly.
+
+Please include:
+
+1. Information about the vulnerability
+1. Associated CVEs (if any)
+1. Affected release(s)
+1. Affected package(s)
+
+[responsible disclosure guidelines]: https://cheatsheetseries.owasp.org/cheatsheets/Vulnerability_Disclosure_Cheat_Sheet.html

main.go

@@ -5,7 +5,7 @@
 
 package main
 
-// CANARY: REQ=CBIN-101; FEATURE="ScannerCore"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_101_Engine_ScanBasic; BENCH=BenchmarkCANARY_CBIN_101_Engine_Scan; OWNER=canary; UPDATED=2025-09-20
+// CANARY: REQ=CBIN-101; FEATURE="ScannerCore"; ASPECT=Engine; STATUS=TESTED; TEST=TestCANARY_CBIN_101_Engine_ScanBasic; BENCH=BenchmarkCANARY_CBIN_101_Engine_Scan; OWNER=canary; UPDATED=2025-10-15
 import (
 	"encoding/json"
 	"flag"

scan_test.go

@@ -13,8 +13,8 @@ import (
 
 func TestAcceptance_ParseAndSummarizeFixture_WithPromotion(t *testing.T) {
 	dir := t.TempDir()
-	mustWrite(t, filepath.Join(dir, "file1.zig"), `// CANARY: REQ=REQ-GQL-042; FEATURE="CDC/Streaming"; ASPECT=API; STATUS=STUB; TEST=tests/e2e_cdc.zig:TestCANARY_REQ_GQL_042_StartStop; OWNER=streaming; UPDATED=2025-09-20`)
-	mustWrite(t, filepath.Join(dir, "file2.go"), `// CANARY: REQ=REQ-GQL-046; FEATURE="TDE"; ASPECT=Storage; STATUS=IMPL; TEST=TestCANARY_REQ_GQL_046_KeyRotate; OWNER=security; UPDATED=2025-09-20`)
+	mustWrite(t, filepath.Join(dir, "file1.zig"), `// CANARY: REQ=REQ-GQL-042; FEATURE="CDC/Streaming"; ASPECT=API; STATUS=STUB; TEST=tests/e2e_cdc.zig:TestCANARY_REQ_GQL_042_StartStop; OWNER=streaming; UPDATED=2025-10-15`)
+	mustWrite(t, filepath.Join(dir, "file2.go"), `// CANARY: REQ=REQ-GQL-046; FEATURE="TDE"; ASPECT=Storage; STATUS=IMPL; TEST=TestCANARY_REQ_GQL_046_KeyRotate; OWNER=security; UPDATED=2025-10-15`)
 
 	rep, err := Scan(dir)
 	if err != nil {
@@ -35,7 +35,7 @@ func TestAcceptance_ParseAndSummarizeFixture_WithPromotion(t *testing.T) {
 
 func TestAcceptance_PromotionToBenched(t *testing.T) {
 	dir := t.TempDir()
-	mustWrite(t, filepath.Join(dir, "file3.zig"), `// CANARY: REQ=REQ-GQL-050; FEATURE="RecursiveQuery"; ASPECT=Planner; STATUS=IMPL; BENCH=BenchmarkCANARY_REQ_GQL_050_RecursivePerf; UPDATED=2025-09-20`)
+	mustWrite(t, filepath.Join(dir, "file3.zig"), `// CANARY: REQ=REQ-GQL-050; FEATURE="RecursiveQuery"; ASPECT=Planner; STATUS=IMPL; BENCH=BenchmarkCANARY_REQ_GQL_050_RecursivePerf; UPDATED=2025-10-15`)
 	rep, err := Scan(dir)
 	if err != nil {
 		t.Fatalf("scan: %v", err)
@@ -53,7 +53,7 @@ func TestAcceptance_VerifyFailsOnOverclaim(t *testing.T) {
 
 	// repo with only STUB marker
 	dir := t.TempDir()
-	mustWrite(t, filepath.Join(dir, "cdc.zig"), `// CANARY: REQ=REQ-GQL-042; FEATURE="CDC"; ASPECT=API; STATUS=STUB; UPDATED=2025-09-20`)
+	mustWrite(t, filepath.Join(dir, "cdc.zig"), `// CANARY: REQ=REQ-GQL-042; FEATURE="CDC"; ASPECT=API; STATUS=STUB; UPDATED=2025-10-15`)
 
 	rep, _ := Scan(dir)
 	claims, _ := ParseGAPClaims(p)

tools/canary/internal/tools/canary/testdata/updatestale/test.go

@@ -1,5 +1,5 @@
 package test
-// CANARY: REQ=CBIN-001; FEATURE="StaleToken"; ASPECT=API; STATUS=TESTED; TEST=Test1; UPDATED=2025-10-19
+// CANARY: REQ=CBIN-001; FEATURE="StaleToken"; ASPECT=API; STATUS=TESTED; TEST=Test1; UPDATED=2025-10-20
 // CANARY: REQ=CBIN-002; FEATURE="FreshToken"; ASPECT=CLI; STATUS=TESTED; TEST=Test2; UPDATED=2025-10-15
 // CANARY: REQ=CBIN-003; FEATURE="StaleImplNotUpdated"; ASPECT=Engine; STATUS=IMPL; UPDATED=2024-01-01
-// CANARY: REQ=CBIN-004; FEATURE="StaleBenchedToken"; ASPECT=Storage; STATUS=BENCHED; BENCH=Bench4; UPDATED=2025-10-19
+// CANARY: REQ=CBIN-004; FEATURE="StaleBenchedToken"; ASPECT=Storage; STATUS=BENCHED; BENCH=Bench4; UPDATED=2025-10-20

tools/canary/main_test.go

@@ -24,13 +24,13 @@ func TestCANARY_CBIN_101_Engine_ScanBasic(t *testing.T) {
 	dir := t.TempDir()
 	fixtures := map[string]string{
 		"file1.go": `package p
-// CANARY: REQ=CBIN-200; FEATURE="Alpha"; ASPECT=API; STATUS=STUB; UPDATED=2025-09-20
+// CANARY: REQ=CBIN-200; FEATURE="Alpha"; ASPECT=API; STATUS=STUB; UPDATED=2025-10-15
 `,
 		"file2.go": `package p
-// CANARY: REQ=CBIN-201; FEATURE="Bravo"; ASPECT=CLI; STATUS=IMPL; UPDATED=2025-09-20
+// CANARY: REQ=CBIN-201; FEATURE="Bravo"; ASPECT=CLI; STATUS=IMPL; UPDATED=2025-10-15
 `,
 		"file3.go": `package p
-// CANARY: REQ=CBIN-202; FEATURE="Charlie"; ASPECT=Engine; STATUS=IMPL; UPDATED=2025-09-20
+// CANARY: REQ=CBIN-202; FEATURE="Charlie"; ASPECT=Engine; STATUS=IMPL; UPDATED=2025-10-15
 `,
 	}
 	for name, content := range fixtures {
@@ -77,7 +77,7 @@ func setupFixture(tb testing.TB, numFiles int) string {
 	dir := tb.TempDir()
 	for i := 0; i < numFiles; i++ {
 		content := fmt.Sprintf(`package p
-// CANARY: REQ=CBIN-%03d; FEATURE="Feature%d"; ASPECT=API; STATUS=IMPL; UPDATED=2025-09-20
+// CANARY: REQ=CBIN-%03d; FEATURE="Feature%d"; ASPECT=API; STATUS=IMPL; UPDATED=2025-10-15
 `, i, i)
 		if err := os.WriteFile(filepath.Join(dir, fmt.Sprintf("file%d.go", i)), []byte(content), 0o644); err != nil {
 			tb.Fatal(err)