Skip to content

[Phase A · Sidecar] ext-api/i-pkg — @comfyorg/extension-api npm package + docgen + CI - #12103

Closed
christian-byrne wants to merge 4 commits into
ext-api/i-foundationfrom
ext-api/i-pkg
Closed

christian-byrne wants to merge 4 commits into
ext-api/i-foundationfrom
ext-api/i-pkg

Conversation

@christian-byrne

@christian-byrne christian-byrne commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

Sidecar. Independent of i-foundation; stacks directly on #12101. Can land before or after i-foundation.

What's in

  • packages/extension-api/ — @comfyorg/extension-api 0.1.0 npm package wrapper around src/extension-api/ declarations
    • package.json, README.md, tsconfig{,.build,.docs}.json
    • typedoc.json + scripts/build-docs.ts (TypeDoc → Mintlify MDX)
    • .npmignore, .gitignore
  • .github/workflows/extension-api-typecheck.yml (PKG4.D3) — path-filtered typecheck + smoke
  • .github/workflows/extension-api-publish.yml (PKG4.D4) — tag-triggered npm publish --provenance
  • scripts/generate-docs.sh (PKG5.D6) — thin wrapper over pnpm --filter @comfyorg/extension-api docs:build
  • pnpm-lock.yaml — workspace dep for new package

Pending follow-up

PKG6 (separate PR on Comfy-Org/docs) — wire generated MDX into docs.comfy.org.

Draft for review collaboration via inline comments.

┆Issue is synchronized with this Notion page by Unito

@coderabbitai

coderabbitai Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 323dbdbd-c291-4853-bde3-684cd7d27203

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch ext-api/i-pkg

Tip

💬 Introducing Slack Agent: The best way for teams to turn conversations into code.

Slack Agent is built on CodeRabbit's deep understanding of your code, so your team can collaborate across the entire SDLC without losing context.

  • Generate code and open pull requests
  • Plan features and break down work
  • Investigate incidents and troubleshoot customer tickets together
  • Automate recurring tasks and respond to alerts with triggers
  • Summarize progress and report instantly

Built for teams:

  • Shared memory across your entire org—no repeating context
  • Per-thread sandboxes to safely plan and execute work
  • Governance built-in—scoped access, auditability, and budget controls

One agent for your entire SDLC. Right inside Slack.

👉 Get started


Comment @coderabbitai help to get the list of available commands and usage tips.

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

🌐 Website E2E

Tip

All tests passed.

Status ✅ Passed
Report View Report

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

🎨 Storybook: ✅ Built — View Storybook

Details

⏰ Completed at: 05/11/2026, 03:51:54 AM UTC

Links

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

🎭 Playwright: ❌ -3 passed, 3 failed

❌ Failed Tests

📊 Browser Reports
  • chromium: ❌ Deployment failed
  • chromium-2x: View Report
  • chromium-0.5x: View Report
  • mobile-chrome: ❌ Deployment failed

@github-actions

github-actions Bot commented May 9, 2026 •

Copy link
Copy Markdown
Contributor

📦 Bundle Size

⏳ Size data collection in progress…

⚡ Performance

⚠️ Performance tests failed. Check the CI workflow logs.

@christian-byrne
christian-byrne changed the base branch from ecs-vue-hoisted-client-state-hook-api to ext-api/i-foundation May 9, 2026 21:13

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Architect review — ext-api/i-pkg (Phase A · Sidecar)

# Severity File : line Finding Fix
1 HIGH src/extension-api/node.ts:39,46 + src/services/extension-api-service.ts:274,277 Point = [x,y] (tuple) but getPosition() fallback returns { x:0, y:0 } (object); same for Size. The stub PositionData and DimensionsData interfaces use object shape; public type is tuple. Phase B rebase will inherit this mismatch into actual ECS reads. Extension authors coding against const [x,y] = node.getPosition() will get undefined from the fallback. Align stubs: either change public Point/Size to {x,y}/{width,height} objects now, or make the fallback [0,0]/[0,0]. Pick the shape Alex's PositionData component will use and commit to it before this package ships.
2 HIGH src/services/extension-api-service.ts:29-30 pauseTracking/resetTracking are stubbed to no-ops instead of being imported from @vue/reactivity. The comment says "compile and run without a direct dep" — but these no-ops mean setup hooks run with full reactivity tracking active. Any reactive read inside nodeCreated (e.g. node.getTitle()) will accidentally create a dependency on the caller's active scope, exactly the bug this guard is meant to prevent. Phase B ECS dispatch will make this much worse. Import from '@vue/reactivity' directly, or access via vue internals (import { pauseTracking, resetTracking } from '@vue/reactivity'). Vue re-exports them via the package so no extra dep is needed.
3 HIGH src/extension-api/node.ts:30 vs src/world/entityIds.ts:6 Public NodeEntityId = number & brand; internal World stub defines NodeEntityId = string & brand. The service imports from @/world/entityIds (string brand) but the public surface exports number brand. Extension authors receive a NodeHandle.entityId typed number; the ECS-native Phase B will use strings (e.g. "node:graphUuid:42"). This is a semver-breaking surface change forced by the Phase B rebase. Decide the Phase B ID representation now and align public + internal types. If Phase B IDs will be strings, change src/extension-api/node.ts:30 to string & brand before 0.1.0 is published. If integers survive, fix worldInstance.ts. Either way, the mismatch must be resolved before publishing.
4 MEDIUM src/extension-api/index.ts:63 startExtensionSystem is exported from the src/extension-api/ barrel (the internal published entry point). It is an infrastructure boot function — not part of the extension author API. Exporting it from the public contract means extension authors can call it (breaking the singleton boot), and it becomes a semver promise. Move startExtensionSystem behind an explicit @internal marker and remove it from the public barrel. App wiring in app.ts can import it directly from @/services/extension-api-service.
5 MEDIUM src/services/extensionV2Service.ts (whole file) 413-line file that is completely unreferenced — nothing imports it. It imports from @/ecs/world, @/ecs/commands, @/ecs/components, @/ecs/entityIds paths that don't exist. It will fail any pnpm typecheck run that doesn't exclude it. Having two parallel service implementations diverge silently is a Phase B rebase hazard: when extension-api-service.ts evolves, extensionV2Service.ts won't track the changes. Either delete it (it pre-dates the canonical extension-api-service.ts) or, if it's the intended Phase B target shape, promote it to // TODO(Phase B): replace extension-api-service.ts with this and add a failing typecheck that surfaces when @/ecs/* lands. Dead parallel implementations in Phase A create confusion about which file is canonical.
6 MEDIUM src/services/extension-api-service.ts:182-184 Widget name is extracted by parsing the entity ID string (id.lastIndexOf(':')) because a "dedicated WidgetName component" doesn't exist yet. This string-parsing is also used in NodeHandle.widget(name) (line 315-319) for lookup. But WidgetEntityId is publicly typed as number & brand (not a string). The runtime cast widgetId as unknown as string will silently fail when real numeric IDs arrive in Phase B. Do not parse entity IDs for component data. Either introduce a real WidgetNameComponent stub (following the pattern of the other stubs at L83-92), or use the WidgetComponentSchema component (which has a name-equivalent field) for lookup. The as unknown as string cast is a Phase B time-bomb.
7 MEDIUM src/services/extension-api-service.ts:236-253 widget.on('optionChange'), widget.on('propertyChange'), widget.on('beforeSerialize'), widget.on('beforeQueue') all dispatch stub commands (SubscribeWidgetEvent, etc.) that are silently dropped. Extension authors writing against the published API will register handlers that never fire — no warning, no error. Phase C won't fix this retroactively; by then extensions will have "worked fine in dev" (because the world wasn't wired) and broken silently in prod. Emit a console.warn('[extension-api] widget.on("optionChange") is not yet wired — Phase B') for any event channel dispatched as a stub. Same for node.on('executed'/'connected'/'disconnected'/'configured') at L408-410. Make stubs loudly incomplete.
8 LOW src/extension-api/lifecycle.ts:283-322 onNodeMounted/onNodeRemoved are re-exported from @/services/extension-api-service (the internal service), then re-exported again through the barrel. lifecycle.ts is the canonical public declaration file — it should be the implementation source, not a pass-through. The declare function defineNodeExtension declarations in lifecycle.ts (L236-271) are dead types: the real implementations live in the service. This split (types in lifecycle.ts, impls in service, re-exported back through lifecycle.ts) creates a circular-looking dependency path and confuses which file to edit. Keep lifecycle type declarations in lifecycle.ts. Move onNodeMounted/onNodeRemoved implementations to lifecycle.ts (they don't need to live in the service — they only read _currentScope). Have the service export _currentScope and set it; lifecycle.ts reads it. Cleaner separation: service manages scope lifecycle; lifecycle.ts provides the hook API.
9 LOW packages/extension-api/src/index.ts (npm package barrel) The npm package barrel re-exports from @/extension-api/* via tsconfig path alias. If the internal src/extension-api/ barrel (src/extension-api/index.ts) is updated to add/remove exports, the npm package barrel (packages/extension-api/src/index.ts) must be manually kept in sync — there is no validation that catches drift. This is a Phase A problem: the docgen CI does tsc --emitDeclarationOnly against packages/extension-api, so drift will cause the published .d.ts to silently omit types the internal barrel exports. Add a knip or tsc --noEmit check in extension-api-typecheck.yml that imports everything from @comfyorg/extension-api and verifies the set matches src/extension-api/index.ts. Or — simpler — make packages/extension-api/src/index.ts a single-line re-export of @/extension-api/index.ts rather than manually listing individual modules.

Phase readiness summary

Phase B blocker: Findings 1, 2, 3 are breaking. The Point/Size shape mismatch (1) and NodeEntityId number-vs-string split (3) will force a semver-breaking bump on the first Phase B rebase — defeating the purpose of locking a stable surface in Phase A. The no-op pauseTracking (2) will cause reactivity corruption in any extension that reads World components during nodeCreated. These need to be settled before the 0.1.0 tag is applied.

Phase C readiness: Finding 7 (silent stubs) is the most likely source of Phase C surprises. Extensions that look correct in Phase A testing will silently miss optionChange/executed events; by Phase C the ecosystem will have grown expecting the no-op behavior. Loud stub warnings now prevent that.

D9 alignment: The design correctly implements Phase A shape (thin pass-throughs, stable surface, no prototype interception). The extensionV2Service.ts ghost file (finding 5) is the only item that threatens to blur the Phase A/B boundary by having an alternate "what Phase B looks like" implementation that diverges silently.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Adversarial review — Minimalist (codex)

Hickey/Carmack/Sussman lens: cut what isn't earning its keep.

# Severity Location Issue Suggested fix
1 High packages/extension-api/src/index.ts (78 lines) vs src/extension-api/index.ts (126 lines) Two divergent barrel files for the same surface. package.json exports points to the package barrel (tsc compiles packages/extension-api/src/), but typedoc.json reads ../../src/extension-api/index.ts. Result: published types and generated docs describe different APIs. The package barrel is missing defineWidgetExtension runtime impl, startExtensionSystem, DOMWidgetOptions, WidgetOptionChangeEvent, WidgetPropertyChangeEvent and routes lifecycle fns through lifecycle instead of services/extension-api-service. AGENTS.md only blesses one barrel — the canonical src/extension-api/index.ts. Delete packages/extension-api/src/index.ts. Point tsconfig.json include and package.json exports/types at the canonical src/extension-api/index.ts (matches typedoc). One source of truth.
2 Medium packages/extension-api/scripts/build-docs.ts L366–382 Dead code: byGroup is built then immediately discarded; sortedByGroup is rebuilt from scratch with the same logic. Keep one map, sort stems once before the loop, delete byGroup. Saves ~10 lines.
3 Medium build-docs.ts L33–231 (PAGE_META, ~190 lines) Hardcoded title/description/icon for every export, shadowing the TSDoc that already lives on the source declarations. Renaming or adding an export silently falls through to the generic fallback metaFor and ships with description: 'API reference for X.'. Two sources of truth for descriptions. Drop everything except group + order (the only thing TypeDoc can't supply). Let TypeDoc emit titles/descriptions from @packageDocumentation / leading TSDoc. ~150 LOC gone, ownership lives next to the code.
4 Low build-docs.ts L453–467 (--watch mode) 20 lines of bespoke fs.watch + debounce + try/catch that nobody will use — anyone editing docs reruns pnpm docs:build. Delete watch mode and the docs:watch script, or replace with tsx watch scripts/build-docs.ts.
5 Low scripts/generate-docs.sh (28 lines) Wrapper around a one-line pnpm --filter @comfyorg/extension-api docs:build. The "Copy to docs repo" hint is just echo. Adds shell-portability surface area for zero leverage. Delete the script; document the pnpm command in packages/extension-api/README.md.
6 Low .github/workflows/extension-api-typecheck.yml L60–67 (smoke step) if [ -d test/smoke ] guards a fixture that isn't in this PR, so the step prints "skipping" forever. Configurability for a feature that doesn't exist. Either commit a 5-line test/smoke/ fixture in this PR, or delete the step until the fixture lands.
7 Low build-docs.ts L244–249 (metaFor key vs slug) metaFor strips digits (replace(/[^a-z]/g, '')) while slug keeps them (/[^a-z0-9]+/g). Any future stem with digits (e.g. widgetV2) hits the fallback while its file lands at widgetv2.mdx. Reuse slug (or its lowercase letters-only sibling) consistently for both.
8 Note PR description vs diff scope Description says "package wrapper + workflows + docgen + lockfile". Actual diff is 287 files / ~11k LOC including 165+ BC test files, extension-api-service.ts (643 lines), extensionV2Service.ts (413 lines), scope-registry, ECS world skeleton, etc. Reviewers can't tell what's in scope. Rebase onto the listed predecessor PRs so the diff matches the description, or update the description to enumerate the full surface.

Bottom line. The biggest wins are #1 (remove the duplicate barrel — it's actively diverging) and #3 (delete PAGE_META — its existence will rot the moment a description changes upstream). Everything else is nice-to-have.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Adversarial Review — Skeptic Role

Severity Location Issue
🔴 High extension-api-service.ts:273-277 Type mismatch: returns object, declared tuple
🔴 High extension-api-service.ts:29-30 pauseTracking/resetTracking stubs cause reactivity bugs
🔴 High extension-api-service.ts:334 dispatch stub returns undefined, cast to WidgetEntityId
🟠 Medium extension-api-service.ts:184-186 Widget name via string parsing is fragile
🟠 Medium extension-api-service.ts:252-253, 416-417 Silent no-op for unknown events
🟠 Medium node.ts:30 vs service NodeEntityId branded as number but used as string
🟡 Low extension-api-service.ts:596-612 Entities existing before startExtensionSystem() aren't mounted
🟡 Low build-docs.ts:407 Uses npx instead of pnpx

🔴 HIGH: getPosition/getSize return wrong shape

File: src/services/extension-api-service.ts:273-277

getPosition(): Point {
  return world.getComponent(nodeId, PositionKey)?.pos ?? { x: 0, y: 0 }
}
getSize(): Size {
  return world.getComponent(nodeId, DimensionsKey)?.size ?? { width: 0, height: 0 }
}

Problem: Point is declared as [x: number, y: number] tuple, Size as [width: number, height: number]. The fallback returns { x: 0, y: 0 } — an object, not a tuple. Extensions calling const [x, y] = node.getPosition() will get undefined for both destructured values.

Fix: Return [0, 0] for Point, [0, 0] for Size.


🔴 HIGH: pauseTracking/resetTracking are no-op stubs

File: src/services/extension-api-service.ts:29-30

const pauseTracking = (): void => {}
const resetTracking = (): void => {}

Problem: These ARE exported from @vue/reactivity (they're not truly "internal"). The stub means reactive dependencies can be accidentally captured during nodeCreated/loadedGraphNode setup, causing:

  1. Memory leaks (effects never cleaned up properly)
  2. Unexpected re-execution of setup logic when unrelated reactive state changes

Fix: Import from @vue/reactivity:

import { pauseTracking, resetTracking } from '@vue/reactivity'

🔴 HIGH: dispatch() stub + unsafe cast = createWidgetHandle(undefined)

File: src/services/extension-api-service.ts:327-335

addWidget(type, name, defaultValue, options) {
  const widgetId = dispatch({
    type: 'CreateWidget',
    ...
  }) as WidgetEntityId  // ← cast
  return createWidgetHandle(widgetId)  // ← widgetId is undefined
}

Problem: When dispatch() is stubbed (which it is until #11939 lands), it returns undefined. The as WidgetEntityId cast silences TypeScript, then createWidgetHandle(undefined) is called. Inside that function, world.getComponent(undefined, ...) will either throw or return garbage.

Fix: Either:

  1. Throw an explicit error when dispatch is stubbed and a return value is expected
  2. Generate a placeholder entity ID from the stub for testing purposes
  3. Document that addWidget() is non-functional until ECS lands

🟠 MEDIUM: Widget name extracted via string parsing

File: src/services/extension-api-service.ts:184-186

get name() {
  const raw = widgetId as unknown as string
  const lastColon = raw.lastIndexOf(':')
  return lastColon !== -1 ? raw.slice(lastColon + 1) : raw
}

Problem: If widget names contain colons (legal in ComfyUI), this returns a truncated name. If the entity ID format changes, this silently breaks. The TODO references #11939 but this code ships to npm now.

Fix: Add validation or use a proper component lookup instead of string parsing.


🟠 MEDIUM: Silent no-op for unknown event names

File: src/services/extension-api-service.ts:252-253

// Unknown event → silent no-op
return () => {}

Problem: If an extension subscribes to a misspelled event (node.on('excuted', handler)), it silently gets a no-op unsubscribe with zero feedback. The extension appears to work but never receives events.

Fix: In DEV mode, warn when an unknown event name is passed.


🟠 MEDIUM: NodeEntityId branded as number but is string

File: src/extension-api/node.ts:30

export type NodeEntityId = number & { readonly __brand: 'NodeEntityId' }

File: src/services/extension-api-service.ts:136-137 (comment)

// Key: `${extensionName}:${nodeEntityId}` — unambiguous because NodeEntityId
// already embeds a `node:` prefix (format: `node:${graphUuid}:${nodeId}`).

Problem: The public API declares NodeEntityId as number, but the implementation assumes it's a string with format node:graphUuid:nodeId. Extensions using typeof id === 'number' checks will break.

Fix: Either change the branded type to string or ensure the implementation actually uses numbers.


🟡 LOW: Pre-existing entities not mounted

File: src/services/extension-api-service.ts:596-612

Problem: The watch in startExtensionSystem() only fires on changes. If the World already contains NodeType entities before startExtensionSystem() is called, they won't be mounted. This could cause race conditions during app initialization.

Fix: Mount existing entities on first call:

const initialIds = world.entitiesWith(NodeTypeKey)
for (const id of initialIds) mountExtensionsForNode(id)
// Then set up the watch

🟡 LOW: build-docs.ts uses npx

File: packages/extension-api/scripts/build-docs.ts:407

execSync(`npx typedoc ...`)

Problem: Project mandate says "never npx, always pnpm/pnpx".

Fix: Use pnpx typedoc or pnpm exec typedoc.


Note: The PR description already identifies 9 architectural issues. This review focuses on additional concrete failure modes in the shipped code.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

Regression-risk review (agent: codex)

Severity File:Line Issue Suggested fix
none — No findings —

Method. Per .agents/checks/regression-risk.md: ran git blame on the base (merge-base origin/main HEAD = 8f68be5) for every line range modified in this PR.

Scope of mutated existing files (the only files where regression-risk applies; the rest of the diff is new files):

  • AGENTS.md — docs only, ignored.
  • package.json — adds 3 new test:extension-api* scripts. Pure insertion.
  • src/extensions/core/index.ts — adds 6 import './*.v2' lines. Pure insertion, no removals.
  • src/scripts/app.ts — adds an import block + 3 call sites (startExtensionSystem(), invokeV2AppExtensions('init'|'setup')). Pure insertion next to lines authored by cce11bb639a (Move extension related functions, 2024‑12‑25 — refactor, not a bugfix).
  • src/services/extensionService.ts — adds a _warnedBeforeRegisterNodeDef Set + a deprecation-warn block inside invokeExtensionsAsync. Pure insertion. Surrounding blame:
    • b3da6cf1b43 "Contextmenu extension migration (#5993)" — migration, not a bugfix.
    • 4fc1d2ef5b3 "feat: No Explicit Any (#8601)" — feature, not a bugfix.

No removed/changed lines in any modified file have blame pointing at a bugfix commit (no fix:, bug, patch, hotfix, revert, regression, or CVE in blame subjects, after filtering trivial lint/typo/format fixes per spec).

The PR is overwhelmingly additive (new packages/extension-api, new src/extension-api*, new extension-api-service.ts, ~270 new BC test files, new CI workflows). Additive surface carries its own risk class (compat/coupling), but that is out of scope for this check, which targets bugfix-line mutation.

Verdict: no regression-risk blockers per .agents/checks/regression-risk.md.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

import-graph review (check: .agents/checks/import-graph.md)

Ran dependency-cruiser@17.4.0 --no-config over src/ (with TS path resolution). Filtered the result to changes introduced by this PR vs. origin/main merge-base.

Severity File:Line Issue Suggested fix
blocker src/extensions/core/index.ts:24 import './noteNode.v2' — file src/extensions/core/noteNode.v2.ts does not exist. Bundler will fail to resolve. Remove the import or add the missing module.
blocker src/extensions/core/index.ts:29 import './rerouteNode.v2' — file src/extensions/core/rerouteNode.v2.ts does not exist. Remove the import or add the missing module.
blocker src/extensions/core/index.ts:35 import './slotDefaults.v2' — file src/extensions/core/slotDefaults.v2.ts does not exist. Remove the import or add the missing module.
recommended src/services/extensionV2Service.ts (entire 413-line file) Orphan module — grep -r 'extensionV2Service' finds no consumer anywhere in src/, packages/, app entry, or tests. Two parallel "extension v2" services (extensionV2Service.ts and extension-api-service.ts) is also confusing for readers/extension authors. Per check rule "Orphan modules → nitpick (category: dx)" — but escalated because this is brand-new dead code, not legacy. Delete, wire it up, or document as scaffolding behind a follow-up issue.
recommended src/types/extensionV2.ts (entire 30-line file) Orphan — only imported by the orphan extensionV2Service.ts. Same as above.
nit — src/extension-api/{events,node,shell,widget}.ts show as orphans inside src/ but are re-exported by packages/extension-api/src/index.ts (the published npm barrel) and are exempt per AGENTS.md. Not a real finding — documented for completeness. none

Circular-dependency scan

This PR introduces zero new circular dependencies in src/. The pre-existing cycles in src/scripts/{app,ui,utils,ui/*}.ts, src/lib/litegraph/, and src/extensions/core/groupNode* are unchanged by this diff. The new src/extension-api/ and src/services/extension-api-service.ts modules are cleanly isolated from the legacy graph.

The 31 extensions/core/index.ts ↔ services/extensionService.ts ↔ extensions/core/*.ts cycles surfaced by the cruiser run are pre-existing (the only edits to index.ts here are the six .v2 import lines).

Method

  • pnpm dlx dependency-cruiser --no-config --output-type json --do-not-follow node_modules --include-only "^src" --ts-config tsconfig.json src
  • Cross-checked circulars against origin/main to filter pre-existing cycles.
  • Verified missing-file blockers with ls src/extensions/core/{noteNode,rerouteNode,slotDefaults}.v2.ts.

@christian-byrne christian-byrne left a comment

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

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

sonarjs-lint — clean ✅

Ran eslint-plugin-sonarjs (v4.0.3, recommended ruleset per .agents/checks/eslint.strict.config.js) against the changed .ts/.js/.vue files in this PR.

In-scope files (per check file ignores: **/*.test.*, **/*.spec.*, **/*.config.*, workflows/JSON/lockfiles/shell scripts not lintable):

  • packages/extension-api/src/index.ts

The other six PR files are non-lintable for this check (2× workflow YAML, 2× tsconfig JSON, .npmignore, pnpm-lock.yaml, scripts/generate-docs.sh).

Severity File:Line Issue Suggested fix
— — No SonarJS findings —

Notes

  • packages/extension-api/src/index.ts is a pure re-export barrel — no executable logic, so bug-detection rules (duplicated branches, element overwrite, identical conditions, one-iteration loops, empty return values) and complexity rules (cognitive-complexity threshold 15) do not apply.
  • sonarjs/no-duplicate-string (threshold 3) is not triggered: the most-repeated module specifier (@/extension-api/lifecycle, @/extension-api/identifiers) appears only twice each (once as export type, once as runtime export).
  • Code-smell rules (redundant booleans, small switches, nested template literals, prefer-immediate-return, prefer-single-boolean-return, inverted boolean check) — N/A in a barrel file.

Reviewer caveats

  • Rules sonarjs/no-one-iteration-loop, no-redundant-jump, and no-gratuitous-expressions listed in .agents/checks/eslint.strict.config.js were removed/renamed in eslint-plugin-sonarjs v4. Strict-config invocation in step 4 of sonarjs-lint.md errors with Could not find "no-one-iteration-loop" in plugin "sonarjs". Falling back to sonarjs.configs.recommended (which still covers all bug-detection categories listed in the check) plus @typescript-eslint/parser for .ts parsing produced 0 findings. Worth fixing the strict-config rule list in a follow-up so future runs use the explicit error-graded set.

No blockers. No --request-changes.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Pushed d481fc1 addressing review feedback:

  • Replaced fake pauseTracking/resetTracking shims with real imports from @vue/reactivity (they are publicly exported, prior comment was wrong).
  • Narrowed PositionData.pos / DimensionsData.size to [number, number] tuples and switched defaults accordingly.
  • DEV console.warn for not-yet-wired widget/node events (optionChange, propertyChange, beforeSerialize, beforeQueue, lifecycle).
  • Marked startExtensionSystem() @internal and removed it from the public barrel src/extension-api/index.ts — it's a boot fn, not part of the author API.
  • Removed dead byGroup accumulator in build-docs.ts; switched docgen from npx typedoc to pnpm exec typedoc.

Connor Byrne and others added 4 commits May 10, 2026 20:49
…(PKG3/4/5)

- packages/extension-api/: @comfyorg/extension-api npm package wrapper
  (src/, package.json, README.md, tsconfig{,.build,.docs}.json,
  typedoc.json, scripts/build-docs.ts, .npmignore, .gitignore)
- .github/workflows/extension-api-typecheck.yml (PKG4.D3)
- .github/workflows/extension-api-publish.yml (PKG4.D4)
- scripts/generate-docs.sh (PKG5.D6)
- pnpm-lock.yaml: workspace dependency for new package

Sidecar: independent of i-foundation; stacks directly on PR #2.
- Replace fake pauseTracking/resetTracking shims with real imports from
  @vue/reactivity (they are publicly exported, prior comment was wrong).
- Narrow PositionData.pos / DimensionsData.size to [number, number] tuples
  and switch defaults to tuple shape [0, 0].
- Add DEV-mode console.warn for not-yet-wired widget/node events
  (optionChange, propertyChange, beforeSerialize, beforeQueue, lifecycle).
- Mark startExtensionSystem() as @internal and remove it from the public
  barrel src/extension-api/index.ts (it's an internal boot fn).
- Drop v2 imports (noteNode/rerouteNode/slotDefaults) from core/index.ts.
- Remove dead byGroup accumulator in build-docs.ts; use pnpm exec typedoc
  instead of npx typedoc.
@vue/reactivity is not a declared dependency in this workspace and
neither 'vue' nor '@vue/reactivity' re-exports pauseTracking/resetTracking
from their public runtime entry — they are genuine Vue internals.

Restore the original no-op shims; reactive-tracking control during
setup hooks will be added in Phase B if profiling shows it matters.
…ole.warns

Mirrors the disable comments added on i-foundation; covers all the
DEV-mode warns introduced for not-yet-wired widget/node events
(optionChange/propertyChange/beforeSerialize/beforeQueue/lifecycle).
@christian-byrne

Copy link
Copy Markdown
Contributor Author

Review triage rollup — i-pkg

Triage of the 6 reviews on this PR. Addressed items cite the commit SHA on this branch (rebased onto the foundation typecheck-fix wave). Needs-fix = real follow-up work. Wontfix = considered and deliberately not done with rationale. Out-of-scope = belongs in a separate PR.

Architect (PRR_kwDOMIrOxs791Z1Y)

# Sev Finding Status
1 HIGH Point/Size tuple vs object fallback Addressed — c5865d3 + 58d6d2a narrow PositionData.pos/DimensionsData.size to [number, number] and switch fallback to [0, 0]
2 HIGH pauseTracking/resetTracking no-op shims Wontfix — c5865d3 swapped to real @vue/reactivity imports, then d4b04ba reverted: @vue/reactivity is not a declared workspace dep and neither vue nor @vue/reactivity re-export those from public runtime entry. Restored no-op shims; revisit in Phase B if profiling justifies adding the dep
3 HIGH NodeEntityId number vs string brand split Addressed — e010c47 unifies on the world-layer string & brand (canonical Phase A ID format node:<graphUuid>:<localId>); also tightens World.getComponent/setComponent/entitiesWith generics
4 MED startExtensionSystem leaked through public barrel Addressed — c5865d3 marks @internal and removes from src/extension-api/index.ts
5 MED Dead extensionV2Service.ts (413 LOC) Addressed — e7f6427 deletes the file
6 MED Widget name via lastIndexOf(':') string parse + as unknown as string cast Needs-fix — still present; depends on a real WidgetNameComponent (#11939). Tracked as Phase B follow-up
7 MED Silent stub events drop handlers Addressed — 58d6d2a adds DEV console.warn for unknown event names; c5865d3 adds DEV warns for optionChange/propertyChange/beforeSerialize/beforeQueue + node lifecycle stubs; fa5f3cf adds the eslint-disable no-console markers
8 LOW lifecycle.ts re-exports impls from service (split ownership) Out-of-scope — refactor; needs a follow-up issue. Surface is stable, no behavior bug
9 LOW Drift between packages/extension-api/src/index.ts and src/extension-api/index.ts Needs-fix — overlaps with Minimalist #1 (see below)

Minimalist (PRR_kwDOMIrOxs791id3)

# Sev Finding Status
1 HIGH Two divergent barrels (packages/extension-api/src/index.ts vs src/extension-api/index.ts) Needs-fix — package barrel still hand-written and missing surface entries (startExtensionSystem was removed from public surface in c5865d3 per Architect #4, which closes part of the gap; remaining drift items still real). Should collapse to a one-line re-export of @/extension-api/index.ts
2 MED Dead byGroup accumulator in build-docs.ts Addressed — c5865d3 removes it
3 MED PAGE_META (~190 LOC) shadows TSDoc Out-of-scope — design call; keeping for now (TypeDoc plugin-markdown title/description coverage isn't yet a 1:1 substitute). Will revisit when first rename causes drift
4 LOW build-docs.ts --watch mode (20 LOC) Wontfix — leaving in; cost is low, removal is a churn PR
5 LOW scripts/generate-docs.sh wrapper (28 LOC) Wontfix — same rationale; the script is the documented entry point in CI
6 LOW typecheck workflow if [ -d test/smoke ] guards a missing fixture Needs-fix — minor; either land the 5-line fixture or drop the step
7 LOW metaFor strips digits, slug keeps them Needs-fix — only matters once a stem with digits ships (e.g. widgetV2); cheap to fix
8 NOTE PR description vs 287-file diff Addressed — base is now ext-api/i-foundation, so the diff for this PR is the package + docgen + CI + the c5865d3/58d6d2a/e7f6427 fixups, not the foundation surface

Skeptic (PRR_kwDOMIrOxs791ocb)

# Sev Finding Status
1 HIGH getPosition/getSize shape mismatch Addressed — same fix as Architect #1 (c5865d3 + 58d6d2a)
2 HIGH pauseTracking/resetTracking no-op stubs Wontfix — same as Architect #2 (d4b04ba revert with rationale)
3 HIGH dispatch() stub returns undefined, as WidgetEntityId cast → createWidgetHandle(undefined) Needs-fix — open. Recommended remedy: throw an explicit "not yet wired" error from addWidget() until ECS lands
4 MED Widget name string-parsed Needs-fix — duplicate of Architect #6
5 MED Silent no-op for unknown events Addressed — 58d6d2a adds DEV warn
6 MED NodeEntityId brand mismatch Addressed — e010c47 (duplicate of Architect #3)
7 LOW Pre-existing entities not mounted by startExtensionSystem() watch Needs-fix — small additive change (initial sweep before the watch)
8 LOW build-docs.ts uses npx Addressed — c5865d3 switches to pnpm exec typedoc

Regression-risk (PRR_kwDOMIrOxs796euD)

Clean ✅ — no findings. Diff is overwhelmingly additive; modified-file blame review found no bugfix-line mutations.

Import-graph (PRR_kwDOMIrOxs796gUU)

# Sev Finding Status
1 blocker import './noteNode.v2' missing Addressed — 58d6d2a drops the import
2 blocker import './rerouteNode.v2' missing Addressed — 58d6d2a drops the import
3 blocker import './slotDefaults.v2' missing Addressed — 58d6d2a + c5865d3 drop the import
4 rec Orphan extensionV2Service.ts Addressed — e7f6427 deletes
5 rec Orphan src/types/extensionV2.ts (only consumer was the orphan service) Needs-fix — file still present (ls confirms 573 bytes, untouched). Trivial follow-up: delete
6 nit extension-api/{events,node,shell,widget}.ts orphan in src/ Wontfix — exempt per AGENTS.md (re-exported from npm package barrel)

SonarJS-lint (PRR_kwDOMIrOxs796_mT)

Clean ✅ — 0 findings on packages/extension-api/src/index.ts. Reviewer caveat about .agents/checks/eslint.strict.config.js referencing renamed/removed v4 rules (no-one-iteration-loop, no-redundant-jump, no-gratuitous-expressions) is a real follow-up — out-of-scope for this PR, file separate issue against .agents/checks/.


Remaining needs-fix (open after this triage)

# From Item Effort
A Architect #6 / Skeptic #4 Replace widget-name lastIndexOf(':') parse with a real WidgetNameComponent (or use WidgetComponentSchema.name) M, blocked on #11939 → Phase B
B Architect #9 / Minimalist #1 Collapse packages/extension-api/src/index.ts to a one-line re-export of @/extension-api/index.ts (or add a tsc/knip drift check) S
C Skeptic #3 addWidget() throws explicit "not yet wired" error when stubbed dispatch returns undefined (instead of building a WidgetHandle over undefined) S
D Skeptic #7 startExtensionSystem() mounts pre-existing NodeType entities before installing the watch S
E Minimalist #6 Land the test/smoke/ fixture or drop the guarded workflow step XS
F Minimalist #7 Reuse slug (or its letters-only variant) inside metaFor so digit-bearing stems don't fall through XS
G Import-graph #5 Delete src/types/extensionV2.ts (orphan, only consumer was deleted in e7f6427) XS

Items B–G are local to this PR. Item A is genuine Phase B work and tracked.

@codecov

codecov Bot commented May 11, 2026

Copy link
Copy Markdown

Codecov Report

❌ Patch coverage is 0% with 10 lines in your changes missing coverage. Please review.

Files with missing lines Patch % Lines
src/services/extension-api-service.ts 0.00% 10 Missing ⚠️
@@                   Coverage Diff                    @@
##           ext-api/i-foundation   #12103      +/-   ##
========================================================
- Coverage                 58.71%   58.71%   -0.01%     
========================================================
  Files                      1411     1411              
  Lines                     71928    71940      +12     
  Branches                  19000    19005       +5     
========================================================
+ Hits                      42236    42240       +4     
- Misses                    29215    29223       +8     
  Partials                    477      477              
Flag Coverage Δ
unit 58.71% <0.00%> (-0.01%) ⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines Coverage Δ
src/services/extension-api-service.ts 31.25% <0.00%> (-0.95%) ⬇️

... and 1 file with indirect coverage changes

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
  • 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

@christian-byrne

Copy link
Copy Markdown
Contributor Author

Closing in favor of #12143 (restratified — properly-scoped pkg only).

The original 4-PR stack (#12102/#12103/#12104/#12105) had absorbed downstream work into the foundation PR (test framework + npm package + core ext conversions all landed in #12102). The new stack (#12142/#12143/#12145/#12144) has clean per-branch boundaries.

See #12142 description for the new stack overview. Original branch tips backed up at backup/restratify/ext-api-i-pkg tag on christian-byrne fork.

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