Skip to content

feat!: add standalone Go contract tracer - #1

Open
dominicnunez wants to merge 44 commits into
mainfrom
dev
Open

dominicnunez wants to merge 44 commits into
mainfrom
dev

Conversation

@dominicnunez

@dominicnunez dominicnunez commented Oct 4, 2026 •

Copy link
Copy Markdown
Owner

Add the first standalone Contract Tracer library and CLI to main. Starting from symbols or source locations and an invariant hypothesis, it assembles a bounded investigation scope with source evidence, possible relationships, candidate alternatives, and unresolved boundaries.

The analyzer combines typed calls/references and bounded value flow with SQLite storage, configured event APIs and lifecycle relationships. Configuration is strict and reusable, including database namespaces. Event construction includes typed keyed and positional struct literals; compound, multi-result and range assignments preserve uncertainty, including parenthesized field targets. Explicit same-line initializers retain distinct source owners. Real literal strings remain separate from unresolved spans across events, SQL and lifecycle values. SQL inventory follows the selected module boundary, and roots retain host filesystem lookup semantics. Windows loader workspace aliases are aligned without changing the recorded build or workfile. Global addresses escaping through calls remain candidates; ordinary database query calls use modeled method identities and receiver/query positions, while prepared statements retain query origins through bound and promoted receivers; generic cancellation registrations retain all source-site candidates; uncalled private callbacks retain unresolved inputs alongside known targets. Map lookups preserve typed nil and unknown alternatives alongside historical known candidates through fields, arrays, address loads, local helpers and valid pointer conversions. Generic context constructors preserve parent alternatives for cancellation signals and scheduler relays. Mixed interface calls retain dependency alternatives alongside local candidates so unknown results, callback escapes and map mutation effects remain visible. Bound external methods retain callbacks carried by receiver storage, and WaitGroup interface calls preserve outside alternatives alongside known groups.

Saved JSON/gzip analysis binds source, selected assets, loaded dependency sources, module/workspace inputs and build selections. Fresh and saved analysis verify inputs again before publishing results. Selected Go source paths are compared with captured parser inputs under the saved tests, tags and loader environment; root-local embedded matches in selected target packages are compared with their captured inventory before final content hashes. Output validation prevents reports from overwriting saved/resumed analysis through file, directory, parent-traversal, dangling-link and hard-link aliases. Saved and resumed analysis also rejects publication paths that replace captured inputs or add source-fingerprinted files, including paired report outputs. Explicit configuration files are protected from both snapshot and report outputs, including report-only runs. Report-only outputs also protect existing analyzed sources, embedded assets and module-resolution inputs; a new source-shaped report remains permitted. These checks require a stable filesystem namespace and do not provide atomic filesystem snapshots or sandbox the Go toolchain.

Go 1.27.0 is the minimum. Snapshots from earlier development versions missing architecture feature/experiment settings or the loaded Go source inventory must be regenerated. Root lookup follows the host filesystem, including Windows junction and drive-path forms. On Windows, all report and snapshot destinations reject ambiguous filenames ending in dots or spaces or using stream colons; file identity is checked again after snapshot creation before reporting.

Contributor commit hooks validate formatting/configuration; raw push hooks validate every non-deletion ref against clean tested HEAD before test/vet/build checks. CI runs Go checks and hook helpers on Linux and Windows, plus repository-wide pre-commit validation. Validation includes public-API and actual CLI regressions that fail on prior revisions, saved-analysis round trips, controlled late-input mutations and real Git transport tests. Final publication requires fresh general/security review and all five checks in both push and PR CI on the published head.

Markdown renders report values as literal text with context-specific encoding and visible control characters; JSON retains the original data. Reports retain contract_complete: false. The supplied invariant is a hypothesis, not an automatically verified specification. Reflection, unsafe/cgo, omitted build configurations, unavailable dependency bodies and unmodeled callbacks remain limits. The public tree contains no development reports or project-specific profile.

@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 4, 2026 •

Copy link
Copy Markdown

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review Status Commit Review trigger
📝 Code Review ✅ Completed 2026-10-12T04:25:57.383881Z 3f66e43 New commits
🔒 Security Review ✅ Completed 2026-10-04T11:31:24.645976Z 1c5ed88 PR opened
ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 1c5ed88428

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread go.mod Resolved
Comment thread adapters.go Resolved
Comment thread tools/check_push_state.py Resolved
Comment thread semantic.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 62ced1ce30

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread trace.go Resolved
Comment thread flow.go Resolved
Comment thread semantic.go Resolved
Comment thread storage.go Resolved
Comment thread storage.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: fdd17b1e54

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread semantic.go Resolved
Comment thread semantic.go Resolved
Comment thread trace.go Resolved
Comment thread exploration.go Resolved
Comment thread cmd/contract-trace/main.go Resolved
@dominicnunez dominicnunez changed the title feat: add standalone Go contract tracer feat!: add standalone Go contract tracer Oct 7, 2026

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 421eae7024

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread global_escape.go Resolved
Comment thread sql_handles.go Resolved
Comment thread afterfunc.go Resolved
Comment thread unresolved_functions.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 4891402736

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread semantic.go Resolved
Comment thread adapters.go Resolved
Comment thread semantic.go Resolved
Comment thread trace.go Resolved
Comment thread semantic.go Resolved
Comment thread cmd/contract-trace/main.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: bb534c008e

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread lifecycle.go Resolved
Comment thread callback_escape.go Resolved
Comment thread waitgroup_binding.go Resolved
Comment thread render.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5827a05681

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread cmd/contract-trace/main.go Resolved
Comment thread loaded_sources.go Resolved
Comment thread embedded.go Resolved

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 006ac47a8d

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread cmd/contract-trace/main.go Resolved
Comment thread containers.go Resolved
Comment thread flow.go Resolved
BREAKING CHANGE: Ordinary report outputs reject analyzed input aliases and ambiguous Windows filenames.
Retain nil and unknown alternatives alongside known map lookup candidates.
Carry addressed reference values through fields, arrays, aliases, conversions,
and snapshots without treating a valid address as its nullable contents.
Preserve dependency CHA targets alongside indexed local implementations so existing result and escape models retain outside alternatives. Keep unresolved interface boundaries when no indexed local implementation exists.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 3f66e438db

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

  • Open a pull request for review
  • Mark a draft as ready
  • Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

Comment thread containers.go
Comment on lines +282 to +283
default:
markMapElementAlternative(value, element, true)

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Preserve zero and unknown string map alternatives

When a closed map[string]string lookup uses a dynamic or absent key, mapLookup reaches this default branch, but markMapElementAlternative ignores string types. It therefore retains known entries without adding the possible "" zero value or setting stringUnknown. For a configured value-identity lifecycle call such as Acquire(keys[k]), a missing key can supply the empty string at runtime, yet the report emits only the known lifecycle resources and no unresolved_lifecycle_resource, so an empty-key acquire/release path can disappear.

Useful? React with 👍 / 👎.

Comment thread semantic.go
Comment on lines +114 to +115
if literal, ok := node.(*ast.FuncLit); ok && !executed[literal] {
return false

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Analyze semantic operations in stored package closures

When a package variable stores a function literal that is invoked later, such as var run = func(db *sql.DB) { db.Query("SELECT ...") }, this condition prunes the literal because it is not immediately invoked by the initializer expression. Function literals have no separate entry in ix.funcs, so no later semantic pass visits the body; resolved value flow can connect a caller to the package initializer, but SQL tables, events, and configured API relationships inside the closure are omitted. Analyze stored package closures under an appropriate source owner rather than treating them as dead initializer syntax.

Useful? React with 👍 / 👎.

Comment thread adapters.go
Comment on lines +214 to +216
values, complete := ix.stringCandidates(call.Args[argumentIndex], f, a)
if !complete {
ix.boundaries = append(ix.boundaries, Boundary{Node: id, Kind: "dynamic_api_value", Reason: "configured API value uses flow candidates; additional runtime values may exist", Evidence: ix.evidence(call.Args[argumentIndex].Pos())})

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Reject call-rule arguments that cannot carry strings

When a configured event or SQL rule selects an argument with a statically incompatible type, such as an int parameter, only the index is validated before this expression is interpreted as a string. The rule is marked matched and produces a dynamic_api_value boundary rather than invalid_rule_site, even though no runtime value of that argument can be an event name or query; this masks a configuration typo and leaves the intended API entirely unmodeled. Validate that the selected type is a string or a type that can actually carry a string before applying the rule.

Useful? React with 👍 / 👎.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant