refactor: extract @hyperframes/lint from core

[miguel-heygen]

Summary

Extracts the project-level linter — lintProject, the rule engine, and shouldBlockRender — out of @hyperframes/core/src/lint/ into a new @hyperframes/lint package.

This is the payoff PR for #1749: a Node app (e.g. an agent harness) can now import { lintProject } from "@hyperframes/lint" and lint a composition directory directly, instead of spawning npx hyperframes lint and parsing stdout.

Part 2 of 3 — stacks on #1755 (@hyperframes/parsers). Merge A first.

What moves

New package source	~4,800 LOC
Tests carried over	257 passing
Files in new package	29

The entire linter moves to @hyperframes/lint — the rule engine (hyperframeLinter, all 9 rules/*, context, types, utils) and the project-orchestration layer (lintProject, directory walking, the render-gate decision). It's the single source of truth: core's compiler render-gate (staticGuard.ts) and the studio preview both consume the rule engine from @hyperframes/lint, so there's no second copy that can drift.

Earlier revisions of this PR left a byte-identical copy of the rule engine behind in packages/core/src/lint/ (used by staticGuard) alongside the new one in @hyperframes/lint (used by the studio preview) — two paths into "the linter" that would silently diverge on the first one-sided rule fix. That dual copy has been removed; staticGuard now imports from @hyperframes/lint directly. (Thanks to the reviewer for catching this.)

API change worth calling out

lintProject now takes a directory string instead of a resolved project object:

- lintProject({ dir, name, indexPath })   // old: CLI-shaped object
+ lintProject(dir)                          // new: just a path

That's deliberate — it drops the CLI's Project type from the public surface so the function is callable from any Node context with nothing but a path. All in-repo callers (lint, preview, publish, render commands) and tests are updated.

Bundle footprint

Artifact	Size
dist/ (unpacked)	448 KB
npm tarball (packed)	104 KB (4 files)

How @hyperframes/core changes

packages/core/src/lint/index.ts becomes a one-line @deprecated re-export stub:

/** @deprecated Import from @hyperframes/lint */
export * from "@hyperframes/lint";

So existing @hyperframes/core/lint imports keep working, but new code points at the dedicated package. @hyperframes/lint depends on @hyperframes/core + @hyperframes/parsers + postcss.

Note: lintHyperframeHtml is no longer re-exported from core's main entry (@hyperframes/core) — only from the @hyperframes/core/lint subpath stub and from @hyperframes/lint. Re-exporting it from the main entry would cycle core's index through the lint package (which imports core utilities back); keeping it behind the subpath stub matches how every other extracted package is surfaced.

Test plan

• bun run --filter @hyperframes/lint test — 257 tests pass
• bun run --cwd packages/cli test — 1045 tests pass (callers updated for the new signature)
• bun run build — full monorepo build succeeds
• Fallow audit passes on CI

[miguel-heygen]

• refactor: extract @hyperframes/lint from core #1756 👈 (View in Graphite)
• refactor: extract @hyperframes/parsers from core #1755 : 1 other dependent PR (#1757 )
• main

This stack of pull requests is managed by Graphite. Learn more about stacking.

[terencecho]

Pass on the API change is clean. One substantive finding worth resolving before merge — the PR description doesn't quite match the diff, and the divergence it conceals is a real footgun.

The thing. Description says "HTML-level primitives stay in core (they're shared with the compiler); what moves out is the project orchestration layer." True for lintProject and friends, but the entire rule engine — packages/core/src/lint/hyperframeLinter.ts, rules/{adapters,captions,core,gsap,media,textures,composition,fonts,slideshow}.ts, plus every *.test.ts — is still present in core and now also exists in packages/lint/src/ as a byte-near-identical copy (only diff is import-path rewrites in composition.ts / fonts.ts / slideshow.ts to consume @hyperframes/parsers / @hyperframes/core/fonts/aliases / @hyperframes/core/slideshow).

That gives the runtime two paths into "the linter":

• core's compiler at packages/core/src/compiler/staticGuard.ts:1 does import { lintHyperframeHtml } from "../lint/hyperframeLinter" — the local copy.
• studio's preview at packages/studio/vite.adapter.ts:193 does server.ssrLoadModule("@hyperframes/core/lint") → @hyperframes/core/src/lint/index.ts stub → @hyperframes/lint — the other copy.

ALL_RULES at packages/lint/src/hyperframeLinter.ts:14-24 is the same 9-array spread as core's at packages/core/src/lint/hyperframeLinter.ts:14-24. Byte-identical today, which is exactly when this risk is invisible — the first rule fix that lands in only one diverges the studio preview from the render-time render-gate guard.

Two reasonable resolutions:

1. Pick a direction: re-point staticGuard.ts at @hyperframes/lint, delete packages/core/src/lint/{rules,hyperframeLinter,context,types,utils}.ts (and their tests, which are also duplicated). The deprecated stub at packages/core/src/lint/index.ts already routes everything else through.
2. Document the dual-copy contract explicitly in both hyperframeLinter.ts files and staticGuard.ts so a future maintainer is forced to update both copies in lockstep.

(1) is cleaner; (2) is fast.

Everything else verified clean

• Signature break — fully migrated. lintProject(projectDir: string) at packages/lint/src/project.ts:168. All 4 in-CLI callers updated: commands/lint.ts:41 (project.dir), commands/preview.ts:129 (dir), commands/publish.ts:38 (dir), commands/render.ts:741 (project.dir). studioServer.ts doesn't call lintProject. Tests in packages/cli/src/utils/lintProject.test.ts updated. No stray { dir, name, indexPath } shape on this branch.
• Behavioral parity. Old lintProject consumed project.indexPath + project.dir; project.name was always caller-only. New project.ts:169 derives indexPath via resolve(projectDir, "index.html"). Same outcome.
• External-consumer surface. Only two @hyperframes/core/lint subpath consumers in the repo (cli/src/utils/lintFormat.test.ts:2, studio/vite.adapter.ts:193); both resolve cleanly through the stub. No @hyperframes/core/lint/rules / /shouldBlockRender subpath exports in core/package.json — so no other subpath imports could've existed.
• Stack-base: gh pr diff 1756 touches 51 files, zero in packages/parsers/ — no #1755 bleed.
• Rule registration: ALL_RULES spreads all 9 rule arrays identically in both copies — no rule silently dropped during the move.

Not approving yet purely on the dual-engine point — happy to flip to approve once that's either resolved or explicitly documented.

— Review by tai (pr-review)

[miguel-heygen]

Thanks for the dual-engine catch — that was a real footgun. Went with resolution (1): deleted core's copy of the rule engine (packages/core/src/lint/{rules/*,hyperframeLinter,context,types,utils}.ts + their tests) and re-pointed compiler/staticGuard.ts at @hyperframes/lint. The render-gate and the studio preview now share one rule engine; the @hyperframes/core/lint stub keeps back-compat.

One follow-on: re-exporting lintHyperframeHtml from core's main entry would cycle core's index through the lint package (lint imports core utils back — fallow flagged it), so it's now surfaced only via the @hyperframes/core/lint subpath stub and @hyperframes/lint — consistent with how the other extracted packages are exposed. Updated the stale main-entry export test accordingly, and fixed the description wording you flagged.

refactor(core): single-source the lint engine — 8,627 LOC of duplication removed. Green locally: core 1114, lint 257, cli 1045, fallow audit passes.

[terencecho]

Verified the dual-engine point is resolved at f86aa6b:

• packages/core/src/compiler/staticGuard.ts:1 now imports lintHyperframeHtml from @hyperframes/lint directly — the local re-import is gone.
• packages/core/src/lint/ is empty except for the 84-byte @deprecated re-export stub at index.ts. All the duplicated rule files (hyperframeLinter.ts, rules/*.ts, context.ts, types.ts, utils.ts, plus tests) are gone from core.
• Bonus rewire on packages/producer/src/services/hyperframeLint.ts:3 — that consumer also picks up from @hyperframes/lint directly rather than going through the stub. Nice.

Single source of truth for the rule engine, with the stub catching any straggler @hyperframes/core/lint imports through the deprecation window. No way for the studio preview and render-gate to diverge.

UNSTABLE merge state is just the regression shards + perf shards + Graphite mergeability check still spinning — none gating on this change shape.

— Review by tai (pr-review)

The base branch was changed.