Refactor (packages/opencode/src/session/instruction.ts): Function with high complexity

[zachkfan]

P1B: Starter Task: Refactoring PR

1. Issue

Link to the associated GitHub issue:
#96

Full path to the refactored file:
packages/opencode/src/session/instruction.ts

What do you think this file does?
(Your answer does not have to be 100% correct; give a reasonable, evidence‑based guess.)
I think what the file is doing is helping to manage instruction files, such as AGENTS.md, CONTEXT.md, etc. It manages these different documents that get injected into the AI agent's context to make sure that it actually follows project convention. This is based on the different functions that also exist in the file, such as systemPaths, which go through all the global and project based instructions files, that were defined earlier in the file as well.

What is the scope of your refactoring within that file?
(Name specific functions/blocks/regions touched.)
Only extract() (previously lines 17–31) was rewritten, and a new helper loadedPaths() was added directly beneath it. No other function in the file was touched (10 insertions, 14 deletions).

Which Qlty‑reported issue did you address?
(Name the rule/metric and include the BEFORE value; e.g., "Cognitive Complexity 18 in render()".)

Function with high complexity (count = 27): extract at line 17, together with Deeply nested control flow (level = 5) at line 26. The file's BEFORE total was High total complexity (count = 75).

2. Refactoring

How did the specific issue you chose impact the codebase's maintainability?
Five levels of nesting meant six conditions had to be held in mind to know when the innermost line ran, which is why a 15-line function scored 27 on a metric that penalizes nesting multiplicatively. Iteration, filtering, and accumulation were tangled together, so no single line expressed which parts actually count and edits had to be made inside the nest.

What changes did you make to resolve the issue?
Replaced three nested for loops and four nested if guards with a flat flatMap pipeline, moving the per-part filtering into a loadedPaths() helper that uses early-return guard clauses. Also collapsed the redundant !loaded || !Array.isArray(loaded) to !Array.isArray(loaded), since Array.isArray already returns false for null/undefined.

How do your changes improve maintainability? Did you consider alternatives?
Splitting the traversal from the filtering rule cuts nesting from 5 levels to 2 and gives the previously-implicit "which parts contribute paths" rule a name. I rejected a single .filter() chain because a boolean filter loses TypeScript's narrowing through the part union, and rejected several smaller helpers because AGENTS.md warns against preemptive single-use extraction.

3. Validation

How did you validate that the change is correct?
bun test test/session/instruction.test.ts passes 9/9 (0 fail) and bun typecheck is clean; bun lint produces no new warnings (repo totals identical before and after). I also confirmed the return type is still Set<string> rather than widening to Set<any>, and that Qlty no longer reports either target smell (file total 75 → 52).

Bun test:

Bun Lint (There was an Identical 698 Warnings and 2 Errors from before changes)

Attach a screenshot of the test coverage showing the lines were executed by the tests.

Uncovered lines mentioned are not lines affected by my changes.

Attach a screenshot showing the tests that cover the change passing during CI

Attach a screenshot of qlty smells --no-snippets <full/path/to/file.ts> showing fewer reported issues after the changes.
Before:

After: