fix: add JSDoc overloads to stackAnalysisBatch for type narrowing

[a-oren]

Summary

• Add 4 specific @overload JSDoc blocks to stackAnalysisBatch() that narrow return types based on html and batchMetadata arguments
• Matches the existing pattern used by stackAnalysis() and imageAnalysis()
• Eliminates the need for runtime type narrowing in consumers (e.g. VS Code extension)

Related

• feat: add Generate SBOM command to VS Code extension fabric8-analytics/fabric8-analytics-vscode-extension#889 (comment)

Test plan

• JSDoc-only change, no runtime behavior affected
• All existing tests pass (npm test)

🤖 Generated with Claude Code

Summary by Sourcery

Enhancements:

• Introduce JSDoc overloads on stackAnalysisBatch() to provide precise return types based on html and batchMetadata options.

[sourcery-ai]

Reviewer's Guide

Adds four precise JSDoc @overload signatures to stackAnalysisBatch to narrow its Promise return type based on the html flag and batchMetadata option, aligning its typing behavior with stackAnalysis/imageAnalysis while not changing runtime behavior.

Class diagram for stackAnalysisBatch JSDoc overloads

classDiagram
    class stackAnalysisBatch {
        <<function>>
        +Promise stackAnalysisBatch(workspaceRoot string, html true, opts OptionsBatchMetadataTrue)
        +Promise stackAnalysisBatch(workspaceRoot string, html true, opts OptionsBatchMetadataFalseOrUndef)
        +Promise stackAnalysisBatch(workspaceRoot string, html false, opts OptionsBatchMetadataTrue)
        +Promise stackAnalysisBatch(workspaceRoot string, html false, opts OptionsBatchMetadataFalseOrUndef)
        +Promise stackAnalysisBatch(workspaceRoot string, html boolean, opts Options)
    }

    class Options {
        +number batchConcurrency
        +boolean continueOnError
        +boolean batchMetadata
        +string[] discoveryIgnores
    }

    class OptionsBatchMetadataTrue {
        +boolean batchMetadata = true
    }

    class OptionsBatchMetadataFalseOrUndef {
        +boolean batchMetadata = false
    }

    class BatchAnalysisMetadata {
        +number totalPackages
        +number successfulAnalyses
        +number failedAnalyses
        +string[] sbomErrors
        +string[] validationErrors
    }

    class AnalysisReport {
    }

    class HtmlBatchResultWithMetadata {
        +string analysis
        +BatchAnalysisMetadata metadata
    }

    class JsonBatchResultWithMetadata {
        +AnalysisReportByPath analysis
        +BatchAnalysisMetadata metadata
    }

    class AnalysisReportByPath {
        +AnalysisReport reportsByPath
    }

    stackAnalysisBatch ..> Options : uses
    stackAnalysisBatch ..> OptionsBatchMetadataTrue : narrows
    stackAnalysisBatch ..> OptionsBatchMetadataFalseOrUndef : narrows
    stackAnalysisBatch ..> BatchAnalysisMetadata : returns
    stackAnalysisBatch ..> AnalysisReport : returns
    stackAnalysisBatch ..> HtmlBatchResultWithMetadata : returns
    stackAnalysisBatch ..> JsonBatchResultWithMetadata : returns

    OptionsBatchMetadataTrue --|> Options
    OptionsBatchMetadataFalseOrUndef --|> Options

    HtmlBatchResultWithMetadata *-- BatchAnalysisMetadata
    JsonBatchResultWithMetadata *-- BatchAnalysisMetadata
    JsonBatchResultWithMetadata *-- AnalysisReportByPath
    AnalysisReportByPath *-- AnalysisReport

Loading

File-Level Changes

Change	Details	Files
Add JSDoc overloads to stackAnalysisBatch to provide typed return shapes for HTML vs JSON and metadata vs non-metadata calls.	Introduce overload for HTML output with batchMetadata: true returning { analysis: string, metadata: BatchAnalysisMetadata } Introduce overload for HTML output with batchMetadata false/omitted returning a string HTML report Introduce overload for JSON output with batchMetadata: true returning { analysis: Record<string, AnalysisReport>, metadata: BatchAnalysisMetadata } Introduce overload for JSON output with batchMetadata false/omitted returning Record<string, AnalysisReport> Annotate the main stackAnalysisBatch JSDoc with @overload to tie the specific overloads to the implementation signature	src/index.js

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

Hey - I've found 1 issue, and left some high level feedback:

• The final JSDoc block for stackAnalysisBatch (the implementation signature) should not be marked with @overload, otherwise TypeScript may treat it as another overload rather than the implementation; drop @overload from that last block and keep it only on the four specific overload signatures.
• To avoid duplicating long generic return types, consider extracting the Object.<string, AnalysisReport> shape and the { analysis, metadata } shape into named JSDoc typedefs and referencing those in the overloads to keep the comments more maintainable.

Prompt for AI Agents

Please address the comments from this code review:

## Overall Comments
- The final JSDoc block for `stackAnalysisBatch` (the implementation signature) should not be marked with `@overload`, otherwise TypeScript may treat it as another overload rather than the implementation; drop `@overload` from that last block and keep it only on the four specific overload signatures.
- To avoid duplicating long generic return types, consider extracting the `Object.<string, AnalysisReport>` shape and the `{ analysis, metadata }` shape into named JSDoc typedefs and referencing those in the overloads to keep the comments more maintainable.

## Individual Comments

### Comment 1
<location path="src/index.js" line_range="451-460" />
<code_context>
  * SBOMs are generated in parallel (see `batchConcurrency`) unless `continueOnError: false` (fail-fast sequential).
  * With `opts.batchMetadata` / `TRUSTIFY_DA_BATCH_METADATA`, returns `{ analysis, metadata }` including validation and SBOM errors.
  *
+ * @overload
  * @param {string} workspaceRoot - Path to workspace root (containing lock file and workspace config)
  * @param {boolean} [html=false] - true returns HTML, false returns JSON report
  * @param {Options} [opts={}] - `batchConcurrency`, discovery ignores, `continueOnError` (default true), `batchMetadata` (default false)
</code_context>
<issue_to_address>
**issue:** The non-specific, final JSDoc block for this function probably should not be tagged with `@overload`.

In TypeScript JSDoc, `@overload` should only annotate the overload signatures; the concrete implementation docblock should omit it. Tagging this final, general block with `@overload` can mislead tooling and produce incorrect type resolution. Please remove `@overload` from the last block so it’s treated as the implementation signature, leaving the earlier blocks as the overloads.
</issue_to_address>

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

_{Help me be more useful! Please click 👍 or 👎 on each comment and I'll use the feedback to improve your reviews.}