acture-build-tier 1.1.0

package/LICENSE

@@ -0,0 +1,190 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to the Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by the Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding any notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   Copyright 2026 Thor Whalen
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.md

@@ -0,0 +1,112 @@
+# acture-build-tier
+
+> **acture is a development tool first.** This is dev/build-time tooling — it never becomes a runtime dependency of the apps it serves, and using it is entirely optional. See [`docs/positioning.md`](../../docs/positioning.md).
+
+Build-step plugin. Scans `.ts` / `.tsx` source for JSDoc tier tags on `defineCommand` calls and mirrors them into the runtime command's `tier` metadata field.
+
+## Install
+
+```bash
+pnpm add -D acture-build-tier
+```
+
+## tsup / esbuild
+
+```ts
+// tsup.config.ts
+import { defineConfig } from 'tsup';
+import { actureBuildTier } from 'acture-build-tier/esbuild';
+
+export default defineConfig({
+  entry: ['src/index.ts'],
+  esbuildPlugins: [actureBuildTier()],
+});
+```
+
+## Vite
+
+```ts
+// vite.config.ts
+import { defineConfig } from 'vite';
+import { actureBuildTierVite } from 'acture-build-tier/vite';
+
+export default defineConfig({
+  plugins: [actureBuildTierVite()],
+});
+```
+
+## What it does
+
+```ts
+/**
+ * Search users by email or display name.
+ * @stable
+ */
+export const searchUsers = defineCommand({
+  id: 'app.users.search',
+  title: 'Search Users',
+  execute: async (params) => { /* ... */ },
+});
+```
+
+becomes (effectively):
+
+```ts
+export const searchUsers = defineCommand({
+  tier: "stable",
+  id: 'app.users.search',
+  title: 'Search Users',
+  execute: async (params) => { /* ... */ },
+});
+```
+
+Four tags recognized:
+
+- `@stable` — `tier: 'stable'`
+- `@experimental` — `tier: 'experimental'`
+- `@deprecated [reason]` — `tier: 'deprecated'` plus `deprecationReason: '<reason>'`
+- `@internal` — `tier: 'internal'` plus `internalToken: <module-scoped Symbol>`
+
+Precedence (most-restrictive wins): `@internal` > `@deprecated` > `@experimental` > `@stable`.
+
+The plugin is **idempotent**: if a spec already declares `tier:` explicitly, the JSDoc is ignored. So you can mix hand-written and tag-driven tiers without conflict.
+
+## `@internal` enforcement
+
+For each file containing at least one `@internal` command, the plugin injects a per-file module-scoped Symbol:
+
+```ts
+const __actureInternalToken__ = /* @__PURE__ */ Symbol('acture.internal');
+```
+
+Each `@internal` command's `internalToken` field references this Symbol. The runtime registry rejects `dispatch` calls from outside the module (i.e., from any caller that didn't capture the Symbol at module load). See [`acture-tier-system`](../../.claude/skills/acture-tier-system/SKILL.md) §7.5.
+
+## AST mode (v1.2)
+
+The default transform is regex-based and intentionally conservative: when the surrounding source is exotic enough to outrun the regex's 4000-char lookahead, the spec falls through and keeps its hand-written `tier` (defaulting to `'stable'`).
+
+For projects where AST-level certainty matters more than a fast regex pass, an AST mode is available behind the `/ast` entry point:
+
+```ts
+// custom bundler plugin
+import { transformSourceAst } from 'acture-build-tier/ast';
+
+export function actureTierAstPlugin() {
+  return {
+    name: 'acture-tier-ast',
+    transform(code: string, id: string) {
+      if (!id.endsWith('.ts') && !id.endsWith('.tsx')) return null;
+      const { code: out, changed } = transformSourceAst(code);
+      return changed ? { code: out, map: null } : null;
+    },
+  };
+}
+```
+
+`ts-morph` is an **optional peer dependency** — pulled in only if you import the AST entry point. The output is interchangeable with the regex mode on every case the regex handles correctly; AST mode also handles 5000-char spec bodies and template-literal `${...}` substitutions the regex skips.
+
+## Caveats
+
+- Default mode is regex-based, not AST. The common case is recognized; exotic JSDoc-or-call shapes are silently ignored (the user's spec keeps its hand-written `tier`, defaulting to `'stable'`). Use `/ast` if your codebase trips this.
+- 4000-char per-call lookahead window for the matching-brace scan (regex mode). Real specs are O(20 lines); this is comfortably generous.
+- No `.d.ts` mirror — the JSDoc tag survives into `.d.ts` natively (IDE hover shows it), but the resolved `tier` value lives in the JS runtime output only.

package/dist/ast.cjs

@@ -0,0 +1,146 @@
+'use strict';
+
+var tsMorph = require('ts-morph');
+
+// src/ast.ts
+
+// 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;
+}
+
+// src/ast.ts
+var INTERNAL_TOKEN_NAME = "__actureInternalToken__";
+var INTERNAL_TOKEN_DECL = `const ${INTERNAL_TOKEN_NAME} = /* @__PURE__ */ Symbol('acture.internal');
+`;
+function transformSourceAst(source) {
+  if (!source.includes("defineCommand")) {
+    return { code: source, changed: false, applied: [] };
+  }
+  const project = new tsMorph.Project({
+    useInMemoryFileSystem: true,
+    compilerOptions: { target: tsMorph.ScriptTarget.ES2022, allowJs: false },
+    skipAddingFilesFromTsConfig: true,
+    skipFileDependencyResolution: true
+  });
+  const file = project.createSourceFile("__acture_build_tier__.ts", source);
+  const applied = [];
+  let internalCount = 0;
+  for (const call of findDefineCommandCalls(file)) {
+    const spec = firstObjectLiteralArg(call);
+    if (!spec) continue;
+    if (hasTierProperty(spec)) continue;
+    const jsdocBody = readLeadingJsdocBody(call);
+    if (!jsdocBody) continue;
+    const directive = parseTierDirective(jsdocBody);
+    if (!directive) continue;
+    const props = [];
+    props.push(`tier: ${JSON.stringify(directive.tier)}`);
+    if (directive.tier === "deprecated" && directive.reason !== void 0) {
+      props.push(`deprecationReason: ${JSON.stringify(directive.reason)}`);
+    }
+    if (directive.tier === "internal") {
+      props.push(`internalToken: ${INTERNAL_TOKEN_NAME}`);
+      internalCount++;
+    }
+    insertPropertiesAtStart(spec, props);
+    applied.push(
+      directive.reason !== void 0 ? { tier: directive.tier, reason: directive.reason } : { tier: directive.tier }
+    );
+  }
+  let code = file.getFullText();
+  if (internalCount > 0) {
+    code = INTERNAL_TOKEN_DECL + code;
+  }
+  return { code, changed: applied.length > 0, applied };
+}
+function findDefineCommandCalls(file) {
+  const calls = [];
+  file.forEachDescendant((node) => {
+    if (node.getKind() !== tsMorph.SyntaxKind.CallExpression) return;
+    const call = node;
+    if (call.getExpression().getText() !== "defineCommand") return;
+    calls.push(call);
+  });
+  return calls;
+}
+function firstObjectLiteralArg(call) {
+  const args = call.getArguments();
+  if (args.length === 0) return null;
+  const first = args[0];
+  if (first.getKind() !== tsMorph.SyntaxKind.ObjectLiteralExpression) return null;
+  return first;
+}
+function hasTierProperty(spec) {
+  return spec.getProperties().some((p) => {
+    if (p.getKind() !== tsMorph.SyntaxKind.PropertyAssignment) return false;
+    const name = p.getName?.();
+    return name === "tier";
+  });
+}
+function readLeadingJsdocBody(node) {
+  let target = node;
+  while (true) {
+    const parent = target.getParent();
+    if (!parent) break;
+    const kind = parent.getKind();
+    if (kind === tsMorph.SyntaxKind.VariableDeclaration || kind === tsMorph.SyntaxKind.VariableDeclarationList || kind === tsMorph.SyntaxKind.VariableStatement || kind === tsMorph.SyntaxKind.ExpressionStatement) {
+      target = parent;
+      continue;
+    }
+    break;
+  }
+  const fullText = target.getSourceFile().getFullText();
+  const start = target.getFullStart();
+  const end = target.getStart();
+  const trivia = fullText.slice(start, end);
+  const match = /\/\*\*([\s\S]*?)\*\//g;
+  let last = null;
+  for (let m = match.exec(trivia); m !== null; m = match.exec(trivia)) {
+    last = m;
+  }
+  if (!last) return null;
+  return last[1] ?? "";
+}
+function insertPropertiesAtStart(spec, propTexts) {
+  const props = [...propTexts];
+  for (let i = props.length - 1; i >= 0; i--) {
+    spec.insertPropertyAssignment(0, parseStructure(props[i]));
+  }
+}
+function parseStructure(propText) {
+  const eq = propText.indexOf(":");
+  const name = propText.slice(0, eq).trim();
+  const initializer = propText.slice(eq + 1).trim();
+  return { name, initializer };
+}
+
+exports.transformSourceAst = transformSourceAst;
+//# sourceMappingURL=ast.cjs.map
+//# sourceMappingURL=ast.cjs.map

package/dist/ast.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/transform.ts","../src/ast.ts"],"names":["Project","ScriptTarget","SyntaxKind"],"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;;;ACpBA,IAAM,mBAAA,GAAsB,yBAAA;AAC5B,IAAM,mBAAA,GAAsB,SAAS,mBAAmB,CAAA;AAAA,CAAA;AAgBjD,SAAS,mBAAmB,MAAA,EAAiC;AAClE,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,OAAA,GAAU,IAAIA,eAAA,CAAQ;AAAA,IAC1B,qBAAA,EAAuB,IAAA;AAAA,IACvB,iBAAiB,EAAE,MAAA,EAAQC,oBAAA,CAAa,MAAA,EAAQ,SAAS,KAAA,EAAM;AAAA,IAC/D,2BAAA,EAA6B,IAAA;AAAA,IAC7B,4BAAA,EAA8B;AAAA,GAC/B,CAAA;AACD,EAAA,MAAM,IAAA,GAAO,OAAA,CAAQ,gBAAA,CAAiB,0BAAA,EAA4B,MAAM,CAAA;AAExE,EAAA,MAAM,UAAmG,EAAC;AAC1G,EAAA,IAAI,aAAA,GAAgB,CAAA;AAEpB,EAAA,KAAA,MAAW,IAAA,IAAQ,sBAAA,CAAuB,IAAI,CAAA,EAAG;AAC/C,IAAA,MAAM,IAAA,GAAO,sBAAsB,IAAI,CAAA;AACvC,IAAA,IAAI,CAAC,IAAA,EAAM;AACX,IAAA,IAAI,eAAA,CAAgB,IAAI,CAAA,EAAG;AAE3B,IAAA,MAAM,SAAA,GAAY,qBAAqB,IAAI,CAAA;AAC3C,IAAA,IAAI,CAAC,SAAA,EAAW;AAEhB,IAAA,MAAM,SAAA,GAAY,mBAAmB,SAAS,CAAA;AAC9C,IAAA,IAAI,CAAC,SAAA,EAAW;AAMhB,IAAA,MAAM,QAAkB,EAAC;AACzB,IAAA,KAAA,CAAM,KAAK,CAAA,MAAA,EAAS,IAAA,CAAK,UAAU,SAAA,CAAU,IAAI,CAAC,CAAA,CAAE,CAAA;AACpD,IAAA,IAAI,SAAA,CAAU,IAAA,KAAS,YAAA,IAAgB,SAAA,CAAU,WAAW,MAAA,EAAW;AACrE,MAAA,KAAA,CAAM,KAAK,CAAA,mBAAA,EAAsB,IAAA,CAAK,UAAU,SAAA,CAAU,MAAM,CAAC,CAAA,CAAE,CAAA;AAAA,IACrE;AACA,IAAA,IAAI,SAAA,CAAU,SAAS,UAAA,EAAY;AACjC,MAAA,KAAA,CAAM,IAAA,CAAK,CAAA,eAAA,EAAkB,mBAAmB,CAAA,CAAE,CAAA;AAClD,MAAA,aAAA,EAAA;AAAA,IACF;AAEA,IAAA,uBAAA,CAAwB,MAAM,KAAK,CAAA;AAEnC,IAAA,OAAA,CAAQ,IAAA;AAAA,MACN,SAAA,CAAU,MAAA,KAAW,MAAA,GACjB,EAAE,MAAM,SAAA,CAAU,IAAA,EAAM,MAAA,EAAQ,SAAA,CAAU,MAAA,EAAO,GACjD,EAAE,IAAA,EAAM,UAAU,IAAA;AAAK,KAC7B;AAAA,EACF;AAEA,EAAA,IAAI,IAAA,GAAO,KAAK,WAAA,EAAY;AAC5B,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,SAAS,uBAAuB,IAAA,EAAoC;AAClE,EAAA,MAAM,QAA0B,EAAC;AACjC,EAAA,IAAA,CAAK,iBAAA,CAAkB,CAAC,IAAA,KAAS;AAC/B,IAAA,IAAI,IAAA,CAAK,OAAA,EAAQ,KAAMC,kBAAA,CAAW,cAAA,EAAgB;AAClD,IAAA,MAAM,IAAA,GAAO,IAAA;AACb,IAAA,IAAI,IAAA,CAAK,aAAA,EAAc,CAAE,OAAA,OAAc,eAAA,EAAiB;AACxD,IAAA,KAAA,CAAM,KAAK,IAAI,CAAA;AAAA,EACjB,CAAC,CAAA;AACD,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,sBAAsB,IAAA,EAAsD;AACnF,EAAA,MAAM,IAAA,GAAO,KAAK,YAAA,EAAa;AAC/B,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG,OAAO,IAAA;AAC9B,EAAA,MAAM,KAAA,GAAQ,KAAK,CAAC,CAAA;AACpB,EAAA,IAAI,KAAA,CAAM,OAAA,EAAQ,KAAMA,kBAAA,CAAW,yBAAyB,OAAO,IAAA;AACnE,EAAA,OAAO,KAAA;AACT;AAEA,SAAS,gBAAgB,IAAA,EAAwC;AAC/D,EAAA,OAAO,IAAA,CAAK,aAAA,EAAc,CAAE,IAAA,CAAK,CAAC,CAAA,KAAM;AACtC,IAAA,IAAI,CAAA,CAAE,OAAA,EAAQ,KAAMA,kBAAA,CAAW,oBAAoB,OAAO,KAAA;AAC1D,IAAA,MAAM,IAAA,GAAQ,EAAwC,OAAA,IAAU;AAChE,IAAA,OAAO,IAAA,KAAS,MAAA;AAAA,EAClB,CAAC,CAAA;AACH;AAQA,SAAS,qBAAqB,IAAA,EAA2B;AACvD,EAAA,IAAI,MAAA,GAAe,IAAA;AAInB,EAAA,OAAO,IAAA,EAAM;AACX,IAAA,MAAM,MAAA,GAAS,OAAO,SAAA,EAAU;AAChC,IAAA,IAAI,CAAC,MAAA,EAAQ;AACb,IAAA,MAAM,IAAA,GAAO,OAAO,OAAA,EAAQ;AAC5B,IAAA,IACE,IAAA,KAASA,kBAAA,CAAW,mBAAA,IACpB,IAAA,KAASA,kBAAA,CAAW,uBAAA,IACpB,IAAA,KAASA,kBAAA,CAAW,iBAAA,IACpB,IAAA,KAASA,kBAAA,CAAW,mBAAA,EACpB;AACA,MAAA,MAAA,GAAS,MAAA;AACT,MAAA;AAAA,IACF;AACA,IAAA;AAAA,EACF;AAEA,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,aAAA,EAAc,CAAE,WAAA,EAAY;AACpD,EAAA,MAAM,KAAA,GAAQ,OAAO,YAAA,EAAa;AAClC,EAAA,MAAM,GAAA,GAAM,OAAO,QAAA,EAAS;AAC5B,EAAA,MAAM,MAAA,GAAS,QAAA,CAAS,KAAA,CAAM,KAAA,EAAO,GAAG,CAAA;AAExC,EAAA,MAAM,KAAA,GAAQ,uBAAA;AACd,EAAA,IAAI,IAAA,GAA+B,IAAA;AACnC,EAAA,KAAA,IAAS,CAAA,GAAI,KAAA,CAAM,IAAA,CAAK,MAAM,CAAA,EAAG,CAAA,KAAM,IAAA,EAAM,CAAA,GAAI,KAAA,CAAM,IAAA,CAAK,MAAM,CAAA,EAAG;AACnE,IAAA,IAAA,GAAO,CAAA;AAAA,EACT;AACA,EAAA,IAAI,CAAC,MAAM,OAAO,IAAA;AAClB,EAAA,OAAO,IAAA,CAAK,CAAC,CAAA,IAAK,EAAA;AACpB;AAEA,SAAS,uBAAA,CACP,MACA,SAAA,EACM;AAGN,EAAA,MAAM,KAAA,GAAQ,CAAC,GAAG,SAAS,CAAA;AAC3B,EAAA,KAAA,IAAS,IAAI,KAAA,CAAM,MAAA,GAAS,CAAA,EAAG,CAAA,IAAK,GAAG,CAAA,EAAA,EAAK;AAC1C,IAAA,IAAA,CAAK,yBAAyB,CAAA,EAAG,cAAA,CAAe,KAAA,CAAM,CAAC,CAAE,CAAC,CAAA;AAAA,EAC5D;AACF;AAEA,SAAS,eAAe,QAAA,EAAyD;AAC/E,EAAA,MAAM,EAAA,GAAK,QAAA,CAAS,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,MAAM,OAAO,QAAA,CAAS,KAAA,CAAM,CAAA,EAAG,EAAE,EAAE,IAAA,EAAK;AACxC,EAAA,MAAM,cAAc,QAAA,CAAS,KAAA,CAAM,EAAA,GAAK,CAAC,EAAE,IAAA,EAAK;AAChD,EAAA,OAAO,EAAE,MAAM,WAAA,EAAY;AAC7B","file":"ast.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 * AST-mode tier mirror — the ts-morph companion to the regex\n * `transformSource` in `./transform.ts`.\n *\n * Why an AST mode exists (phase-4-reflection §1, caveat 1): the regex\n * transform handles the 95th-percentile form (JSDoc directly above a\n * `defineCommand({...})` call, with optional declaration prefix). It\n * caps its per-call lookahead at 4000 chars to stay fast, and treats\n * template-substitution braces conservatively. For projects with\n * heavily macro'd source — or where a CI gate wants *AST-level\n * certainty* rather than a fast regex pass — the AST mode is the\n * second entry point.\n *\n * The AST mode produces the same output as the regex transform on\n * every case the regex handles correctly. Where the regex falls\n * through (e.g. 5000-char spec body, template literals containing\n * `${`-delimited substitutions with braces), the AST mode still\n * applies the transformation. The two modes are interchangeable\n * outputs for normal input.\n *\n * Cost: ts-morph is a real dependency (~7 MB). It is declared as an\n * *optional peer* of `acture-build-tier` so consumers who only use\n * the regex mode don't pay for it. Importing this file pulls ts-morph\n * in lazily.\n *\n * Usage:\n *\n *     // tsup, vite, etc. — point your plugin at the AST transform:\n *     import { transformSourceAst } from 'acture-build-tier/ast';\n *\n *     export function actureTierAstPlugin(): Plugin {\n *       return {\n *         name: 'acture-tier-ast',\n *         transform(code, id) {\n *           if (!id.endsWith('.ts') && !id.endsWith('.tsx')) return null;\n *           const { code: out, changed } = transformSourceAst(code);\n *           return changed ? { code: out, map: null } : null;\n *         },\n *       };\n *     }\n *\n * The regex mode at `acture-build-tier/esbuild` and\n * `acture-build-tier/vite` is the documented default. Use AST mode\n * when the regex's lookahead window or string handling is insufficient.\n */\n\nimport {\n  Project,\n  ScriptTarget,\n  SyntaxKind,\n  type CallExpression,\n  type Node,\n  type ObjectLiteralExpression,\n  type SourceFile,\n} from 'ts-morph';\nimport { parseTierDirective, type TransformResult } from './transform.js';\n\nconst INTERNAL_TOKEN_NAME = '__actureInternalToken__';\nconst INTERNAL_TOKEN_DECL = `const ${INTERNAL_TOKEN_NAME} = /* @__PURE__ */ Symbol('acture.internal');\\n`;\n\n/**\n * AST-mode counterpart of `transformSource`. Same input/output contract:\n * a `defineCommand({...})` call with a JSDoc tier tag gets `tier`,\n * `deprecationReason`, and/or `internalToken` injected into the spec.\n *\n * Idempotent: if the spec already declares `tier:`, the call is left\n * alone (matches the regex mode's behavior).\n *\n * Conservative: any `defineCommand` call that isn't a direct top-level\n * declaration or expression statement is processed the same way —\n * ts-morph walks ALL CallExpression nodes. The JSDoc lookup uses the\n * compiler's leading-comment-ranges API, which correctly attributes\n * docblocks regardless of how deeply nested the call is.\n */\nexport function transformSourceAst(source: string): TransformResult {\n  if (!source.includes('defineCommand')) {\n    return { code: source, changed: false, applied: [] };\n  }\n\n  const project = new Project({\n    useInMemoryFileSystem: true,\n    compilerOptions: { target: ScriptTarget.ES2022, allowJs: false },\n    skipAddingFilesFromTsConfig: true,\n    skipFileDependencyResolution: true,\n  });\n  const file = project.createSourceFile('__acture_build_tier__.ts', source);\n\n  const applied: Array<{ tier: 'stable' | 'experimental' | 'internal' | 'deprecated'; reason?: string }> = [];\n  let internalCount = 0;\n\n  for (const call of findDefineCommandCalls(file)) {\n    const spec = firstObjectLiteralArg(call);\n    if (!spec) continue;\n    if (hasTierProperty(spec)) continue; // idempotent\n\n    const jsdocBody = readLeadingJsdocBody(call);\n    if (!jsdocBody) continue;\n\n    const directive = parseTierDirective(jsdocBody);\n    if (!directive) continue;\n\n    // Build the property text. We could go through ts-morph's\n    // `insertPropertyAssignment` API, but for the small set of property\n    // names we inject the text path is simpler and produces predictable\n    // output that lines up with the regex mode's emission.\n    const props: string[] = [];\n    props.push(`tier: ${JSON.stringify(directive.tier)}`);\n    if (directive.tier === 'deprecated' && directive.reason !== undefined) {\n      props.push(`deprecationReason: ${JSON.stringify(directive.reason)}`);\n    }\n    if (directive.tier === 'internal') {\n      props.push(`internalToken: ${INTERNAL_TOKEN_NAME}`);\n      internalCount++;\n    }\n\n    insertPropertiesAtStart(spec, props);\n\n    applied.push(\n      directive.reason !== undefined\n        ? { tier: directive.tier, reason: directive.reason }\n        : { tier: directive.tier },\n    );\n  }\n\n  let code = file.getFullText();\n  if (internalCount > 0) {\n    code = INTERNAL_TOKEN_DECL + code;\n  }\n  return { code, changed: applied.length > 0, applied };\n}\n\n/* ───────────────────────── internals ──────────────────────────────── */\n\nfunction findDefineCommandCalls(file: SourceFile): CallExpression[] {\n  const calls: CallExpression[] = [];\n  file.forEachDescendant((node) => {\n    if (node.getKind() !== SyntaxKind.CallExpression) return;\n    const call = node as CallExpression;\n    if (call.getExpression().getText() !== 'defineCommand') return;\n    calls.push(call);\n  });\n  return calls;\n}\n\nfunction firstObjectLiteralArg(call: CallExpression): ObjectLiteralExpression | null {\n  const args = call.getArguments();\n  if (args.length === 0) return null;\n  const first = args[0]!;\n  if (first.getKind() !== SyntaxKind.ObjectLiteralExpression) return null;\n  return first as ObjectLiteralExpression;\n}\n\nfunction hasTierProperty(spec: ObjectLiteralExpression): boolean {\n  return spec.getProperties().some((p) => {\n    if (p.getKind() !== SyntaxKind.PropertyAssignment) return false;\n    const name = (p as Node & { getName?: () => string }).getName?.();\n    return name === 'tier';\n  });\n}\n\n/**\n * Find the *attached* JSDoc block for a node, climbing through wrapping\n * `const x = …` / `export const x = …` declarations. ts-morph's\n * `getLeadingCommentRanges` would also work but doesn't follow these\n * wrappers cleanly.\n */\nfunction readLeadingJsdocBody(node: Node): string | null {\n  let target: Node = node;\n  // Walk up CallExpression → VariableDeclaration → VariableStatement\n  // (or → ExpressionStatement). The JSDoc is attached to the\n  // outermost declaration in the source.\n  while (true) {\n    const parent = target.getParent();\n    if (!parent) break;\n    const kind = parent.getKind();\n    if (\n      kind === SyntaxKind.VariableDeclaration ||\n      kind === SyntaxKind.VariableDeclarationList ||\n      kind === SyntaxKind.VariableStatement ||\n      kind === SyntaxKind.ExpressionStatement\n    ) {\n      target = parent;\n      continue;\n    }\n    break;\n  }\n  // Read leading trivia.\n  const fullText = target.getSourceFile().getFullText();\n  const start = target.getFullStart();\n  const end = target.getStart();\n  const trivia = fullText.slice(start, end);\n  // Find LAST JSDoc block in the trivia.\n  const match = /\\/\\*\\*([\\s\\S]*?)\\*\\//g;\n  let last: RegExpExecArray | null = null;\n  for (let m = match.exec(trivia); m !== null; m = match.exec(trivia)) {\n    last = m;\n  }\n  if (!last) return null;\n  return last[1] ?? '';\n}\n\nfunction insertPropertiesAtStart(\n  spec: ObjectLiteralExpression,\n  propTexts: readonly string[],\n): void {\n  // We prepend in reverse so the visible order is `tier`, then\n  // `deprecationReason`, then `internalToken`.\n  const props = [...propTexts];\n  for (let i = props.length - 1; i >= 0; i--) {\n    spec.insertPropertyAssignment(0, parseStructure(props[i]!));\n  }\n}\n\nfunction parseStructure(propText: string): { name: string; initializer: string } {\n  const eq = propText.indexOf(':');\n  const name = propText.slice(0, eq).trim();\n  const initializer = propText.slice(eq + 1).trim();\n  return { name, initializer };\n}\n"]}

package/dist/ast.d.cts

@@ -0,0 +1,65 @@
+import { TransformResult } from './index.cjs';
+
+/**
+ * AST-mode tier mirror — the ts-morph companion to the regex
+ * `transformSource` in `./transform.ts`.
+ *
+ * Why an AST mode exists (phase-4-reflection §1, caveat 1): the regex
+ * transform handles the 95th-percentile form (JSDoc directly above a
+ * `defineCommand({...})` call, with optional declaration prefix). It
+ * caps its per-call lookahead at 4000 chars to stay fast, and treats
+ * template-substitution braces conservatively. For projects with
+ * heavily macro'd source — or where a CI gate wants *AST-level
+ * certainty* rather than a fast regex pass — the AST mode is the
+ * second entry point.
+ *
+ * The AST mode produces the same output as the regex transform on
+ * every case the regex handles correctly. Where the regex falls
+ * through (e.g. 5000-char spec body, template literals containing
+ * `${`-delimited substitutions with braces), the AST mode still
+ * applies the transformation. The two modes are interchangeable
+ * outputs for normal input.
+ *
+ * Cost: ts-morph is a real dependency (~7 MB). It is declared as an
+ * *optional peer* of `acture-build-tier` so consumers who only use
+ * the regex mode don't pay for it. Importing this file pulls ts-morph
+ * in lazily.
+ *
+ * Usage:
+ *
+ *     // tsup, vite, etc. — point your plugin at the AST transform:
+ *     import { transformSourceAst } from 'acture-build-tier/ast';
+ *
+ *     export function actureTierAstPlugin(): Plugin {
+ *       return {
+ *         name: 'acture-tier-ast',
+ *         transform(code, id) {
+ *           if (!id.endsWith('.ts') && !id.endsWith('.tsx')) return null;
+ *           const { code: out, changed } = transformSourceAst(code);
+ *           return changed ? { code: out, map: null } : null;
+ *         },
+ *       };
+ *     }
+ *
+ * The regex mode at `acture-build-tier/esbuild` and
+ * `acture-build-tier/vite` is the documented default. Use AST mode
+ * when the regex's lookahead window or string handling is insufficient.
+ */
+
+/**
+ * AST-mode counterpart of `transformSource`. Same input/output contract:
+ * a `defineCommand({...})` call with a JSDoc tier tag gets `tier`,
+ * `deprecationReason`, and/or `internalToken` injected into the spec.
+ *
+ * Idempotent: if the spec already declares `tier:`, the call is left
+ * alone (matches the regex mode's behavior).
+ *
+ * Conservative: any `defineCommand` call that isn't a direct top-level
+ * declaration or expression statement is processed the same way —
+ * ts-morph walks ALL CallExpression nodes. The JSDoc lookup uses the
+ * compiler's leading-comment-ranges API, which correctly attributes
+ * docblocks regardless of how deeply nested the call is.
+ */
+declare function transformSourceAst(source: string): TransformResult;
+
+export { transformSourceAst };

package/dist/ast.d.ts

@@ -0,0 +1,65 @@
+import { TransformResult } from './index.js';
+
+/**
+ * AST-mode tier mirror — the ts-morph companion to the regex
+ * `transformSource` in `./transform.ts`.
+ *
+ * Why an AST mode exists (phase-4-reflection §1, caveat 1): the regex
+ * transform handles the 95th-percentile form (JSDoc directly above a
+ * `defineCommand({...})` call, with optional declaration prefix). It
+ * caps its per-call lookahead at 4000 chars to stay fast, and treats
+ * template-substitution braces conservatively. For projects with
+ * heavily macro'd source — or where a CI gate wants *AST-level
+ * certainty* rather than a fast regex pass — the AST mode is the
+ * second entry point.
+ *
+ * The AST mode produces the same output as the regex transform on
+ * every case the regex handles correctly. Where the regex falls
+ * through (e.g. 5000-char spec body, template literals containing
+ * `${`-delimited substitutions with braces), the AST mode still
+ * applies the transformation. The two modes are interchangeable
+ * outputs for normal input.
+ *
+ * Cost: ts-morph is a real dependency (~7 MB). It is declared as an
+ * *optional peer* of `acture-build-tier` so consumers who only use
+ * the regex mode don't pay for it. Importing this file pulls ts-morph
+ * in lazily.
+ *
+ * Usage:
+ *
+ *     // tsup, vite, etc. — point your plugin at the AST transform:
+ *     import { transformSourceAst } from 'acture-build-tier/ast';
+ *
+ *     export function actureTierAstPlugin(): Plugin {
+ *       return {
+ *         name: 'acture-tier-ast',
+ *         transform(code, id) {
+ *           if (!id.endsWith('.ts') && !id.endsWith('.tsx')) return null;
+ *           const { code: out, changed } = transformSourceAst(code);
+ *           return changed ? { code: out, map: null } : null;
+ *         },
+ *       };
+ *     }
+ *
+ * The regex mode at `acture-build-tier/esbuild` and
+ * `acture-build-tier/vite` is the documented default. Use AST mode
+ * when the regex's lookahead window or string handling is insufficient.
+ */
+
+/**
+ * AST-mode counterpart of `transformSource`. Same input/output contract:
+ * a `defineCommand({...})` call with a JSDoc tier tag gets `tier`,
+ * `deprecationReason`, and/or `internalToken` injected into the spec.
+ *
+ * Idempotent: if the spec already declares `tier:`, the call is left
+ * alone (matches the regex mode's behavior).
+ *
+ * Conservative: any `defineCommand` call that isn't a direct top-level
+ * declaration or expression statement is processed the same way —
+ * ts-morph walks ALL CallExpression nodes. The JSDoc lookup uses the
+ * compiler's leading-comment-ranges API, which correctly attributes
+ * docblocks regardless of how deeply nested the call is.
+ */
+declare function transformSourceAst(source: string): TransformResult;
+
+export { transformSourceAst };