obix-compiler-sfc

Previous name: @obinexusltd/obix-compiler-sfc — OBIX packages are named without an npm scope since decision D-102 (2026-09-29); the package, its version and its exports are unchanged.

The canonical SFC boundary of the .obix VueTS compiler.

npm install obix-compiler-sfc

Counter.obix ──► parseObix (official Vue SFC parser) ──► toObixSfc ──► ObixSfc   canonical, Vue-independent, frozen
Counter.vue  ──► parseVueReference ───────────────────► toObixSfc ──► ObixSfc
                                                    sfcDifferences(vue, obix) = []     ← the Phase 1 gate

import { parseObix } from "obix-compiler-parser";
import { toObixSfc, sfcDifferences } from "obix-compiler-sfc";

const sfc = toObixSfc(parseObix(source, "Counter.obix"));
sfc.scriptSetup?.lang;   // "ts"
sfc.styles[0]?.scoped;   // true
sfc.template?.loc;       // { start: { line, column, offset }, end: { … } }

sfcDifferences(toObixSfc(parseVueReference(source, "Counter.vue")), sfc); // [] — equivalent up to the filename

| Export | Role | |---|---| | toObixSfc(parseResult) | the canonical ObixSfc of a parseObix / parseVueReference result; throws TypeError for anything else | | sfcDifferences(a, b) | every place two canonical SFCs differ — { path, a, b }, deterministic order — or [] when they are equivalent up to their filename | | types | ObixSfc, SfcTemplateBlock, SfcScriptBlock, SfcStyleBlock, SfcCustomBlock, SfcAttributes, SfcDifference — the position and range types (SourcePosition, SourceRange) are the diagnostic contract's, from obix-compiler-diagnostics |

What is canonical

template, script, scriptSetup, styles[], customBlocks[], each with its content, every attribute (attrs), lang, src and its source location; scoped and module on a style; setup on a script; cssVars and slotted; the whole source; and the parse diagnostics. Locations are the official parser's: 1-based line and column, 0-based offset; a block's loc spans its content.

The value is plain, deep-frozen data that shares no object with the official descriptor and survives a JSON round trip unchanged. It carries no Vue type, no Vue template AST (descriptor.template.ast is not OBIX semantics), no source-map object and no script-analysis field. It is a frontend boundary: the semantic authority of OBIX is the canonical DOP IR (D-44), which later phases lower into.

Equivalence is the filename and nothing else

sfcDifferences normalizes exactly two things: the top-level filename, and — inside a diagnostic — that diagnostic's own filename, as the field and where the official parser quotes it in a message. Nothing else is absorbed: not a directive, a binding, a slot, a style flag, a location, a diagnostic, and not the deliberate from "vue" / from "obix" import difference. That mapping is a documented rule of the equivalence phase; until then it is reported, as a difference of the script content. The tests pin all of this, mutation by mutation.

Dependency role

Depends on obix-compiler-parser (for the parse result it consumes) and on obix-compiler-diagnostics (for ObixCompilerDiagnostic, SourcePosition and SourceRange) — for types only: no runtime import, the built package imports nothing. Consumed by the later phases of the compiler. A compile-time package; graph rule R5 keeps it out of every browser graph.

Tests

npm test -w obix-compiler-sfc — the corpus tests/corpus/vuets (OBIX monorepo record) (31 byte-identical .vue / .obix pairs, 23 valid and 8 invalid); the expected canonical value of every fixture is rebuilt from the official parser by independent test code, and source locations are re-derived from the offsets.

Installation

npm install obix-compiler-sfc

API surface

• obix-compiler-sfc — 2 value exports: sfcDifferences, toObixSfc
• Type declarations: ./dist/index.d.ts (and a declaration next to every JS entry point).

Architecture role

obix-compiler-sfc is part of the OBIX compiler (build-time tooling): it never runs in an application's browser graph.

The architecture of OBIX — the package families and which packages are public API — is indexed in the umbrella: docs/architecture.md.

Package relationships

• Depends on (OBIX): obix-compiler-diagnostics, obix-compiler-parser.
• Used by (OBIX): obix-compiler-dop, obix-compiler-script, obix-compiler-script-setup, obix-compiler-template.

Testing

• 1 test file ships in the npm package (test/): the evidence of the package's contract, published so that its verification can be inspected — not runtime code (no entry point reaches it).
• Standalone: none.
• Need the OBIX development / test harness: 1 — it reads the OBIX monorepo's shared harness, oracles or fixtures, so it does not run from an npm install or from this package's repository alone; it is shipped for inspection and provenance:
  • test/sfc.test.mjs — its code climbs three directories up, out of the package
• Run them with npm test (node --test "test/*.test.mjs") in the OBIX monorepo, which provides the test tooling (Node's test runner, TypeScript) and the harness.

Documentation

• CHANGELOG.md
• The OBIX architecture index: obix/docs/architecture.md

Repository

• https://github.com/obinexus/obix-compiler-sfc — [email protected]:obinexus/obix-compiler-sfc.git
• Issues: https://github.com/obinexus/obix-compiler-sfc/issues
• The repository is a clean export of the package from the OBIX monorepo. Its lineage — the sources it was recovered from and its earlier names — is PROVENANCE.json, shipped in this package; the repository's copy also records the monorepo commit it was exported from.

License

MIT — see LICENSE.