Skip to content

feat(javascript): resolve exact package import aliases - #1862

Merged
morluto merged 7 commits into
morluto:mainfrom
mvanhorn:fix/package-imports-aliases
Oct 11, 2026
Merged

morluto merged 7 commits into
morluto:mainfrom
mvanhorn:fix/package-imports-aliases

Conversation

@mvanhorn

Copy link
Copy Markdown
Contributor

Summary

Static JavaScript application analysis now resolves exact package-private #alias specifiers against the importer's enclosing package.json imports map. Inventoried local files become resolved application-graph edges instead of external unknowns, and missing, blocked, or out-of-scope aliases keep an unresolved edge with a precise reason.

Fixes #1838

Demo

demo

The sample is a generated local application, not third-party code.

Problem and expected behavior

A package that declares {"imports":{"#config":"./config.cjs"}} and requires #config leaves a real dependency out of the static application graph. On 0b4ce836, that specifier is resolved_path: null, resolution_status: "external", with the limitation "The bare specifier is a Node builtin, package import map, or invalid package name." Node's resolver selects config.cjs.

The graph should resolve exact #alias keys through the nearest enclosing same-container package.json, stopping at a node_modules directory so a nested package cannot inherit an ancestor's map. Selected targets are package-local ./ files with no extension or index fallback. A missing key, explicit null, or out-of-scope alias reports that reason and does not fall through to files, indexes, or another package's map.

Change and scope

Domain lookup classifies # specifiers and exact imports keys. Application path resolution walks the importer's enclosing package scope, then reuses the existing condition, array, and null target selection. Shared CLI and MCP adapters already thread those resolver outcomes into analyze-javascript-application / analyze_javascript_application graphs; no new tool is added.

  • Exact #alias keys resolve relative to the owning package root.
  • Nested node_modules packages use their own imports map.
  • ESM #config is treated as an import alias, not a URL fragment.
  • Wildcard keys (#internal/*), recursive # targets, and external-package import targets remain unresolved with that limitation.

Out of scope: wildcard expansion, recursive alias chasing, external-package targets, TypeScript paths, browser import maps, package installation, network access, and target execution.

Contract and boundary impact

  • Semantic owner and earliest changed stage: domain src/domain/javascript/javascriptPackageImportAliases.ts, then application JavaScriptArtifactPathResolution, before graph relationship construction.
  • CLI and MCP/tool-catalog contract: none. Existing analyze_javascript_application / analyze-javascript-application schemas, names, and adapters are unchanged; resolution outcomes flow through the current resolution_status / resolved_path / limitations fields.
  • Provider, bridge, target-format, or platform compatibility: static JavaScript artifacts only; no Hopper, Ghidra, IDA, or browser provider changes.
  • Evidence, artifact, provenance, or reconstruction contract: original specifier, source path, artifact digest, source range, and container identity are preserved. Unsupported alias forms stay explicit unknowns rather than guessed files.
  • Process execution, authorization, cleanup, or containment impact: none. Resolution reads the inventoried file map only; artifact-root confinement remains enforced.
  • Generated metadata (docs/public/product-catalog.json), package, or installation impact (CI generates and validates ignored catalogs and skills/; edit authored instructions in .agents/skills/reverse-engineer-anything/ and never commit build outputs): authored skill reference javascript-applications.md and docs/javascript-artifact-reconstruction.md updated. Catalog is regenerated by the repo build and is not committed.

Evidence and regression coverage

  • Tests added or updated: domain specifier/lookup/target classification; application enclosing-scope, conditions, arrays, exact-file, missing-key, explicit-null, wildcard, recursive, external-package, reserved #, and foreign-container refusals; Node import/require oracle comparisons including nested packages without an imports field; compiled CLI and stdio MCP graphs on an owned fixture.
  • Base reproduction or other evidence: on 0b4ce836, #config against the fixture above is external with the builtin/import-map limitation. After this change the same specifier is resolved_path: "config.cjs", resolution_status: "resolved".
  • User-visible CLI/MCP output (if applicable): generated local fixture. Root #config → config.cjs (resolved); nested node_modules/fixture #config → node_modules/fixture/local.cjs (resolved); #missing → resolved_path: null, resolution_status: "external", limitation "Package metadata package.json does not define package import alias #missing; it declares #config."
  • Remaining proof gaps: wildcard, recursive, and external-package import targets are intentionally unresolved. Real Hopper/Ghidra and browser lanes do not apply. This host did not rerun a Windows package.

For evidence-bearing changes:

  • Observed, derived, and inferred claims remain distinguishable.
  • Artifact identity, source provenance, and failed attempts remain preserved.
  • Unsupported, incomplete, unavailable, or uncertain outcomes remain visible.

Validation performed

  • npm ci — pass (377 packages added, 378 audited, 0 vulnerabilities)
  • npm run test:focused -- src/domain/javascript/javascriptPackageImportAliases.test.ts src/application/javascript/JavaScriptArtifactPathResolution.test.ts tests/boundary/javascript/packageImportAliases.test.ts tests/acceptance/applications/packageImportAliasesCli.test.ts — pass (4 files, 111 tests; CLI 1255 ms, stdio MCP 3863 ms)
  • npm run check:fast — pass
  • npm run check — pass (typecheck, lint, format:check, knip, metadata:check; 6/6 turbo tasks; architecture guards across 1138 source files; lint 753 warnings, 0 errors)
  • npm run docs:check — pass
  • npm run verify:test-discovery — pass (“Discovered all 839 test files exactly once.”)

Compatibility, safety, and release

  • Breaking changes or migration steps: none. Additive resolution inside the existing application-graph contract. # specifiers that previously stayed external now resolve when an exact enclosing imports key selects an inventoried ./ file; unsupported forms remain unresolved.
  • Real Hopper/Ghidra, browser, or OS coverage: not run. This change is static JavaScript path resolution. CLI/MCP and Node resolver comparisons ran on Linux with Node 24.18.0.
  • Package or release metadata impact: none. No new tool, skill version, or package identity change.
  • Security, privacy, process, or containment review: caller-selected inputs and source evidence remain intact. Same-container package-scope checks and artifact-root confinement are preserved. No network, installation, or target execution is introduced.

Review checklist

  • This PR addresses a concrete problem or an agreed enhancement.
  • The PR has one focused outcome and the title follows type(scope): outcome.
  • Related issue is linked, or the reason for not linking one is stated above.
  • Tests cover changed observable behavior and meaningful failure paths.
  • Owning docs, contracts, and generated metadata are updated where needed.
  • User-visible CLI/MCP changes include representative output.
  • I checked the final diff for secrets, unrelated cleanup, and unsupported claims.

Resolve exact #alias specifiers against the importer's enclosing
package.json imports map using the shared condition, array, and null
target selection. Nested packages keep their own maps; missing keys,
explicit nulls, and out-of-scope aliases report a precise reason.
Wildcard, recursive, and external-package import targets remain
unresolved.
Bound nested #alias requires produce application-graph require edges
from the enclosing package. Node reports MODULE_NOT_FOUND when a nested
package.json has no imports field, without inheriting the ancestor map.
@chatgpt-codex-connector

chatgpt-codex-connector Bot commented Oct 11, 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-11T17:19:57.324247Z e4ccc23 New commits
ℹ️ 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: 208c40463c

ℹ️ 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".

@AWUQAQ

AWUQAQ commented Oct 11, 2026

Copy link
Copy Markdown
Contributor

From the #1838 author's side: this implements the sketched boundary faithfully, including the part I expected to be the subtle one — the enclosing-package walk stopping at node_modules, with all four isolation cases covered (nested map preferred, no ancestor inheritance, no reverse application to the root importer, foreign-container refusal). Nice to see the declared-keys visibility in refusal reasons continue the pattern from #1424. Read-through only from me so far — I haven't run the branch locally.

@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: 5492780737

ℹ️ 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".

@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: 5603a4d842

ℹ️ 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".

@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: cfc07f6cc5

ℹ️ 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".

@morluto
morluto merged commit d28b41e into morluto:main Oct 11, 2026
31 checks passed

@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: e4ccc23402

ℹ️ 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".

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

Labels

area: build Build, CI, packaging, and publishing enhancement New feature or request

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[Feature] Resolve exact package-private import aliases in static application graphs

3 participants