@caretcms/caretize 0.1.0

package/dist/import-wrap.js

@@ -0,0 +1,149 @@
+/**
+ * Tier-3 editable() wrapping for IMPORTED data — PURE INSERTION.
+ *
+ * A very common Astro pattern keeps list content in a data file and renders it
+ * with `.map()`:
+ *
+ *   import faqs from "./data/faqs.json";
+ *   …
+ *   {faqs.map((f) => <details>{f.question}…</details>)}
+ *
+ * caretize's Tier-1 wrap only sees inline-literal consts (`const x = [...]`), so
+ * this content was previously left un-editable. Tier-3 makes it editable WITHOUT
+ * moving any code: it suffixes the import binding and rebinds the original name
+ * to an `editable()` wrap of it —
+ *
+ *   import faqsRaw from "./data/faqs.json";
+ *   const faqs = await editable("pages::home::faqs", faqsRaw);
+ *
+ * Every original character survives in order (the import binding only GAINS a
+ * suffix; a new const line is inserted), so the result is a provable pure
+ * insertion — the same subsequence safety contract as Tier-1. The `.map()`
+ * consumer is untouched and now reads the stega-encoded, click-to-edit value.
+ */
+import { deriveScope, isValidField, slugifyText } from "./name.js";
+import { parseAstro } from "./parse.js";
+import { classifyConstUsage } from "./usage.js";
+import { frontmatterRange, importBindingNames, } from "./frontmatter.js";
+import { isIdentifier } from "./identifiers.js";
+import { IMPORT_LINE, IMPORT_RE } from "./wrap.js";
+/** Pick a non-colliding suffixed name for the raw (pre-editable) import binding. */
+function rawNameFor(source, varName) {
+    for (const suffix of ["Raw", "Source", "Data"]) {
+        const candidate = `${varName}${suffix}`;
+        if (!new RegExp(`\\b${candidate}\\b`).test(source))
+            return candidate;
+    }
+    return null;
+}
+/**
+ * Rebind an imported `varName` to `await editable("<key>", <varName>Raw)` and
+ * ensure the import is present. Pure insertion: the import binding gains a
+ * suffix and a new const line is inserted; nothing is deleted.
+ */
+export function wrapImport(source, varName, key) {
+    if (!isIdentifier(varName)) {
+        return { output: source, ok: false, reason: `invalid identifier: ${varName}` };
+    }
+    const fm = frontmatterRange(source);
+    if (!fm)
+        return { output: source, ok: false, reason: "no frontmatter block" };
+    const fmText = source.slice(fm.start, fm.end);
+    // Idempotent: bail if this binding is already an editable() rebind.
+    if (new RegExp(`\\bconst\\s+${varName}\\s*=\\s*await\\s+editable\\s*\\(`).test(fmText)) {
+        return { output: source, ok: true, alreadyWrapped: true };
+    }
+    const importRe = new RegExp(`\\bimport\\s+(?!type\\b)(${varName})\\s+from\\s*['"][^'"]+['"]`);
+    const m = importRe.exec(fmText);
+    if (!m) {
+        return { output: source, ok: false, reason: `default import of ${varName} not found` };
+    }
+    const rawName = rawNameFor(source, varName);
+    if (!rawName) {
+        return { output: source, ok: false, reason: `could not pick a free name for ${varName}` };
+    }
+    // Offset just past the binding identifier (insert the suffix here).
+    const kw = /^import\s+/.exec(m[0])[0];
+    const identEndRel = m.index + kw.length + varName.length;
+    // Offset just past the import statement, swallowing an optional `;`.
+    let stmtEndRel = m.index + m[0].length;
+    if (fmText[stmtEndRel] === ";")
+        stmtEndRel++;
+    const identEndAbs = fm.start + identEndRel;
+    const stmtEndAbs = fm.start + stmtEndRel;
+    const suffix = rawName.slice(varName.length); // e.g. "Raw"
+    const constLine = `\nconst ${varName} = await editable(${JSON.stringify(key)}, ${rawName});`;
+    // Two pure insertions, applied left-to-right via slicing: the binding gains
+    // `suffix`, and a new const line follows the import statement.
+    let output = source.slice(0, identEndAbs) +
+        suffix +
+        source.slice(identEndAbs, stmtEndAbs) +
+        constLine +
+        source.slice(stmtEndAbs);
+    if (!IMPORT_RE.test(source)) {
+        output = output.slice(0, fm.start) + IMPORT_LINE + "\n" + output.slice(fm.start);
+    }
+    return { output, ok: true };
+}
+/**
+ * Detect Tier-3 candidates: DEFAULT imports of a `.json`/module data file that
+ * are `.map()`/`.flatMap()`'d in the template. Key is derived from the file's
+ * scope (`collection::id`) plus the binding name as the field.
+ */
+export function detectImportWrapCandidates(source, relPath) {
+    const fm = frontmatterRange(source);
+    if (!fm)
+        return [];
+    const fmText = source.slice(fm.start, fm.end);
+    const template = source.slice(fm.end);
+    const imports = importBindingNames(fmText);
+    if (imports.size === 0)
+        return [];
+    // Of the imported bindings, the ones actually iterated in the template.
+    const mapped = new Set();
+    const mapRe = /\b([A-Za-z_$][\w$]*)\s*\.\s*(?:map|flatMap)\b/g;
+    let mm;
+    while ((mm = mapRe.exec(template))) {
+        if (imports.has(mm[1]))
+            mapped.add(mm[1]);
+    }
+    if (mapped.size === 0)
+        return [];
+    const scoped = deriveScope(relPath);
+    if ("skip" in scoped)
+        return [];
+    const { collection, id } = scoped.scope;
+    const candidates = [];
+    for (const varName of mapped) {
+        // Already rebound on a prior run → not a candidate.
+        if (new RegExp(`\\bconst\\s+${varName}\\s*=\\s*await\\s+editable\\s*\\(`).test(fmText)) {
+            continue;
+        }
+        const field = isValidField(varName) ? varName : slugifyText(varName);
+        if (!field)
+            continue;
+        const meta = imports.get(varName);
+        candidates.push({
+            varName,
+            key: `${collection}::${id}::${field}`,
+            specifier: meta.specifier,
+            importKind: meta.importKind,
+        });
+    }
+    return candidates;
+}
+/**
+ * Safety-checked Tier-3 detection: import-backed candidates minus any whose
+ * mapped fields flow into a native-element attribute (where `editable()`'s stega
+ * encoding would corrupt an href/src/class/…). Mirrors `detectWrapTargetsSafe`.
+ */
+export async function detectImportWrapTargetsSafe(source, relPath, root) {
+    const candidates = detectImportWrapCandidates(source, relPath);
+    if (candidates.length === 0)
+        return [];
+    const ast = root ?? (await parseAstro(source));
+    return candidates
+        .filter((c) => classifyConstUsage(ast, c.varName).safe)
+        .map((c) => ({ varName: c.varName, key: c.key, origin: "import" }));
+}
+//# sourceMappingURL=import-wrap.js.map

package/dist/import-wrap.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-wrap.js","sourceRoot":"","sources":["../src/import-wrap.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,EAAE,WAAW,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACnE,OAAO,EAAE,UAAU,EAAkB,MAAM,YAAY,CAAC;AACxD,OAAO,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAChD,OAAO,EACL,gBAAgB,EAChB,kBAAkB,GAEnB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,SAAS,EAAoC,MAAM,WAAW,CAAC;AAcrF,oFAAoF;AACpF,SAAS,UAAU,CAAC,MAAc,EAAE,OAAe;IACjD,KAAK,MAAM,MAAM,IAAI,CAAC,KAAK,EAAE,QAAQ,EAAE,MAAM,CAAC,EAAE,CAAC;QAC/C,MAAM,SAAS,GAAG,GAAG,OAAO,GAAG,MAAM,EAAE,CAAC;QACxC,IAAI,CAAC,IAAI,MAAM,CAAC,MAAM,SAAS,KAAK,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC;YAAE,OAAO,SAAS,CAAC;IACvE,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,UAAU,CAAC,MAAc,EAAE,OAAe,EAAE,GAAW;IACrE,IAAI,CAAC,YAAY,CAAC,OAAO,CAAC,EAAE,CAAC;QAC3B,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,uBAAuB,OAAO,EAAE,EAAE,CAAC;IACjF,CAAC;IAED,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,sBAAsB,EAAE,CAAC;IAE9E,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAE9C,oEAAoE;IACpE,IAAI,IAAI,MAAM,CAAC,eAAe,OAAO,mCAAmC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QACvF,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC;IAC5D,CAAC;IAED,MAAM,QAAQ,GAAG,IAAI,MAAM,CACzB,4BAA4B,OAAO,6BAA6B,CACjE,CAAC;IACF,MAAM,CAAC,GAAG,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;IAChC,IAAI,CAAC,CAAC,EAAE,CAAC;QACP,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,qBAAqB,OAAO,YAAY,EAAE,CAAC;IACzF,CAAC;IAED,MAAM,OAAO,GAAG,UAAU,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC5C,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,EAAE,EAAE,KAAK,EAAE,MAAM,EAAE,kCAAkC,OAAO,EAAE,EAAE,CAAC;IAC5F,CAAC;IAED,oEAAoE;IACpE,MAAM,EAAE,GAAG,YAAY,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAE,CAAC,CAAC,CAAC,CAAC;IACvC,MAAM,WAAW,GAAG,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IACzD,qEAAqE;IACrE,IAAI,UAAU,GAAG,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC;IACvC,IAAI,MAAM,CAAC,UAAU,CAAC,KAAK,GAAG;QAAE,UAAU,EAAE,CAAC;IAE7C,MAAM,WAAW,GAAG,EAAE,CAAC,KAAK,GAAG,WAAW,CAAC;IAC3C,MAAM,UAAU,GAAG,EAAE,CAAC,KAAK,GAAG,UAAU,CAAC;IAEzC,MAAM,MAAM,GAAG,OAAO,CAAC,KAAK,CAAC,OAAO,CAAC,MAAM,CAAC,CAAC,CAAC,aAAa;IAC3D,MAAM,SAAS,GAAG,WAAW,OAAO,qBAAqB,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,KAAK,OAAO,IAAI,CAAC;IAE7F,4EAA4E;IAC5E,+DAA+D;IAC/D,IAAI,MAAM,GACR,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,WAAW,CAAC;QAC5B,MAAM;QACN,MAAM,CAAC,KAAK,CAAC,WAAW,EAAE,UAAU,CAAC;QACrC,SAAS;QACT,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC;IAE3B,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;QAC5B,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,WAAW,GAAG,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,CAAC,CAAC;IACnF,CAAC;IAED,OAAO,EAAE,MAAM,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC;AAC9B,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,0BAA0B,CACxC,MAAc,EACd,OAAe;IAEf,MAAM,EAAE,GAAG,gBAAgB,CAAC,MAAM,CAAC,CAAC;IACpC,IAAI,CAAC,EAAE;QAAE,OAAO,EAAE,CAAC;IACnB,MAAM,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,GAAG,CAAC,CAAC;IAC9C,MAAM,QAAQ,GAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC;IAEtC,MAAM,OAAO,GAAG,kBAAkB,CAAC,MAAM,CAAC,CAAC;IAC3C,IAAI,OAAO,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAElC,wEAAwE;IACxE,MAAM,MAAM,GAAG,IAAI,GAAG,EAAU,CAAC;IACjC,MAAM,KAAK,GAAG,gDAAgD,CAAC;IAC/D,IAAI,EAA0B,CAAC;IAC/B,OAAO,CAAC,EAAE,GAAG,KAAK,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC;YAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5C,CAAC;IACD,IAAI,MAAM,CAAC,IAAI,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IAEjC,MAAM,MAAM,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;IACpC,IAAI,MAAM,IAAI,MAAM;QAAE,OAAO,EAAE,CAAC;IAChC,MAAM,EAAE,UAAU,EAAE,EAAE,EAAE,GAAG,MAAM,CAAC,KAAK,CAAC;IAExC,MAAM,UAAU,GAA0B,EAAE,CAAC;IAC7C,KAAK,MAAM,OAAO,IAAI,MAAM,EAAE,CAAC;QAC7B,oDAAoD;QACpD,IAAI,IAAI,MAAM,CAAC,eAAe,OAAO,mCAAmC,CAAC,CAAC,IAAI,CAAC,MAAM,CAAC,EAAE,CAAC;YACvF,SAAS;QACX,CAAC;QACD,MAAM,KAAK,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,WAAW,CAAC,OAAO,CAAC,CAAC;QACrE,IAAI,CAAC,KAAK;YAAE,SAAS;QACrB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,OAAO,CAAE,CAAC;QACnC,UAAU,CAAC,IAAI,CAAC;YACd,OAAO;YACP,GAAG,EAAE,GAAG,UAAU,KAAK,EAAE,KAAK,KAAK,EAAE;YACrC,SAAS,EAAE,IAAI,CAAC,SAAS;YACzB,UAAU,EAAE,IAAI,CAAC,UAAU;SAC5B,CAAC,CAAC;IACL,CAAC;IACD,OAAO,UAAU,CAAC;AACpB,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,2BAA2B,CAC/C,MAAc,EACd,OAAe,EACf,IAAgB;IAEhB,MAAM,UAAU,GAAG,0BAA0B,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/D,IAAI,UAAU,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,EAAE,CAAC;IACvC,MAAM,GAAG,GAAG,IAAI,IAAI,CAAC,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC;IAC/C,OAAO,UAAU;SACd,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,kBAAkB,CAAC,GAAG,EAAE,CAAC,CAAC,OAAO,CAAC,CAAC,IAAI,CAAC;SACtD,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE,GAAG,EAAE,CAAC,CAAC,GAAG,EAAE,MAAM,EAAE,QAAiB,EAAE,CAAC,CAAC,CAAC;AACjF,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,18 @@
+/**
+ * @caretcms/caretize — public entry.
+ *
+ * v0.1 surfaces the byte-correct splice/parse core plus detection, naming, and
+ * planning. The interactive review loop and the CLI build on top of these.
+ */
+export { parseAstro, walkTags, isTagNode, tagElementAndVerify, type AstroNode, type TagNode, type ContainerNode, type TagResult, } from "./parse.js";
+export { findOpenTagEnd, spliceAttribute, type OpenTagEnd, } from "./splice.js";
+export { detect, type Candidate, type Skipped, type SkipReason, type Confidence, type CandidateKind, type IteratorFlag, type DetectResult, } from "./detect.js";
+export { deriveScope, assignFields, slugifyText, isValidCollection, isValidId, isValidField, type Scope, type ScopeReason, type ScopeResult, } from "./name.js";
+export { applyTags, type TagInsertion, type ApplyResult } from "./write.js";
+export { planFile, type PlannedTag, type FilePlan, type PlanOptions, } from "./plan.js";
+export { wrapConst, detectWrapTargetsSafe, type WrapResult, type WrapCandidate, type WrapTarget, type WrapOrigin, } from "./wrap.js";
+export { wrapImport, detectImportWrapCandidates, detectImportWrapTargetsSafe, type ImportWrapCandidate, } from "./import-wrap.js";
+export { importBindingNames, literalConstNames, type ImportKind, } from "./frontmatter.js";
+export { detectPropWrapTargets, childRendersPropAsText, type FileReader } from "./props.js";
+export { detectPropHoistTargets, hoistPropLiterals, verifyHoistResult, type PropHoistTarget, type HoistProp, type HoistResult, } from "./prop-hoist.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,EACnB,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,aAAa,EAClB,KAAK,SAAS,GACf,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,EACf,KAAK,UAAU,GAChB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,MAAM,EACN,KAAK,SAAS,EACd,KAAK,OAAO,EACZ,KAAK,UAAU,EACf,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,YAAY,EACjB,KAAK,YAAY,GAClB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,EACZ,KAAK,KAAK,EACV,KAAK,WAAW,EAChB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,SAAS,EAAE,KAAK,YAAY,EAAE,KAAK,WAAW,EAAE,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,QAAQ,EACR,KAAK,UAAU,EACf,KAAK,QAAQ,EACb,KAAK,WAAW,GACjB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,SAAS,EACT,qBAAqB,EACrB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,UAAU,EACf,KAAK,UAAU,GAChB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,2BAA2B,EAC3B,KAAK,mBAAmB,GACzB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,EACjB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAE,KAAK,UAAU,EAAE,MAAM,YAAY,CAAC;AAE5F,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,EACjB,KAAK,eAAe,EACpB,KAAK,SAAS,EACd,KAAK,WAAW,GACjB,MAAM,iBAAiB,CAAC"}

package/dist/index.js

@@ -0,0 +1,18 @@
+/**
+ * @caretcms/caretize — public entry.
+ *
+ * v0.1 surfaces the byte-correct splice/parse core plus detection, naming, and
+ * planning. The interactive review loop and the CLI build on top of these.
+ */
+export { parseAstro, walkTags, isTagNode, tagElementAndVerify, } from "./parse.js";
+export { findOpenTagEnd, spliceAttribute, } from "./splice.js";
+export { detect, } from "./detect.js";
+export { deriveScope, assignFields, slugifyText, isValidCollection, isValidId, isValidField, } from "./name.js";
+export { applyTags } from "./write.js";
+export { planFile, } from "./plan.js";
+export { wrapConst, detectWrapTargetsSafe, } from "./wrap.js";
+export { wrapImport, detectImportWrapCandidates, detectImportWrapTargetsSafe, } from "./import-wrap.js";
+export { importBindingNames, literalConstNames, } from "./frontmatter.js";
+export { detectPropWrapTargets, childRendersPropAsText } from "./props.js";
+export { detectPropHoistTargets, hoistPropLiterals, verifyHoistResult, } from "./prop-hoist.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EACL,UAAU,EACV,QAAQ,EACR,SAAS,EACT,mBAAmB,GAKpB,MAAM,YAAY,CAAC;AAEpB,OAAO,EACL,cAAc,EACd,eAAe,GAEhB,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,MAAM,GAQP,MAAM,aAAa,CAAC;AAErB,OAAO,EACL,WAAW,EACX,YAAY,EACZ,WAAW,EACX,iBAAiB,EACjB,SAAS,EACT,YAAY,GAIb,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,SAAS,EAAuC,MAAM,YAAY,CAAC;AAE5E,OAAO,EACL,QAAQ,GAIT,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,SAAS,EACT,qBAAqB,GAKtB,MAAM,WAAW,CAAC;AAEnB,OAAO,EACL,UAAU,EACV,0BAA0B,EAC1B,2BAA2B,GAE5B,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EACL,kBAAkB,EAClB,iBAAiB,GAElB,MAAM,kBAAkB,CAAC;AAE1B,OAAO,EAAE,qBAAqB,EAAE,sBAAsB,EAAmB,MAAM,YAAY,CAAC;AAE5F,OAAO,EACL,sBAAsB,EACtB,iBAAiB,EACjB,iBAAiB,GAIlB,MAAM,iBAAiB,CAAC"}

package/dist/name.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Naming: derive a stable `collection::id` scope from a file path and assign a
+ * unique, valid field name to each candidate.
+ *
+ * The field names a candidate gets are *permanent storage keys* once a user
+ * edits — so naming must be deterministic (same input → same name every run),
+ * seeded from any `data-caret` names already in the file (so re-runs never
+ * reuse a name), unique within a scope (duplicate keys would mirror content at
+ * runtime), and valid against the runtime's parser regexes.
+ */
+import type { Candidate } from "./detect.js";
+export declare const COLLECTION_RE: RegExp;
+export declare const ID_RE: RegExp;
+export declare function isValidCollection(s: string): boolean;
+export declare function isValidId(s: string): boolean;
+export declare function isValidField(s: string): boolean;
+export interface Scope {
+    collection: string;
+    id: string;
+}
+export type ScopeReason = "dynamic-route" | "unsupported-location";
+export type ScopeResult = {
+    scope: Scope;
+} | {
+    skip: ScopeReason;
+};
+/**
+ * Derive the scope for a `.astro` file from its path relative to the project
+ * root (POSIX-style or OS-style accepted). Returns a skip reason for dynamic
+ * routes and locations we don't tag in v1.
+ */
+export declare function deriveScope(relPath: string): ScopeResult;
+/**
+ * Derive a field name from an element's visible text — far more useful to an
+ * editor than `subhead_3` (e.g. "Our Programs 🎨" → `our_programs`). Decodes
+ * the few common HTML entities, strips emoji/accents/punctuation, and keeps the
+ * first few words. Returns null when nothing usable remains (all emoji, leading
+ * digits, etc.), so the caller falls back to a role-based name.
+ */
+export declare function slugifyText(text: string): string | null;
+/**
+ * Assign a unique field name to each candidate, in document order.
+ *
+ * `existingFields` seeds the used-name set with whatever `data-caret` field
+ * names already live in the file's scope, so a partial first run, a manual
+ * edit, or a re-run never collides with an existing binding.
+ */
+export declare function assignFields(candidates: Candidate[], existingFields?: Iterable<string>): Map<Candidate, string>;
+//# sourceMappingURL=name.d.ts.map

package/dist/name.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.d.ts","sourceRoot":"","sources":["../src/name.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAM7C,eAAO,MAAM,aAAa,QAAuB,CAAC;AAClD,eAAO,MAAM,KAAK,QAA0B,CAAC;AAG7C,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAEpD;AACD,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE5C;AACD,wBAAgB,YAAY,CAAC,CAAC,EAAE,MAAM,GAAG,OAAO,CAE/C;AAED,MAAM,WAAW,KAAK;IACpB,UAAU,EAAE,MAAM,CAAC;IACnB,EAAE,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,sBAAsB,CAAC;AAEnE,MAAM,MAAM,WAAW,GACnB;IAAE,KAAK,EAAE,KAAK,CAAA;CAAE,GAChB;IAAE,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAY1B;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,WAAW,CA0BxD;AAKD;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAavD;AAsDD;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,UAAU,EAAE,SAAS,EAAE,EACvB,cAAc,GAAE,QAAQ,CAAC,MAAM,CAAM,GACpC,GAAG,CAAC,SAAS,EAAE,MAAM,CAAC,CAexB"}

package/dist/name.js

@@ -0,0 +1,164 @@
+/**
+ * Naming: derive a stable `collection::id` scope from a file path and assign a
+ * unique, valid field name to each candidate.
+ *
+ * The field names a candidate gets are *permanent storage keys* once a user
+ * edits — so naming must be deterministic (same input → same name every run),
+ * seeded from any `data-caret` names already in the file (so re-runs never
+ * reuse a name), unique within a scope (duplicate keys would mirror content at
+ * runtime), and valid against the runtime's parser regexes.
+ */
+// Mirror the runtime's id-contract regexes exactly (core's
+// runtime/storage/id-contracts.ts) — a label the runtime would reject must
+// never be emitted. caretize deliberately has no dependency on core, so these
+// are copies, held byte-identical by tests/unit/contracts-parity.test.ts.
+export const COLLECTION_RE = /^[a-z][a-z0-9_-]*$/;
+export const ID_RE = /^[a-z0-9][a-z0-9_-]*$/;
+const FIELD_RE = /^[a-z][a-z0-9_]*$/; // generated fields: keep them clean identifiers
+export function isValidCollection(s) {
+    return COLLECTION_RE.test(s);
+}
+export function isValidId(s) {
+    return ID_RE.test(s);
+}
+export function isValidField(s) {
+    return FIELD_RE.test(s);
+}
+/** Convert a PascalCase/camelCase or arbitrary filename to a valid id. */
+function toId(name) {
+    const kebab = name
+        .replace(/([a-z0-9])([A-Z])/g, "$1-$2")
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "");
+    return kebab || "page";
+}
+/**
+ * Derive the scope for a `.astro` file from its path relative to the project
+ * root (POSIX-style or OS-style accepted). Returns a skip reason for dynamic
+ * routes and locations we don't tag in v1.
+ */
+export function deriveScope(relPath) {
+    const parts = relPath.replace(/\\/g, "/").replace(/^\.?\/+/, "").split("/");
+    const srcIdx = parts.indexOf("src");
+    const rel = srcIdx >= 0 ? parts.slice(srcIdx + 1) : parts;
+    const [area, ...rest] = rel;
+    if (rest.length === 0)
+        return { skip: "unsupported-location" };
+    // strip .astro from the final segment
+    rest[rest.length - 1] = rest[rest.length - 1].replace(/\.astro$/i, "");
+    // dynamic route segments like [slug] or [...rest] → no static identity
+    if (rest.some((seg) => /^\[.*\]$/.test(seg)))
+        return { skip: "dynamic-route" };
+    if (area === "pages") {
+        const segs = rest.filter((s) => s !== "index");
+        const id = segs.length === 0 ? "home" : segs.map(toId).join("_");
+        return { scope: { collection: "pages", id } };
+    }
+    if (area === "layouts") {
+        return { scope: { collection: "site", id: toId(rest[rest.length - 1]) } };
+    }
+    if (area === "components") {
+        return { scope: { collection: "components", id: toId(rest[rest.length - 1]) } };
+    }
+    return { skip: "unsupported-location" };
+}
+// Maximum words taken from text content when deriving a field name from it.
+const SLUG_MAX_WORDS = 4;
+/**
+ * Derive a field name from an element's visible text — far more useful to an
+ * editor than `subhead_3` (e.g. "Our Programs 🎨" → `our_programs`). Decodes
+ * the few common HTML entities, strips emoji/accents/punctuation, and keeps the
+ * first few words. Returns null when nothing usable remains (all emoji, leading
+ * digits, etc.), so the caller falls back to a role-based name.
+ */
+export function slugifyText(text) {
+    const decoded = text
+        .replace(/&/g, " and ")
+        .replace(/&(lt|gt|quot|nbsp|#0?39|apos);/g, " ")
+        .replace(/['’]/g, ""); // keep contractions joined: What's → whats
+    const ascii = decoded.normalize("NFKD").replace(/[̀-ͯ]/g, "");
+    const cleaned = ascii.toLowerCase().replace(/[^a-z0-9]+/g, " ").trim();
+    if (!cleaned)
+        return null;
+    const slug = cleaned.split(/\s+/).slice(0, SLUG_MAX_WORDS).join("_");
+    // Field names must start with a letter; if the text led with digits/symbols,
+    // a role-based fallback reads better than a mangled slug.
+    if (!/^[a-z]/.test(slug) || !isValidField(slug))
+        return null;
+    return slug;
+}
+// Role-based field name, used when text isn't sluggable. `seenOfTag` lets the
+// first <p> be "intro", first <img> "hero", etc.
+function roleField(candidate, seenOfTag) {
+    if (candidate.kind === "image")
+        return seenOfTag === 0 ? "hero" : "image";
+    switch (candidate.tag) {
+        case "h1": return "headline";
+        case "h2": return "subhead";
+        case "h3":
+        case "h4":
+        case "h5":
+        case "h6": return "heading";
+        case "p": return seenOfTag === 0 ? "intro" : "body";
+        case "blockquote": return "quote";
+        case "li": return "item";
+        case "a": return "link";
+        case "button": return "button_label";
+        case "figcaption":
+        case "caption": return "caption";
+        case "summary": return "summary";
+        case "dt": return "term";
+        case "dd": return "definition";
+        case "th":
+        case "td": return "cell";
+        case "label": return "label";
+        default: return "text";
+    }
+}
+// Prose elements hold sentences, where a 4-word slug is an awkward fragment
+// ("here_s_what_a"); a role name (intro/body) reads better. Label-like
+// elements (headings, links, buttons, list items…) hold short phrases that
+// slug cleanly ("our_programs"), which is far more useful than "subhead_3".
+const PROSE_TAGS = new Set(["p", "blockquote", "dd"]);
+// Preferred base field name: a content slug for short label-like elements (the
+// editor-friendly default), a role name for prose. Determinism is preserved —
+// the same element always yields the same base.
+function baseField(candidate, seenOfTag) {
+    if (candidate.kind === "text" && !PROSE_TAGS.has(candidate.tag)) {
+        const slug = slugifyText(candidate.text);
+        if (slug)
+            return slug;
+    }
+    return roleField(candidate, seenOfTag);
+}
+function uniquify(base, used) {
+    if (!used.has(base))
+        return base;
+    let i = 2;
+    while (used.has(`${base}_${i}`))
+        i++;
+    return `${base}_${i}`;
+}
+/**
+ * Assign a unique field name to each candidate, in document order.
+ *
+ * `existingFields` seeds the used-name set with whatever `data-caret` field
+ * names already live in the file's scope, so a partial first run, a manual
+ * edit, or a re-run never collides with an existing binding.
+ */
+export function assignFields(candidates, existingFields = []) {
+    const used = new Set(existingFields);
+    const seen = new Map();
+    const result = new Map();
+    for (const c of candidates) {
+        const key = c.kind === "image" ? "img" : c.tag;
+        const seenCount = seen.get(key) ?? 0;
+        seen.set(key, seenCount + 1);
+        const name = uniquify(baseField(c, seenCount), used);
+        used.add(name);
+        result.set(c, name);
+    }
+    return result;
+}
+//# sourceMappingURL=name.js.map

package/dist/name.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"name.js","sourceRoot":"","sources":["../src/name.ts"],"names":[],"mappings":"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"}

package/dist/output.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Output formatting for the caretize CLI — pure functions that turn a plan /
+ * run result into the exact strings the CLI prints. Kept out of cli.ts (and free
+ * of process.stdout) so the formatting is unit-testable in isolation.
+ */
+import type { FilePlan, PlannedTag } from "./plan.js";
+import type { WrapTarget } from "./wrap.js";
+import type { PropHoistTarget } from "./prop-hoist.js";
+import type { CollectionBindTarget } from "./bind-collection.js";
+type BindsByFile = Map<string, CollectionBindTarget[]>;
+/** One-line description of a tag candidate, e.g. `<h1> "Hello"` or `<img> src="…"`. */
+export declare function tagLine(t: PlannedTag): string;
+/** The post-scan tally line. */
+export declare function formatScanSummary(fileCount: number, plans: FilePlan[], wrapsByFile: Map<string, WrapTarget[]>, hoistsByFile: Map<string, PropHoistTarget[]>, bindsByFile?: BindsByFile): string;
+/** The full `--dry-run` plan dump, ending with the "nothing written" footer. */
+export declare function formatPlan(plans: FilePlan[], wrapsByFile: Map<string, WrapTarget[]>, hoistsByFile: Map<string, PropHoistTarget[]>, bindsByFile?: BindsByFile): string;
+/** The closing summary block after a commit. */
+export declare function formatSummary(files: number, changes: number, wrapped: number, hoisted: number, flagged: number, hadBackups: boolean, bound?: number): string;
+/**
+ * The actionable-skips hints — the "why isn't this editable?" answers — so a skip
+ * reads as a checklist item, not a silent omission. Adapts to the flags already
+ * passed: a hint only appears while its unlock flag is off. Returns "" when
+ * there's nothing to say.
+ */
+export declare function formatHints(plans: FilePlan[], rich: boolean, opts?: {
+    bindCollections?: boolean;
+    bindRoutes?: boolean;
+}): string;
+export {};
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,iBAAiB,CAAC;AACvD,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sBAAsB,CAAC;AAEjE,KAAK,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,oBAAoB,EAAE,CAAC,CAAC;AAEvD,uFAAuF;AACvF,wBAAgB,OAAO,CAAC,CAAC,EAAE,UAAU,GAAG,MAAM,CAK7C;AAED,gCAAgC;AAChC,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,QAAQ,EAAE,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EACtC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,EAC5C,WAAW,GAAE,WAAuB,GACnC,MAAM,CASR;AAED,gFAAgF;AAChF,wBAAgB,UAAU,CACxB,KAAK,EAAE,QAAQ,EAAE,EACjB,WAAW,EAAE,GAAG,CAAC,MAAM,EAAE,UAAU,EAAE,CAAC,EACtC,YAAY,EAAE,GAAG,CAAC,MAAM,EAAE,eAAe,EAAE,CAAC,EAC5C,WAAW,GAAE,WAAuB,GACnC,MAAM,CA4BR;AAED,gDAAgD;AAChD,wBAAgB,aAAa,CAC3B,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,UAAU,EAAE,OAAO,EACnB,KAAK,SAAI,GACR,MAAM,CAUR;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,KAAK,EAAE,QAAQ,EAAE,EACjB,IAAI,EAAE,OAAO,EACb,IAAI,GAAE;IAAE,eAAe,CAAC,EAAE,OAAO,CAAC;IAAC,UAAU,CAAC,EAAE,OAAO,CAAA;CAAO,GAC7D,MAAM,CA4BR"}

package/dist/output.js

@@ -0,0 +1,110 @@
+/**
+ * Output formatting for the caretize CLI — pure functions that turn a plan /
+ * run result into the exact strings the CLI prints. Kept out of cli.ts (and free
+ * of process.stdout) so the formatting is unit-testable in isolation.
+ */
+/** One-line description of a tag candidate, e.g. `<h1> "Hello"` or `<img> src="…"`. */
+export function tagLine(t) {
+    const text = t.candidate.text.replace(/\s+/g, " ").slice(0, 50);
+    const what = t.candidate.kind === "image" ? `src="${text}"` : `"${text}"`;
+    const rich = t.candidate.rich ? " [rich]" : "";
+    return `<${t.candidate.tag}>${rich} ${what}`;
+}
+/** The post-scan tally line. */
+export function formatScanSummary(fileCount, plans, wrapsByFile, hoistsByFile, bindsByFile = new Map()) {
+    const candidateTotal = plans.reduce((n, p) => n + p.tags.length, 0);
+    const wrapTotal = [...wrapsByFile.values()].reduce((n, t) => n + t.length, 0);
+    const hoistTotal = [...hoistsByFile.values()].reduce((n, ts) => n + ts.reduce((m, t) => m + t.props.length, 0), 0);
+    const bindTotal = [...bindsByFile.values()].reduce((n, b) => n + b.length, 0);
+    const bindPart = bindTotal ? ` · ${bindTotal} collection binding(s)` : "";
+    return `✓ ${fileCount} .astro files · ${candidateTotal} tag candidate(s) · ${wrapTotal} wrap target(s) · ${hoistTotal} prop(s)${bindPart}\n`;
+}
+/** The full `--dry-run` plan dump, ending with the "nothing written" footer. */
+export function formatPlan(plans, wrapsByFile, hoistsByFile, bindsByFile = new Map()) {
+    let out = "";
+    for (const plan of plans) {
+        const wraps = wrapsByFile.get(plan.relPath) ?? [];
+        const hoists = hoistsByFile.get(plan.relPath) ?? [];
+        const binds = bindsByFile.get(plan.relPath) ?? [];
+        if (plan.tags.length === 0 && plan.flags.length === 0 && wraps.length === 0 && hoists.length === 0 && binds.length === 0)
+            continue;
+        out += `\n${plan.relPath}${plan.scopeSkip ? `  (skipped: ${plan.scopeSkip})` : ""}\n`;
+        for (const t of plan.tags)
+            out += `  + data-caret="${t.binding}"  ${tagLine(t)}\n`;
+        for (const w of wraps) {
+            const via = w.origin === "prop" ? " (via component prop)" : w.origin === "import" ? " (via data import)" : "";
+            const kind = w.origin === "import" ? "import" : "const";
+            out += `  ~ editable("${w.key}")  wrap ${kind} ${w.varName}${via}\n`;
+        }
+        for (const h of hoists) {
+            for (const p of h.props) {
+                out += `  ⤴ editable("${p.key}")  hoist <${h.componentName}> ${p.propName}${p.isRich ? " [rich]" : ""}\n`;
+            }
+        }
+        for (const b of binds) {
+            const id = b.kind === "route" ? "${entry}" : "*";
+            const note = b.kind === "route" ? "current entry" : "per-row collection loop";
+            out += `  ⟳ data-caret  bind <${b.tag}> ${b.collection}::${id}::${b.field}  (${note})\n`;
+        }
+        for (const f of plan.flags)
+            out += `  ⚠ ${f.method}() loop — consider a dynamic collection\n`;
+    }
+    out += "\n(dry run — nothing written)\n";
+    return out;
+}
+/** The closing summary block after a commit. */
+export function formatSummary(files, changes, wrapped, hoisted, flagged, hadBackups, bound = 0) {
+    let out = `\n───────────────────────────────\n`;
+    out += `✓ ${changes} change(s) across ${files} file(s)\n`;
+    if (wrapped)
+        out += `✓ ${wrapped} data array(s) wrapped with editable()\n`;
+    if (hoisted)
+        out += `✓ ${hoisted} component prop(s) hoisted to editable()\n`;
+    if (bound)
+        out += `✓ ${bound} collection field(s) bound to data-caret\n`;
+    if (flagged)
+        out += `⚠ ${flagged} loop(s) flagged → consider dynamic collections\n`;
+    if (hadBackups)
+        out += `⤺ backups in .caret/.caretize-bak/ (caretize --restore to undo)\n`;
+    out += `───────────────────────────────\nNext: npm run dev → open your page → click to edit\n`;
+    return out;
+}
+/**
+ * The actionable-skips hints — the "why isn't this editable?" answers — so a skip
+ * reads as a checklist item, not a silent omission. Adapts to the flags already
+ * passed: a hint only appears while its unlock flag is off. Returns "" when
+ * there's nothing to say.
+ */
+export function formatHints(plans, rich, opts = {}) {
+    let eligible = 0;
+    let styled = 0;
+    let inIterator = 0;
+    for (const p of plans) {
+        for (const s of p.skipped) {
+            if (s.reason === "rich-eligible")
+                eligible++;
+            else if (s.reason === "rich-unsafe-attrs")
+                styled++;
+            else if (s.reason === "inside-iterator")
+                inIterator++;
+        }
+    }
+    const dynamicRoutes = plans.filter((p) => p.scopeSkip === "dynamic-route").length;
+    let out = "";
+    if (eligible && !rich) {
+        out += `\n↪ ${eligible} mixed-content block(s) are sanitizer-safe inline markup — re-run with --rich to make them editable.\n`;
+    }
+    if (styled) {
+        out += `↪ ${styled} block(s) hold inline styling classes the rich-text sanitizer strips on save.\n` +
+            `  Move the styling to CSS (style the semantic tag), or bless the class via\n` +
+            `  caret({ allowedClasses: { tag: ["your-class"] } }) — then they're safe to tag.\n`;
+    }
+    if (inIterator && !opts.bindCollections) {
+        out += `↪ ${inIterator} element(s) render inside collection loops — re-run with --bind-collections to bind them per row.\n`;
+    }
+    if (dynamicRoutes && !opts.bindRoutes) {
+        out += `↪ ${dynamicRoutes} dynamic route(s) skipped — re-run with --bind-routes to bind each detail page to its entry.\n`;
+    }
+    return out;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"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"}