acture-build-tier 1.1.0

package/dist/index.cjs

@@ -0,0 +1,141 @@
+'use strict';
+
+// src/transform.ts
+var TIER_PRECEDENCE = /* @__PURE__ */ new Map([
+  ["stable", 0],
+  ["experimental", 1],
+  ["deprecated", 2],
+  ["internal", 3]
+]);
+function parseTierDirective(jsdocBody) {
+  let chosen;
+  const stripped = jsdocBody.replace(/^\s*\*\s?/gm, "");
+  const stableRe = /@stable\b/;
+  const experimentalRe = /@experimental\b/;
+  const internalRe = /@internal\b/;
+  const deprecatedRe = /@deprecated\b[ \t]*([^\n@]*)/;
+  if (stableRe.test(stripped)) chosen = take(chosen, { tier: "stable" });
+  if (experimentalRe.test(stripped)) chosen = take(chosen, { tier: "experimental" });
+  const depMatch = deprecatedRe.exec(stripped);
+  if (depMatch) {
+    const reason = (depMatch[1] ?? "").trim();
+    chosen = take(chosen, reason.length > 0 ? { tier: "deprecated", reason } : { tier: "deprecated" });
+  }
+  if (internalRe.test(stripped)) chosen = take(chosen, { tier: "internal" });
+  return chosen;
+}
+function take(current, candidate) {
+  if (!current) return candidate;
+  const cur = TIER_PRECEDENCE.get(current.tier) ?? 0;
+  const cand = TIER_PRECEDENCE.get(candidate.tier) ?? 0;
+  return cand > cur ? candidate : current;
+}
+function transformSource(source) {
+  if (!source.includes("defineCommand")) {
+    return { code: source, changed: false, applied: [] };
+  }
+  const applied = [];
+  const out = [];
+  let i = 0;
+  const len = source.length;
+  let internalCount = 0;
+  while (i < len) {
+    const jsdocStart = source.indexOf("/**", i);
+    if (jsdocStart < 0) {
+      out.push(source.slice(i));
+      break;
+    }
+    out.push(source.slice(i, jsdocStart));
+    const jsdocEnd = source.indexOf("*/", jsdocStart + 3);
+    if (jsdocEnd < 0) {
+      out.push(source.slice(jsdocStart));
+      break;
+    }
+    const jsdocBlock = source.slice(jsdocStart, jsdocEnd + 2);
+    out.push(jsdocBlock);
+    const afterDocStart = jsdocEnd + 2;
+    const lookahead = source.slice(afterDocStart, afterDocStart + 600);
+    const dcRe = /^\s*(?:(?:export\s+)?(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*)?defineCommand\s*\(\s*\{/;
+    const m = dcRe.exec(lookahead);
+    if (!m) {
+      i = afterDocStart;
+      continue;
+    }
+    const tier = parseTierDirective(jsdocBlock.slice(3, -2));
+    if (!tier) {
+      i = afterDocStart;
+      continue;
+    }
+    const openBraceAbs = afterDocStart + m[0].length;
+    const restOfFile = source.slice(openBraceAbs, openBraceAbs + 4e3);
+    if (/\btier\s*:/.test(restOfFile.slice(0, indexOfMatchingBrace(restOfFile)))) {
+      i = afterDocStart;
+      continue;
+    }
+    out.push(source.slice(afterDocStart, openBraceAbs));
+    const injected = [];
+    injected.push(` tier: ${JSON.stringify(tier.tier)},`);
+    if (tier.tier === "deprecated" && tier.reason !== void 0) {
+      injected.push(` deprecationReason: ${JSON.stringify(tier.reason)},`);
+    }
+    if (tier.tier === "internal") {
+      injected.push(` internalToken: __actureInternalToken__,`);
+      internalCount++;
+    }
+    out.push(injected.join(""));
+    applied.push(tier.reason !== void 0 ? { tier: tier.tier, reason: tier.reason } : { tier: tier.tier });
+    i = openBraceAbs;
+  }
+  let code = out.join("");
+  if (internalCount > 0) {
+    code = INTERNAL_TOKEN_DECL + code;
+  }
+  return { code, changed: applied.length > 0, applied };
+}
+var INTERNAL_TOKEN_DECL = "const __actureInternalToken__ = /* @__PURE__ */ Symbol('acture.internal');\n";
+function indexOfMatchingBrace(text) {
+  let depth = 1;
+  let i = 0;
+  const len = text.length;
+  while (i < len) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < len) {
+        if (text[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (text[i] === quote) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < len && text[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < len && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return len;
+}
+
+exports.parseTierDirective = parseTierDirective;
+exports.transformSource = transformSource;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transform.ts"],"names":[],"mappings":";;;AAkCA,IAAM,eAAA,uBAAiD,GAAA,CAAI;AAAA,EACzD,CAAC,UAAU,CAAC,CAAA;AAAA,EACZ,CAAC,gBAAgB,CAAC,CAAA;AAAA,EAClB,CAAC,cAAc,CAAC,CAAA;AAAA,EAChB,CAAC,YAAY,CAAC;AAChB,CAAC,CAAA;AAMM,SAAS,mBAAmB,SAAA,EAA8C;AAC/E,EAAA,IAAI,MAAA;AAGJ,EAAA,MAAM,QAAA,GAAW,SAAA,CAAU,OAAA,CAAQ,aAAA,EAAe,EAAE,CAAA;AAEpD,EAAA,MAAM,QAAA,GAAW,WAAA;AACjB,EAAA,MAAM,cAAA,GAAiB,iBAAA;AACvB,EAAA,MAAM,UAAA,GAAa,aAAA;AAEnB,EAAA,MAAM,YAAA,GAAe,8BAAA;AAErB,EAAA,IAAI,QAAA,CAAS,IAAA,CAAK,QAAQ,CAAA,EAAG,MAAA,GAAS,KAAK,MAAA,EAAQ,EAAE,IAAA,EAAM,QAAA,EAAU,CAAA;AACrE,EAAA,IAAI,cAAA,CAAe,IAAA,CAAK,QAAQ,CAAA,EAAG,MAAA,GAAS,KAAK,MAAA,EAAQ,EAAE,IAAA,EAAM,cAAA,EAAgB,CAAA;AACjF,EAAA,MAAM,QAAA,GAAW,YAAA,CAAa,IAAA,CAAK,QAAQ,CAAA;AAC3C,EAAA,IAAI,QAAA,EAAU;AACZ,IAAA,MAAM,MAAA,GAAA,CAAU,QAAA,CAAS,CAAC,CAAA,IAAK,IAAI,IAAA,EAAK;AACxC,IAAA,MAAA,GAAS,IAAA,CAAK,MAAA,EAAQ,MAAA,CAAO,MAAA,GAAS,CAAA,GAAI,EAAE,IAAA,EAAM,YAAA,EAAc,MAAA,EAAO,GAAI,EAAE,IAAA,EAAM,cAAc,CAAA;AAAA,EACnG;AACA,EAAA,IAAI,UAAA,CAAW,IAAA,CAAK,QAAQ,CAAA,EAAG,MAAA,GAAS,KAAK,MAAA,EAAQ,EAAE,IAAA,EAAM,UAAA,EAAY,CAAA;AAEzE,EAAA,OAAO,MAAA;AACT;AAEA,SAAS,IAAA,CACP,SACA,SAAA,EACe;AACf,EAAA,IAAI,CAAC,SAAS,OAAO,SAAA;AACrB,EAAA,MAAM,GAAA,GAAM,eAAA,CAAgB,GAAA,CAAI,OAAA,CAAQ,IAAI,CAAA,IAAK,CAAA;AACjD,EAAA,MAAM,IAAA,GAAO,eAAA,CAAgB,GAAA,CAAI,SAAA,CAAU,IAAI,CAAA,IAAK,CAAA;AACpD,EAAA,OAAO,IAAA,GAAO,MAAM,SAAA,GAAY,OAAA;AAClC;AAuBO,SAAS,gBAAgB,MAAA,EAAiC;AAE/D,EAAA,IAAI,CAAC,MAAA,CAAO,QAAA,CAAS,eAAe,CAAA,EAAG;AACrC,IAAA,OAAO,EAAE,IAAA,EAAM,MAAA,EAAQ,SAAS,KAAA,EAAO,OAAA,EAAS,EAAC,EAAE;AAAA,EACrD;AAEA,EAAA,MAAM,UAAkD,EAAC;AAGzD,EAAA,MAAM,MAAgB,EAAC;AACvB,EAAA,IAAI,CAAA,GAAI,CAAA;AACR,EAAA,MAAM,MAAM,MAAA,CAAO,MAAA;AACnB,EAAA,IAAI,aAAA,GAAgB,CAAA;AAEpB,EAAA,OAAO,IAAI,GAAA,EAAK;AACd,IAAA,MAAM,UAAA,GAAa,MAAA,CAAO,OAAA,CAAQ,KAAA,EAAO,CAAC,CAAA;AAC1C,IAAA,IAAI,aAAa,CAAA,EAAG;AAClB,MAAA,GAAA,CAAI,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,CAAC,CAAC,CAAA;AACxB,MAAA;AAAA,IACF;AACA,IAAA,GAAA,CAAI,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,CAAA,EAAG,UAAU,CAAC,CAAA;AACpC,IAAA,MAAM,QAAA,GAAW,MAAA,CAAO,OAAA,CAAQ,IAAA,EAAM,aAAa,CAAC,CAAA;AACpD,IAAA,IAAI,WAAW,CAAA,EAAG;AAChB,MAAA,GAAA,CAAI,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,UAAU,CAAC,CAAA;AACjC,MAAA;AAAA,IACF;AACA,IAAA,MAAM,UAAA,GAAa,MAAA,CAAO,KAAA,CAAM,UAAA,EAAY,WAAW,CAAC,CAAA;AACxD,IAAA,GAAA,CAAI,KAAK,UAAU,CAAA;AAInB,IAAA,MAAM,gBAAgB,QAAA,GAAW,CAAA;AACjC,IAAA,MAAM,SAAA,GAAY,MAAA,CAAO,KAAA,CAAM,aAAA,EAAe,gBAAgB,GAAG,CAAA;AAMjE,IAAA,MAAM,IAAA,GAAO,2FAAA;AACb,IAAA,MAAM,CAAA,GAAI,IAAA,CAAK,IAAA,CAAK,SAAS,CAAA;AAC7B,IAAA,IAAI,CAAC,CAAA,EAAG;AACN,MAAA,CAAA,GAAI,aAAA;AACJ,MAAA;AAAA,IACF;AACA,IAAA,MAAM,OAAO,kBAAA,CAAmB,UAAA,CAAW,KAAA,CAAM,CAAA,EAAG,EAAE,CAAC,CAAA;AACvD,IAAA,IAAI,CAAC,IAAA,EAAM;AACT,MAAA,CAAA,GAAI,aAAA;AACJ,MAAA;AAAA,IACF;AAIA,IAAA,MAAM,YAAA,GAAe,aAAA,GAAgB,CAAA,CAAE,CAAC,CAAA,CAAE,MAAA;AAE1C,IAAA,MAAM,UAAA,GAAa,MAAA,CAAO,KAAA,CAAM,YAAA,EAAc,eAAe,GAAI,CAAA;AACjE,IAAA,IAAI,YAAA,CAAa,KAAK,UAAA,CAAW,KAAA,CAAM,GAAG,oBAAA,CAAqB,UAAU,CAAC,CAAC,CAAA,EAAG;AAC5E,MAAA,CAAA,GAAI,aAAA;AACJ,MAAA;AAAA,IACF;AAGA,IAAA,GAAA,CAAI,IAAA,CAAK,MAAA,CAAO,KAAA,CAAM,aAAA,EAAe,YAAY,CAAC,CAAA;AAGlD,IAAA,MAAM,WAAqB,EAAC;AAC5B,IAAA,QAAA,CAAS,KAAK,CAAA,OAAA,EAAU,IAAA,CAAK,UAAU,IAAA,CAAK,IAAI,CAAC,CAAA,CAAA,CAAG,CAAA;AACpD,IAAA,IAAI,IAAA,CAAK,IAAA,KAAS,YAAA,IAAgB,IAAA,CAAK,WAAW,MAAA,EAAW;AAC3D,MAAA,QAAA,CAAS,KAAK,CAAA,oBAAA,EAAuB,IAAA,CAAK,UAAU,IAAA,CAAK,MAAM,CAAC,CAAA,CAAA,CAAG,CAAA;AAAA,IACrE;AACA,IAAA,IAAI,IAAA,CAAK,SAAS,UAAA,EAAY;AAC5B,MAAA,QAAA,CAAS,KAAK,CAAA,wCAAA,CAA0C,CAAA;AACxD,MAAA,aAAA,EAAA;AAAA,IACF;AACA,IAAA,GAAA,CAAI,IAAA,CAAK,QAAA,CAAS,IAAA,CAAK,EAAE,CAAC,CAAA;AAE1B,IAAA,OAAA,CAAQ,KAAK,IAAA,CAAK,MAAA,KAAW,MAAA,GAAY,EAAE,MAAM,IAAA,CAAK,IAAA,EAAM,MAAA,EAAQ,IAAA,CAAK,QAAO,GAAI,EAAE,IAAA,EAAM,IAAA,CAAK,MAAM,CAAA;AAEvG,IAAA,CAAA,GAAI,YAAA;AAAA,EACN;AAEA,EAAA,IAAI,IAAA,GAAO,GAAA,CAAI,IAAA,CAAK,EAAE,CAAA;AACtB,EAAA,IAAI,gBAAgB,CAAA,EAAG;AACrB,IAAA,IAAA,GAAO,mBAAA,GAAsB,IAAA;AAAA,EAC/B;AACA,EAAA,OAAO,EAAE,IAAA,EAAM,OAAA,EAAS,OAAA,CAAQ,MAAA,GAAS,GAAG,OAAA,EAAQ;AACtD;AAIA,IAAM,mBAAA,GACJ,8EAAA;AAgBF,SAAS,qBAAqB,IAAA,EAAsB;AAClD,EAAA,IAAI,KAAA,GAAQ,CAAA;AACZ,EAAA,IAAI,CAAA,GAAI,CAAA;AACR,EAAA,MAAM,MAAM,IAAA,CAAK,MAAA;AACjB,EAAA,OAAO,IAAI,GAAA,EAAK;AACd,IAAA,MAAM,EAAA,GAAK,KAAK,CAAC,CAAA;AACjB,IAAA,IAAI,EAAA,KAAO,GAAA,IAAO,EAAA,KAAO,GAAA,IAAO,OAAO,GAAA,EAAK;AAC1C,MAAA,MAAM,KAAA,GAAQ,EAAA;AACd,MAAA,CAAA,EAAA;AACA,MAAA,OAAO,IAAI,GAAA,EAAK;AACd,QAAA,IAAI,IAAA,CAAK,CAAC,CAAA,KAAM,IAAA,EAAM;AAAE,UAAA,CAAA,IAAK,CAAA;AAAG,UAAA;AAAA,QAAU;AAC1C,QAAA,IAAI,IAAA,CAAK,CAAC,CAAA,KAAM,KAAA,EAAO;AAAE,UAAA,CAAA,EAAA;AAAK,UAAA;AAAA,QAAO;AACrC,QAAA,CAAA,EAAA;AAAA,MACF;AACA,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAO,GAAA,IAAO,IAAA,CAAK,CAAA,GAAI,CAAC,MAAM,GAAA,EAAK;AAErC,MAAA,OAAO,CAAA,GAAI,GAAA,IAAO,IAAA,CAAK,CAAC,MAAM,IAAA,EAAM,CAAA,EAAA;AACpC,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAO,GAAA,IAAO,IAAA,CAAK,CAAA,GAAI,CAAC,MAAM,GAAA,EAAK;AACrC,MAAA,CAAA,IAAK,CAAA;AACL,MAAA,OAAO,CAAA,GAAI,GAAA,IAAO,EAAE,IAAA,CAAK,CAAC,CAAA,KAAM,GAAA,IAAO,IAAA,CAAK,CAAA,GAAI,CAAC,CAAA,KAAM,GAAA,CAAA,EAAM,CAAA,EAAA;AAC7D,MAAA,CAAA,IAAK,CAAA;AACL,MAAA;AAAA,IACF;AACA,IAAA,IAAI,OAAO,GAAA,EAAK,KAAA,EAAA;AAAA,SAAA,IACP,OAAO,GAAA,EAAK;AACnB,MAAA,KAAA,EAAA;AACA,MAAA,IAAI,KAAA,KAAU,GAAG,OAAO,CAAA;AAAA,IAC1B;AACA,IAAA,CAAA,EAAA;AAAA,EACF;AACA,EAAA,OAAO,GAAA;AACT","file":"index.cjs","sourcesContent":["/**\n * Pure source-transform logic. The esbuild and Vite plugin wrappers\n * import this and call it from their respective transform hooks.\n *\n * Strategy: regex-based, intentionally conservative. We match a JSDoc\n * block immediately preceding a `defineCommand({ ... })` call, parse\n * the tier tag(s) from the JSDoc, and inject the corresponding\n * properties into the spec object literal.\n *\n * Why regex and not AST: the build step has to be fast (it runs on every\n * .ts file), and the patterns we accept are deliberately narrow — JSDoc\n * directly above the call site, no exotic syntax in between. If a user\n * writes `defineCommand` in a way our regex can't see, they fall back to\n * writing `tier: 'experimental'` explicitly in the spec — that path is\n * documented as the manual fallback.\n *\n * The four recognized tags:\n *   @stable\n *   @experimental\n *   @internal\n *   @deprecated [reason text...]\n *\n * Tag precedence: if multiple appear in the same JSDoc, we honour the\n * most-specific-restriction wins: internal > deprecated > experimental > stable.\n */\n\nexport type Tier = 'stable' | 'experimental' | 'internal' | 'deprecated';\n\nexport interface TierDirective {\n  readonly tier: Tier;\n  /** Non-empty only for `@deprecated <reason>`. */\n  readonly reason?: string;\n}\n\nconst TIER_PRECEDENCE: ReadonlyMap<Tier, number> = new Map([\n  ['stable', 0],\n  ['experimental', 1],\n  ['deprecated', 2],\n  ['internal', 3],\n]);\n\n/**\n * Parse a JSDoc block body (the text between `/**` and `* /` ) for tier\n * tags. Returns the most-restrictive tag found, or `undefined` if none.\n */\nexport function parseTierDirective(jsdocBody: string): TierDirective | undefined {\n  let chosen: TierDirective | undefined;\n  // Strip the leading `*` on each line so multi-line JSDoc doesn't break\n  // the tag scanner.\n  const stripped = jsdocBody.replace(/^\\s*\\*\\s?/gm, '');\n\n  const stableRe = /@stable\\b/;\n  const experimentalRe = /@experimental\\b/;\n  const internalRe = /@internal\\b/;\n  // `@deprecated` may carry free-text reason on the same line.\n  const deprecatedRe = /@deprecated\\b[ \\t]*([^\\n@]*)/;\n\n  if (stableRe.test(stripped)) chosen = take(chosen, { tier: 'stable' });\n  if (experimentalRe.test(stripped)) chosen = take(chosen, { tier: 'experimental' });\n  const depMatch = deprecatedRe.exec(stripped);\n  if (depMatch) {\n    const reason = (depMatch[1] ?? '').trim();\n    chosen = take(chosen, reason.length > 0 ? { tier: 'deprecated', reason } : { tier: 'deprecated' });\n  }\n  if (internalRe.test(stripped)) chosen = take(chosen, { tier: 'internal' });\n\n  return chosen;\n}\n\nfunction take(\n  current: TierDirective | undefined,\n  candidate: TierDirective,\n): TierDirective {\n  if (!current) return candidate;\n  const cur = TIER_PRECEDENCE.get(current.tier) ?? 0;\n  const cand = TIER_PRECEDENCE.get(candidate.tier) ?? 0;\n  return cand > cur ? candidate : current;\n}\n\nexport interface TransformResult {\n  readonly code: string;\n  readonly changed: boolean;\n  /** Tier directives applied, in order — exposed for testing. */\n  readonly applied: ReadonlyArray<{ tier: Tier; reason?: string }>;\n}\n\n/**\n * Find every `/** ... * /` JSDoc block immediately followed by a\n * `defineCommand({ ... })` call, parse the tier tag(s), and inject the\n * tier (plus deprecationReason / internalToken when applicable) into\n * the spec object literal.\n *\n * - `tier` is injected at the head of the spec object.\n * - `deprecationReason` is injected after `tier`.\n * - `internalToken` references a module-scoped Symbol that is declared\n *   once at the top of the file (only when at least one `@internal`\n *   command is present in the file).\n *\n * Idempotent: if the spec already contains `tier:`, we leave it alone.\n */\nexport function transformSource(source: string): TransformResult {\n  // Skip files that obviously do not call defineCommand.\n  if (!source.includes('defineCommand')) {\n    return { code: source, changed: false, applied: [] };\n  }\n\n  const applied: Array<{ tier: Tier; reason?: string }> = [];\n  // Find every JSDoc block. We scan in order so insertion offsets remain\n  // valid as we rebuild the source incrementally.\n  const out: string[] = [];\n  let i = 0;\n  const len = source.length;\n  let internalCount = 0;\n\n  while (i < len) {\n    const jsdocStart = source.indexOf('/**', i);\n    if (jsdocStart < 0) {\n      out.push(source.slice(i));\n      break;\n    }\n    out.push(source.slice(i, jsdocStart));\n    const jsdocEnd = source.indexOf('*/', jsdocStart + 3);\n    if (jsdocEnd < 0) {\n      out.push(source.slice(jsdocStart));\n      break;\n    }\n    const jsdocBlock = source.slice(jsdocStart, jsdocEnd + 2);\n    out.push(jsdocBlock);\n\n    // Look ahead for `defineCommand(` after optional whitespace,\n    // an optional `export ...`, an optional `const NAME = ` binding.\n    const afterDocStart = jsdocEnd + 2;\n    const lookahead = source.slice(afterDocStart, afterDocStart + 600);\n    // The pattern captures the slice up to and including the opening\n    // `{` of the spec object literal.\n    // Optional declaration prefix (e.g. `export const NAME = `), then\n    // `defineCommand({`. The declaration is optional so bare-call forms\n    // are recognized too (`defineCommand({...})` on its own line).\n    const dcRe = /^\\s*(?:(?:export\\s+)?(?:const|let|var)\\s+[A-Za-z_$][\\w$]*\\s*=\\s*)?defineCommand\\s*\\(\\s*\\{/;\n    const m = dcRe.exec(lookahead);\n    if (!m) {\n      i = afterDocStart;\n      continue;\n    }\n    const tier = parseTierDirective(jsdocBlock.slice(3, -2));\n    if (!tier) {\n      i = afterDocStart;\n      continue;\n    }\n    // Compute the absolute position right after the opening `{`.\n    // `m.index` is 0 (we anchored with `^`); `m[0].length` is the entire\n    // match, ending at the `{` (inclusive).\n    const openBraceAbs = afterDocStart + m[0].length;\n    // Detect if the spec already declares `tier:` — if so, leave it.\n    const restOfFile = source.slice(openBraceAbs, openBraceAbs + 4000);\n    if (/\\btier\\s*:/.test(restOfFile.slice(0, indexOfMatchingBrace(restOfFile)))) {\n      i = afterDocStart;\n      continue;\n    }\n\n    // Emit everything between end-of-JSDoc and openBraceAbs.\n    out.push(source.slice(afterDocStart, openBraceAbs));\n\n    // Build the injected fields.\n    const injected: string[] = [];\n    injected.push(` tier: ${JSON.stringify(tier.tier)},`);\n    if (tier.tier === 'deprecated' && tier.reason !== undefined) {\n      injected.push(` deprecationReason: ${JSON.stringify(tier.reason)},`);\n    }\n    if (tier.tier === 'internal') {\n      injected.push(` internalToken: __actureInternalToken__,`);\n      internalCount++;\n    }\n    out.push(injected.join(''));\n\n    applied.push(tier.reason !== undefined ? { tier: tier.tier, reason: tier.reason } : { tier: tier.tier });\n\n    i = openBraceAbs;\n  }\n\n  let code = out.join('');\n  if (internalCount > 0) {\n    code = INTERNAL_TOKEN_DECL + code;\n  }\n  return { code, changed: applied.length > 0, applied };\n}\n\n/** Declared at module top so every `@internal` command in the file\n *  shares it. Cross-module callers cannot see it. */\nconst INTERNAL_TOKEN_DECL =\n  \"const __actureInternalToken__ = /* @__PURE__ */ Symbol('acture.internal');\\n\";\n\n/**\n * Find the offset of the matching closing brace for a string that\n * starts immediately after an opening `{` (the `{` is NOT in `text`).\n * Returns the index of the `}` (relative to `text`) on success, or\n * `text.length` if no balanced close is found.\n *\n * The scanner is intentionally minimal — it tracks nested `{}` only.\n * It treats string and template literals as opaque (skips matching\n * braces inside them) to a first approximation: handles single-quoted,\n * double-quoted, and backtick strings; does NOT handle template\n * substitutions perfectly (a `${` inside a backtick may foil it). The\n * defineCommand spec object is shallow enough that this is fine in\n * practice; users with exotic templates can write `tier: 'X'` manually.\n */\nfunction indexOfMatchingBrace(text: string): number {\n  let depth = 1;\n  let i = 0;\n  const len = text.length;\n  while (i < len) {\n    const ch = text[i]!;\n    if (ch === '\"' || ch === \"'\" || ch === '`') {\n      const quote = ch;\n      i++;\n      while (i < len) {\n        if (text[i] === '\\\\') { i += 2; continue; }\n        if (text[i] === quote) { i++; break; }\n        i++;\n      }\n      continue;\n    }\n    if (ch === '/' && text[i + 1] === '/') {\n      // line comment\n      while (i < len && text[i] !== '\\n') i++;\n      continue;\n    }\n    if (ch === '/' && text[i + 1] === '*') {\n      i += 2;\n      while (i < len && !(text[i] === '*' && text[i + 1] === '/')) i++;\n      i += 2;\n      continue;\n    }\n    if (ch === '{') depth++;\n    else if (ch === '}') {\n      depth--;\n      if (depth === 0) return i;\n    }\n    i++;\n  }\n  return len;\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,62 @@
+/**
+ * Pure source-transform logic. The esbuild and Vite plugin wrappers
+ * import this and call it from their respective transform hooks.
+ *
+ * Strategy: regex-based, intentionally conservative. We match a JSDoc
+ * block immediately preceding a `defineCommand({ ... })` call, parse
+ * the tier tag(s) from the JSDoc, and inject the corresponding
+ * properties into the spec object literal.
+ *
+ * Why regex and not AST: the build step has to be fast (it runs on every
+ * .ts file), and the patterns we accept are deliberately narrow — JSDoc
+ * directly above the call site, no exotic syntax in between. If a user
+ * writes `defineCommand` in a way our regex can't see, they fall back to
+ * writing `tier: 'experimental'` explicitly in the spec — that path is
+ * documented as the manual fallback.
+ *
+ * The four recognized tags:
+ *   @stable
+ *   @experimental
+ *   @internal
+ *   @deprecated [reason text...]
+ *
+ * Tag precedence: if multiple appear in the same JSDoc, we honour the
+ * most-specific-restriction wins: internal > deprecated > experimental > stable.
+ */
+type Tier = 'stable' | 'experimental' | 'internal' | 'deprecated';
+interface TierDirective {
+    readonly tier: Tier;
+    /** Non-empty only for `@deprecated <reason>`. */
+    readonly reason?: string;
+}
+/**
+ * Parse a JSDoc block body (the text between `/**` and `* /` ) for tier
+ * tags. Returns the most-restrictive tag found, or `undefined` if none.
+ */
+declare function parseTierDirective(jsdocBody: string): TierDirective | undefined;
+interface TransformResult {
+    readonly code: string;
+    readonly changed: boolean;
+    /** Tier directives applied, in order — exposed for testing. */
+    readonly applied: ReadonlyArray<{
+        tier: Tier;
+        reason?: string;
+    }>;
+}
+/**
+ * Find every `/** ... * /` JSDoc block immediately followed by a
+ * `defineCommand({ ... })` call, parse the tier tag(s), and inject the
+ * tier (plus deprecationReason / internalToken when applicable) into
+ * the spec object literal.
+ *
+ * - `tier` is injected at the head of the spec object.
+ * - `deprecationReason` is injected after `tier`.
+ * - `internalToken` references a module-scoped Symbol that is declared
+ *   once at the top of the file (only when at least one `@internal`
+ *   command is present in the file).
+ *
+ * Idempotent: if the spec already contains `tier:`, we leave it alone.
+ */
+declare function transformSource(source: string): TransformResult;
+
+export { type Tier, type TierDirective, type TransformResult, parseTierDirective, transformSource };

package/dist/index.d.ts

@@ -0,0 +1,62 @@
+/**
+ * Pure source-transform logic. The esbuild and Vite plugin wrappers
+ * import this and call it from their respective transform hooks.
+ *
+ * Strategy: regex-based, intentionally conservative. We match a JSDoc
+ * block immediately preceding a `defineCommand({ ... })` call, parse
+ * the tier tag(s) from the JSDoc, and inject the corresponding
+ * properties into the spec object literal.
+ *
+ * Why regex and not AST: the build step has to be fast (it runs on every
+ * .ts file), and the patterns we accept are deliberately narrow — JSDoc
+ * directly above the call site, no exotic syntax in between. If a user
+ * writes `defineCommand` in a way our regex can't see, they fall back to
+ * writing `tier: 'experimental'` explicitly in the spec — that path is
+ * documented as the manual fallback.
+ *
+ * The four recognized tags:
+ *   @stable
+ *   @experimental
+ *   @internal
+ *   @deprecated [reason text...]
+ *
+ * Tag precedence: if multiple appear in the same JSDoc, we honour the
+ * most-specific-restriction wins: internal > deprecated > experimental > stable.
+ */
+type Tier = 'stable' | 'experimental' | 'internal' | 'deprecated';
+interface TierDirective {
+    readonly tier: Tier;
+    /** Non-empty only for `@deprecated <reason>`. */
+    readonly reason?: string;
+}
+/**
+ * Parse a JSDoc block body (the text between `/**` and `* /` ) for tier
+ * tags. Returns the most-restrictive tag found, or `undefined` if none.
+ */
+declare function parseTierDirective(jsdocBody: string): TierDirective | undefined;
+interface TransformResult {
+    readonly code: string;
+    readonly changed: boolean;
+    /** Tier directives applied, in order — exposed for testing. */
+    readonly applied: ReadonlyArray<{
+        tier: Tier;
+        reason?: string;
+    }>;
+}
+/**
+ * Find every `/** ... * /` JSDoc block immediately followed by a
+ * `defineCommand({ ... })` call, parse the tier tag(s), and inject the
+ * tier (plus deprecationReason / internalToken when applicable) into
+ * the spec object literal.
+ *
+ * - `tier` is injected at the head of the spec object.
+ * - `deprecationReason` is injected after `tier`.
+ * - `internalToken` references a module-scoped Symbol that is declared
+ *   once at the top of the file (only when at least one `@internal`
+ *   command is present in the file).
+ *
+ * Idempotent: if the spec already contains `tier:`, we leave it alone.
+ */
+declare function transformSource(source: string): TransformResult;
+
+export { type Tier, type TierDirective, type TransformResult, parseTierDirective, transformSource };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { parseTierDirective, transformSource } from './chunk-SWJN6WEL.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/vite.cjs

@@ -0,0 +1,157 @@
+'use strict';
+
+// src/transform.ts
+var TIER_PRECEDENCE = /* @__PURE__ */ new Map([
+  ["stable", 0],
+  ["experimental", 1],
+  ["deprecated", 2],
+  ["internal", 3]
+]);
+function parseTierDirective(jsdocBody) {
+  let chosen;
+  const stripped = jsdocBody.replace(/^\s*\*\s?/gm, "");
+  const stableRe = /@stable\b/;
+  const experimentalRe = /@experimental\b/;
+  const internalRe = /@internal\b/;
+  const deprecatedRe = /@deprecated\b[ \t]*([^\n@]*)/;
+  if (stableRe.test(stripped)) chosen = take(chosen, { tier: "stable" });
+  if (experimentalRe.test(stripped)) chosen = take(chosen, { tier: "experimental" });
+  const depMatch = deprecatedRe.exec(stripped);
+  if (depMatch) {
+    const reason = (depMatch[1] ?? "").trim();
+    chosen = take(chosen, reason.length > 0 ? { tier: "deprecated", reason } : { tier: "deprecated" });
+  }
+  if (internalRe.test(stripped)) chosen = take(chosen, { tier: "internal" });
+  return chosen;
+}
+function take(current, candidate) {
+  if (!current) return candidate;
+  const cur = TIER_PRECEDENCE.get(current.tier) ?? 0;
+  const cand = TIER_PRECEDENCE.get(candidate.tier) ?? 0;
+  return cand > cur ? candidate : current;
+}
+function transformSource(source) {
+  if (!source.includes("defineCommand")) {
+    return { code: source, changed: false, applied: [] };
+  }
+  const applied = [];
+  const out = [];
+  let i = 0;
+  const len = source.length;
+  let internalCount = 0;
+  while (i < len) {
+    const jsdocStart = source.indexOf("/**", i);
+    if (jsdocStart < 0) {
+      out.push(source.slice(i));
+      break;
+    }
+    out.push(source.slice(i, jsdocStart));
+    const jsdocEnd = source.indexOf("*/", jsdocStart + 3);
+    if (jsdocEnd < 0) {
+      out.push(source.slice(jsdocStart));
+      break;
+    }
+    const jsdocBlock = source.slice(jsdocStart, jsdocEnd + 2);
+    out.push(jsdocBlock);
+    const afterDocStart = jsdocEnd + 2;
+    const lookahead = source.slice(afterDocStart, afterDocStart + 600);
+    const dcRe = /^\s*(?:(?:export\s+)?(?:const|let|var)\s+[A-Za-z_$][\w$]*\s*=\s*)?defineCommand\s*\(\s*\{/;
+    const m = dcRe.exec(lookahead);
+    if (!m) {
+      i = afterDocStart;
+      continue;
+    }
+    const tier = parseTierDirective(jsdocBlock.slice(3, -2));
+    if (!tier) {
+      i = afterDocStart;
+      continue;
+    }
+    const openBraceAbs = afterDocStart + m[0].length;
+    const restOfFile = source.slice(openBraceAbs, openBraceAbs + 4e3);
+    if (/\btier\s*:/.test(restOfFile.slice(0, indexOfMatchingBrace(restOfFile)))) {
+      i = afterDocStart;
+      continue;
+    }
+    out.push(source.slice(afterDocStart, openBraceAbs));
+    const injected = [];
+    injected.push(` tier: ${JSON.stringify(tier.tier)},`);
+    if (tier.tier === "deprecated" && tier.reason !== void 0) {
+      injected.push(` deprecationReason: ${JSON.stringify(tier.reason)},`);
+    }
+    if (tier.tier === "internal") {
+      injected.push(` internalToken: __actureInternalToken__,`);
+      internalCount++;
+    }
+    out.push(injected.join(""));
+    applied.push(tier.reason !== void 0 ? { tier: tier.tier, reason: tier.reason } : { tier: tier.tier });
+    i = openBraceAbs;
+  }
+  let code = out.join("");
+  if (internalCount > 0) {
+    code = INTERNAL_TOKEN_DECL + code;
+  }
+  return { code, changed: applied.length > 0, applied };
+}
+var INTERNAL_TOKEN_DECL = "const __actureInternalToken__ = /* @__PURE__ */ Symbol('acture.internal');\n";
+function indexOfMatchingBrace(text) {
+  let depth = 1;
+  let i = 0;
+  const len = text.length;
+  while (i < len) {
+    const ch = text[i];
+    if (ch === '"' || ch === "'" || ch === "`") {
+      const quote = ch;
+      i++;
+      while (i < len) {
+        if (text[i] === "\\") {
+          i += 2;
+          continue;
+        }
+        if (text[i] === quote) {
+          i++;
+          break;
+        }
+        i++;
+      }
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "/") {
+      while (i < len && text[i] !== "\n") i++;
+      continue;
+    }
+    if (ch === "/" && text[i + 1] === "*") {
+      i += 2;
+      while (i < len && !(text[i] === "*" && text[i + 1] === "/")) i++;
+      i += 2;
+      continue;
+    }
+    if (ch === "{") depth++;
+    else if (ch === "}") {
+      depth--;
+      if (depth === 0) return i;
+    }
+    i++;
+  }
+  return len;
+}
+
+// src/vite.ts
+function actureBuildTierVite(options = {}) {
+  const filter = options.filter ?? /\.tsx?$/;
+  const exclude = options.exclude ?? /node_modules/;
+  return {
+    name: "acture-build-tier",
+    enforce: "pre",
+    transform(code, id) {
+      if (!filter.test(id)) return void 0;
+      if (exclude.test(id)) return void 0;
+      const result = transformSource(code);
+      if (!result.changed) return void 0;
+      return { code: result.code, map: null };
+    }
+  };
+}
+
+exports.actureBuildTierVite = actureBuildTierVite;
+//# sourceMappingURL=vite.cjs.map
+//# sourceMappingURL=vite.cjs.map

package/dist/vite.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transform.ts","../src/vite.ts"],"names":[],"mappings":"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","file":"vite.cjs","sourcesContent":["/**\n * Pure source-transform logic. The esbuild and Vite plugin wrappers\n * import this and call it from their respective transform hooks.\n *\n * Strategy: regex-based, intentionally conservative. We match a JSDoc\n * block immediately preceding a `defineCommand({ ... })` call, parse\n * the tier tag(s) from the JSDoc, and inject the corresponding\n * properties into the spec object literal.\n *\n * Why regex and not AST: the build step has to be fast (it runs on every\n * .ts file), and the patterns we accept are deliberately narrow — JSDoc\n * directly above the call site, no exotic syntax in between. If a user\n * writes `defineCommand` in a way our regex can't see, they fall back to\n * writing `tier: 'experimental'` explicitly in the spec — that path is\n * documented as the manual fallback.\n *\n * The four recognized tags:\n *   @stable\n *   @experimental\n *   @internal\n *   @deprecated [reason text...]\n *\n * Tag precedence: if multiple appear in the same JSDoc, we honour the\n * most-specific-restriction wins: internal > deprecated > experimental > stable.\n */\n\nexport type Tier = 'stable' | 'experimental' | 'internal' | 'deprecated';\n\nexport interface TierDirective {\n  readonly tier: Tier;\n  /** Non-empty only for `@deprecated <reason>`. */\n  readonly reason?: string;\n}\n\nconst TIER_PRECEDENCE: ReadonlyMap<Tier, number> = new Map([\n  ['stable', 0],\n  ['experimental', 1],\n  ['deprecated', 2],\n  ['internal', 3],\n]);\n\n/**\n * Parse a JSDoc block body (the text between `/**` and `* /` ) for tier\n * tags. Returns the most-restrictive tag found, or `undefined` if none.\n */\nexport function parseTierDirective(jsdocBody: string): TierDirective | undefined {\n  let chosen: TierDirective | undefined;\n  // Strip the leading `*` on each line so multi-line JSDoc doesn't break\n  // the tag scanner.\n  const stripped = jsdocBody.replace(/^\\s*\\*\\s?/gm, '');\n\n  const stableRe = /@stable\\b/;\n  const experimentalRe = /@experimental\\b/;\n  const internalRe = /@internal\\b/;\n  // `@deprecated` may carry free-text reason on the same line.\n  const deprecatedRe = /@deprecated\\b[ \\t]*([^\\n@]*)/;\n\n  if (stableRe.test(stripped)) chosen = take(chosen, { tier: 'stable' });\n  if (experimentalRe.test(stripped)) chosen = take(chosen, { tier: 'experimental' });\n  const depMatch = deprecatedRe.exec(stripped);\n  if (depMatch) {\n    const reason = (depMatch[1] ?? '').trim();\n    chosen = take(chosen, reason.length > 0 ? { tier: 'deprecated', reason } : { tier: 'deprecated' });\n  }\n  if (internalRe.test(stripped)) chosen = take(chosen, { tier: 'internal' });\n\n  return chosen;\n}\n\nfunction take(\n  current: TierDirective | undefined,\n  candidate: TierDirective,\n): TierDirective {\n  if (!current) return candidate;\n  const cur = TIER_PRECEDENCE.get(current.tier) ?? 0;\n  const cand = TIER_PRECEDENCE.get(candidate.tier) ?? 0;\n  return cand > cur ? candidate : current;\n}\n\nexport interface TransformResult {\n  readonly code: string;\n  readonly changed: boolean;\n  /** Tier directives applied, in order — exposed for testing. */\n  readonly applied: ReadonlyArray<{ tier: Tier; reason?: string }>;\n}\n\n/**\n * Find every `/** ... * /` JSDoc block immediately followed by a\n * `defineCommand({ ... })` call, parse the tier tag(s), and inject the\n * tier (plus deprecationReason / internalToken when applicable) into\n * the spec object literal.\n *\n * - `tier` is injected at the head of the spec object.\n * - `deprecationReason` is injected after `tier`.\n * - `internalToken` references a module-scoped Symbol that is declared\n *   once at the top of the file (only when at least one `@internal`\n *   command is present in the file).\n *\n * Idempotent: if the spec already contains `tier:`, we leave it alone.\n */\nexport function transformSource(source: string): TransformResult {\n  // Skip files that obviously do not call defineCommand.\n  if (!source.includes('defineCommand')) {\n    return { code: source, changed: false, applied: [] };\n  }\n\n  const applied: Array<{ tier: Tier; reason?: string }> = [];\n  // Find every JSDoc block. We scan in order so insertion offsets remain\n  // valid as we rebuild the source incrementally.\n  const out: string[] = [];\n  let i = 0;\n  const len = source.length;\n  let internalCount = 0;\n\n  while (i < len) {\n    const jsdocStart = source.indexOf('/**', i);\n    if (jsdocStart < 0) {\n      out.push(source.slice(i));\n      break;\n    }\n    out.push(source.slice(i, jsdocStart));\n    const jsdocEnd = source.indexOf('*/', jsdocStart + 3);\n    if (jsdocEnd < 0) {\n      out.push(source.slice(jsdocStart));\n      break;\n    }\n    const jsdocBlock = source.slice(jsdocStart, jsdocEnd + 2);\n    out.push(jsdocBlock);\n\n    // Look ahead for `defineCommand(` after optional whitespace,\n    // an optional `export ...`, an optional `const NAME = ` binding.\n    const afterDocStart = jsdocEnd + 2;\n    const lookahead = source.slice(afterDocStart, afterDocStart + 600);\n    // The pattern captures the slice up to and including the opening\n    // `{` of the spec object literal.\n    // Optional declaration prefix (e.g. `export const NAME = `), then\n    // `defineCommand({`. The declaration is optional so bare-call forms\n    // are recognized too (`defineCommand({...})` on its own line).\n    const dcRe = /^\\s*(?:(?:export\\s+)?(?:const|let|var)\\s+[A-Za-z_$][\\w$]*\\s*=\\s*)?defineCommand\\s*\\(\\s*\\{/;\n    const m = dcRe.exec(lookahead);\n    if (!m) {\n      i = afterDocStart;\n      continue;\n    }\n    const tier = parseTierDirective(jsdocBlock.slice(3, -2));\n    if (!tier) {\n      i = afterDocStart;\n      continue;\n    }\n    // Compute the absolute position right after the opening `{`.\n    // `m.index` is 0 (we anchored with `^`); `m[0].length` is the entire\n    // match, ending at the `{` (inclusive).\n    const openBraceAbs = afterDocStart + m[0].length;\n    // Detect if the spec already declares `tier:` — if so, leave it.\n    const restOfFile = source.slice(openBraceAbs, openBraceAbs + 4000);\n    if (/\\btier\\s*:/.test(restOfFile.slice(0, indexOfMatchingBrace(restOfFile)))) {\n      i = afterDocStart;\n      continue;\n    }\n\n    // Emit everything between end-of-JSDoc and openBraceAbs.\n    out.push(source.slice(afterDocStart, openBraceAbs));\n\n    // Build the injected fields.\n    const injected: string[] = [];\n    injected.push(` tier: ${JSON.stringify(tier.tier)},`);\n    if (tier.tier === 'deprecated' && tier.reason !== undefined) {\n      injected.push(` deprecationReason: ${JSON.stringify(tier.reason)},`);\n    }\n    if (tier.tier === 'internal') {\n      injected.push(` internalToken: __actureInternalToken__,`);\n      internalCount++;\n    }\n    out.push(injected.join(''));\n\n    applied.push(tier.reason !== undefined ? { tier: tier.tier, reason: tier.reason } : { tier: tier.tier });\n\n    i = openBraceAbs;\n  }\n\n  let code = out.join('');\n  if (internalCount > 0) {\n    code = INTERNAL_TOKEN_DECL + code;\n  }\n  return { code, changed: applied.length > 0, applied };\n}\n\n/** Declared at module top so every `@internal` command in the file\n *  shares it. Cross-module callers cannot see it. */\nconst INTERNAL_TOKEN_DECL =\n  \"const __actureInternalToken__ = /* @__PURE__ */ Symbol('acture.internal');\\n\";\n\n/**\n * Find the offset of the matching closing brace for a string that\n * starts immediately after an opening `{` (the `{` is NOT in `text`).\n * Returns the index of the `}` (relative to `text`) on success, or\n * `text.length` if no balanced close is found.\n *\n * The scanner is intentionally minimal — it tracks nested `{}` only.\n * It treats string and template literals as opaque (skips matching\n * braces inside them) to a first approximation: handles single-quoted,\n * double-quoted, and backtick strings; does NOT handle template\n * substitutions perfectly (a `${` inside a backtick may foil it). The\n * defineCommand spec object is shallow enough that this is fine in\n * practice; users with exotic templates can write `tier: 'X'` manually.\n */\nfunction indexOfMatchingBrace(text: string): number {\n  let depth = 1;\n  let i = 0;\n  const len = text.length;\n  while (i < len) {\n    const ch = text[i]!;\n    if (ch === '\"' || ch === \"'\" || ch === '`') {\n      const quote = ch;\n      i++;\n      while (i < len) {\n        if (text[i] === '\\\\') { i += 2; continue; }\n        if (text[i] === quote) { i++; break; }\n        i++;\n      }\n      continue;\n    }\n    if (ch === '/' && text[i + 1] === '/') {\n      // line comment\n      while (i < len && text[i] !== '\\n') i++;\n      continue;\n    }\n    if (ch === '/' && text[i + 1] === '*') {\n      i += 2;\n      while (i < len && !(text[i] === '*' && text[i + 1] === '/')) i++;\n      i += 2;\n      continue;\n    }\n    if (ch === '{') depth++;\n    else if (ch === '}') {\n      depth--;\n      if (depth === 0) return i;\n    }\n    i++;\n  }\n  return len;\n}\n","/**\n * Vite plugin. Mirrors the esbuild plugin for `vite` consumers (the\n * greenfield example uses Vite).\n *\n * Usage in vite.config.ts:\n *\n *   import { actureBuildTierVite } from 'acture-build-tier/vite';\n *   export default defineConfig({\n *     plugins: [actureBuildTierVite()],\n *   });\n *\n * Vite runs `transform` hooks for every loaded module; we filter to\n * `.ts` / `.tsx` under the consumer's source tree and skip\n * `node_modules`.\n */\n\nimport { transformSource } from './transform.js';\n\n/** Minimal Vite plugin shape. Avoids pulling in vite as a dep. */\nexport interface VitePlugin {\n  name: string;\n  enforce?: 'pre' | 'post';\n  transform?(code: string, id: string): { code: string; map: null } | undefined;\n}\n\nexport interface ActureBuildTierViteOptions {\n  /** File-path regex. Defaults to `/\\\\.tsx?$/`. */\n  filter?: RegExp;\n  /** Skip transform for paths matching this regex. Defaults to a\n   *  `node_modules` matcher. */\n  exclude?: RegExp;\n}\n\n/** Vite plugin wrapper. Marked `enforce: 'pre'` so the transform runs\n *  before Vite's own TypeScript transform — the JSDoc must still be in\n *  the source when we scan. */\nexport function actureBuildTierVite(\n  options: ActureBuildTierViteOptions = {},\n): VitePlugin {\n  const filter = options.filter ?? /\\.tsx?$/;\n  const exclude = options.exclude ?? /node_modules/;\n  return {\n    name: 'acture-build-tier',\n    enforce: 'pre',\n    transform(code, id) {\n      if (!filter.test(id)) return undefined;\n      if (exclude.test(id)) return undefined;\n      const result = transformSource(code);\n      if (!result.changed) return undefined;\n      return { code: result.code, map: null };\n    },\n  };\n}\n"]}

package/dist/vite.d.cts

@@ -0,0 +1,37 @@
+/**
+ * Vite plugin. Mirrors the esbuild plugin for `vite` consumers (the
+ * greenfield example uses Vite).
+ *
+ * Usage in vite.config.ts:
+ *
+ *   import { actureBuildTierVite } from 'acture-build-tier/vite';
+ *   export default defineConfig({
+ *     plugins: [actureBuildTierVite()],
+ *   });
+ *
+ * Vite runs `transform` hooks for every loaded module; we filter to
+ * `.ts` / `.tsx` under the consumer's source tree and skip
+ * `node_modules`.
+ */
+/** Minimal Vite plugin shape. Avoids pulling in vite as a dep. */
+interface VitePlugin {
+    name: string;
+    enforce?: 'pre' | 'post';
+    transform?(code: string, id: string): {
+        code: string;
+        map: null;
+    } | undefined;
+}
+interface ActureBuildTierViteOptions {
+    /** File-path regex. Defaults to `/\\.tsx?$/`. */
+    filter?: RegExp;
+    /** Skip transform for paths matching this regex. Defaults to a
+     *  `node_modules` matcher. */
+    exclude?: RegExp;
+}
+/** Vite plugin wrapper. Marked `enforce: 'pre'` so the transform runs
+ *  before Vite's own TypeScript transform — the JSDoc must still be in
+ *  the source when we scan. */
+declare function actureBuildTierVite(options?: ActureBuildTierViteOptions): VitePlugin;
+
+export { type ActureBuildTierViteOptions, type VitePlugin, actureBuildTierVite };

package/dist/vite.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Vite plugin. Mirrors the esbuild plugin for `vite` consumers (the
+ * greenfield example uses Vite).
+ *
+ * Usage in vite.config.ts:
+ *
+ *   import { actureBuildTierVite } from 'acture-build-tier/vite';
+ *   export default defineConfig({
+ *     plugins: [actureBuildTierVite()],
+ *   });
+ *
+ * Vite runs `transform` hooks for every loaded module; we filter to
+ * `.ts` / `.tsx` under the consumer's source tree and skip
+ * `node_modules`.
+ */
+/** Minimal Vite plugin shape. Avoids pulling in vite as a dep. */
+interface VitePlugin {
+    name: string;
+    enforce?: 'pre' | 'post';
+    transform?(code: string, id: string): {
+        code: string;
+        map: null;
+    } | undefined;
+}
+interface ActureBuildTierViteOptions {
+    /** File-path regex. Defaults to `/\\.tsx?$/`. */
+    filter?: RegExp;
+    /** Skip transform for paths matching this regex. Defaults to a
+     *  `node_modules` matcher. */
+    exclude?: RegExp;
+}
+/** Vite plugin wrapper. Marked `enforce: 'pre'` so the transform runs
+ *  before Vite's own TypeScript transform — the JSDoc must still be in
+ *  the source when we scan. */
+declare function actureBuildTierVite(options?: ActureBuildTierViteOptions): VitePlugin;
+
+export { type ActureBuildTierViteOptions, type VitePlugin, actureBuildTierVite };

package/dist/vite.js

@@ -0,0 +1,22 @@
+import { transformSource } from './chunk-SWJN6WEL.js';
+
+// src/vite.ts
+function actureBuildTierVite(options = {}) {
+  const filter = options.filter ?? /\.tsx?$/;
+  const exclude = options.exclude ?? /node_modules/;
+  return {
+    name: "acture-build-tier",
+    enforce: "pre",
+    transform(code, id) {
+      if (!filter.test(id)) return void 0;
+      if (exclude.test(id)) return void 0;
+      const result = transformSource(code);
+      if (!result.changed) return void 0;
+      return { code: result.code, map: null };
+    }
+  };
+}
+
+export { actureBuildTierVite };
+//# sourceMappingURL=vite.js.map
+//# sourceMappingURL=vite.js.map

package/dist/vite.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/vite.ts"],"names":[],"mappings":";;;AAoCO,SAAS,mBAAA,CACd,OAAA,GAAsC,EAAC,EAC3B;AACZ,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,IAAU,SAAA;AACjC,EAAA,MAAM,OAAA,GAAU,QAAQ,OAAA,IAAW,cAAA;AACnC,EAAA,OAAO;AAAA,IACL,IAAA,EAAM,mBAAA;AAAA,IACN,OAAA,EAAS,KAAA;AAAA,IACT,SAAA,CAAU,MAAM,EAAA,EAAI;AAClB,MAAA,IAAI,CAAC,MAAA,CAAO,IAAA,CAAK,EAAE,GAAG,OAAO,MAAA;AAC7B,MAAA,IAAI,OAAA,CAAQ,IAAA,CAAK,EAAE,CAAA,EAAG,OAAO,MAAA;AAC7B,MAAA,MAAM,MAAA,GAAS,gBAAgB,IAAI,CAAA;AACnC,MAAA,IAAI,CAAC,MAAA,CAAO,OAAA,EAAS,OAAO,MAAA;AAC5B,MAAA,OAAO,EAAE,IAAA,EAAM,MAAA,CAAO,IAAA,EAAM,KAAK,IAAA,EAAK;AAAA,IACxC;AAAA,GACF;AACF","file":"vite.js","sourcesContent":["/**\n * Vite plugin. Mirrors the esbuild plugin for `vite` consumers (the\n * greenfield example uses Vite).\n *\n * Usage in vite.config.ts:\n *\n *   import { actureBuildTierVite } from 'acture-build-tier/vite';\n *   export default defineConfig({\n *     plugins: [actureBuildTierVite()],\n *   });\n *\n * Vite runs `transform` hooks for every loaded module; we filter to\n * `.ts` / `.tsx` under the consumer's source tree and skip\n * `node_modules`.\n */\n\nimport { transformSource } from './transform.js';\n\n/** Minimal Vite plugin shape. Avoids pulling in vite as a dep. */\nexport interface VitePlugin {\n  name: string;\n  enforce?: 'pre' | 'post';\n  transform?(code: string, id: string): { code: string; map: null } | undefined;\n}\n\nexport interface ActureBuildTierViteOptions {\n  /** File-path regex. Defaults to `/\\\\.tsx?$/`. */\n  filter?: RegExp;\n  /** Skip transform for paths matching this regex. Defaults to a\n   *  `node_modules` matcher. */\n  exclude?: RegExp;\n}\n\n/** Vite plugin wrapper. Marked `enforce: 'pre'` so the transform runs\n *  before Vite's own TypeScript transform — the JSDoc must still be in\n *  the source when we scan. */\nexport function actureBuildTierVite(\n  options: ActureBuildTierViteOptions = {},\n): VitePlugin {\n  const filter = options.filter ?? /\\.tsx?$/;\n  const exclude = options.exclude ?? /node_modules/;\n  return {\n    name: 'acture-build-tier',\n    enforce: 'pre',\n    transform(code, id) {\n      if (!filter.test(id)) return undefined;\n      if (exclude.test(id)) return undefined;\n      const result = transformSource(code);\n      if (!result.changed) return undefined;\n      return { code: result.code, map: null };\n    },\n  };\n}\n"]}