@shrkcrft/generator 0.1.0-alpha.30 → 0.1.0-alpha.31

package/dist/dry-run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../src/dry-run.ts"],"names":[],"mappings":"AAEA,OAAO,EAIL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAW5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CA8Gf"}
+{"version":3,"file":"dry-run.d.ts","sourceRoot":"","sources":["../src/dry-run.ts"],"names":[],"mappings":"AAEA,OAAO,EAKL,KAAK,mBAAmB,EACzB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AAY5D,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,eAAe,CAAC;IACtB,gEAAgE;IAChE,IAAI,EAAE,OAAO,CAAC;CACf;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,mBAAmB,EAC7B,OAAO,EAAE,kBAAkB,GAC1B,aAAa,CAqHf"}

package/dist/dry-run.js

@@ -1,11 +1,12 @@
 import { existsSync, readFileSync } from 'node:fs';
 import { safeResolveTargetPath } from '@shrkcrft/core';
-import { renderTemplate, validateTemplateVariables, } from '@shrkcrft/templates';
+import { renderTemplate, templateRemainderLines, validateTemplateVariables, } from '@shrkcrft/templates';
 import { OverwriteStrategy } from "./overwrite-strategy.js";
 import { FileChangeType } from "./file-change.js";
 import { decideForExisting, summarizeConflicts } from "./conflict-handler.js";
 import { buildNameVariables } from "./naming-strategy.js";
 import { evaluatePlannedChange, } from "./planned-change.js";
+import { describeInvalidPlannedOperation, validatePlannedOperation } from "./planned-operation-fields.js";
 export function planGeneration(template, request) {
     const warnings = [];
     const overwriteStrategy = request.overwriteStrategy ?? OverwriteStrategy.Never;
@@ -24,6 +25,7 @@ export function planGeneration(template, request) {
                 hasConflicts: false,
                 warnings,
                 postGenerationNotes: template.postGenerationNotes ?? [],
+                remainderLines: templateRemainderLines(template),
             },
             safe: false,
         };
@@ -90,10 +92,15 @@ export function planGeneration(template, request) {
     }
     // 2) v2 planned changes — evaluate against the live filesystem, threaded
     //    through the overlay so successive changes to one file compose.
-    for (const tplChange of rendered.changes) {
-        const evaluated = planOne(tplChange, request.projectRoot, overlay);
+    //    Each op is shape-checked against PLANNED_OPERATION_FIELDS first, so a
+    //    misspelled op becomes a located Conflict instead of a TypeError.
+    rendered.changes.forEach((tplChange, index) => {
+        const evaluated = planOne(tplChange, request.projectRoot, overlay, {
+            where: `template '${template.id}' change[${index}]`,
+            warnings,
+        });
         changes.push(evaluated);
-    }
+    });
     const { hasConflicts } = summarizeConflicts(changes);
     return {
         plan: {
@@ -104,12 +111,32 @@ export function planGeneration(template, request) {
             hasConflicts,
             warnings,
             postGenerationNotes: rendered.postGenerationNotes,
+            remainderLines: templateRemainderLines(template),
         },
         safe: !hasConflicts && changes.length > 0,
     };
 }
-function planOne(tplChange, projectRoot, overlay) {
+function planOne(tplChange, projectRoot, overlay, ctx) {
     const op = tplChange.operation;
+    const where = ctx?.where ?? 'change';
+    const shape = validatePlannedOperation(op);
+    const rawTarget = typeof tplChange.targetPath === 'string' ? tplChange.targetPath : '';
+    const invalid = describeInvalidPlannedOperation(shape, where) ??
+        (rawTarget.length === 0 ? `${where} (${shape.kind}): missing targetPath` : undefined);
+    if (invalid) {
+        return {
+            type: FileChangeType.Conflict,
+            absolutePath: rawTarget,
+            relativePath: rawTarget,
+            contents: '',
+            reason: invalid,
+            sizeBytes: 0,
+            operation: op,
+        };
+    }
+    if (shape.unknown.length > 0) {
+        ctx?.warnings.push(`${where} (${shape.kind}): unknown key(s) ${shape.unknown.join(', ')} are ignored by the engine`);
+    }
     let safe;
     try {
         safe = safeResolveTargetPath(tplChange.targetPath, projectRoot);
@@ -138,12 +165,28 @@ function planOne(tplChange, projectRoot, overlay) {
         : existsSync(safe.absolutePath)
             ? readFileSafe(safe.absolutePath)
             : null;
-    const result = evaluatePlannedChange({
-        change,
-        absolutePath: safe.absolutePath,
-        relativePath: safe.relativePath,
-        existing,
-    });
+    let result;
+    try {
+        result = evaluatePlannedChange({
+            change,
+            absolutePath: safe.absolutePath,
+            relativePath: safe.relativePath,
+            existing,
+        });
+    }
+    catch (e) {
+        // A well-shaped op can still carry a wrong-typed value; the plan must name
+        // the change, never surface a bare TypeError.
+        return {
+            type: FileChangeType.Conflict,
+            absolutePath: safe.absolutePath,
+            relativePath: safe.relativePath,
+            contents: existing ?? '',
+            reason: `${where} (${shape.kind}): could not be evaluated — ${e.message}`,
+            sizeBytes: 0,
+            operation: op,
+        };
+    }
     // Record the cumulative content (Skip/Conflict carry the unchanged bytes,
     // which is exactly what a later op on the same file should see).
     overlay?.set(safe.absolutePath, result.contents);

package/dist/generation-plan.d.ts

@@ -8,6 +8,13 @@ export interface IGenerationPlan {
     hasConflicts: boolean;
     warnings: readonly string[];
     postGenerationNotes: readonly string[];
+    /**
+     * The template's declared remainder — what it deliberately does NOT
+     * scaffold, and the manual steps that cover it — as the printable lines
+     * `templateRemainderLines` renders (`@shrkcrft/templates`). Absent/empty
+     * when the template declares neither `notScaffolded` nor `manualSteps`.
+     */
+    remainderLines?: readonly string[];
     /**
      * Optional folder operations attached to the plan. Carried verbatim
      * into saved plans and executed via `applyFolderOps()` during `shrk apply`

package/dist/generation-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"generation-plan.d.ts","sourceRoot":"","sources":["../src/generation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB"}
+{"version":3,"file":"generation-plan.d.ts","sourceRoot":"","sources":["../src/generation-plan.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,OAAO,EAAE,SAAS,WAAW,EAAE,CAAC;IAChC,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,OAAO,CAAC;IACtB,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,mBAAmB,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAC3C;AAED,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB"}

package/dist/index.d.ts

@@ -9,6 +9,7 @@ export * from './naming-strategy.js';
 export * from './saved-plan.js';
 export * from './plan-signing.js';
 export * from './planned-change.js';
+export * from './planned-operation-fields.js';
 export * from './folder-safety.js';
 export * from './folder-apply.js';
 export * from './synthetic-plan.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,yBAAyB,CAAC;AACxC,cAAc,sBAAsB,CAAC;AACrC,cAAc,kBAAkB,CAAC;AACjC,cAAc,uBAAuB,CAAC;AACtC,cAAc,cAAc,CAAC;AAC7B,cAAc,yBAAyB,CAAC;AACxC,cAAc,uBAAuB,CAAC;AACtC,cAAc,sBAAsB,CAAC;AACrC,cAAc,iBAAiB,CAAC;AAChC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,+BAA+B,CAAC;AAC9C,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,qBAAqB,CAAC;AACpC,cAAc,4BAA4B,CAAC;AAC3C,cAAc,iBAAiB,CAAC;AAChC,cAAc,sBAAsB,CAAC"}

package/dist/index.js

@@ -9,6 +9,7 @@ export * from "./naming-strategy.js";
 export * from "./saved-plan.js";
 export * from "./plan-signing.js";
 export * from "./planned-change.js";
+export * from "./planned-operation-fields.js";
 export * from "./folder-safety.js";
 export * from "./folder-apply.js";
 export * from "./synthetic-plan.js";

package/dist/planned-operation-fields.d.ts

@@ -0,0 +1,71 @@
+export declare const PLANNED_OPERATION_FIELDS: {
+    readonly create: {
+        readonly required: readonly ["content"];
+        readonly optional: readonly ["description"];
+    };
+    readonly append: {
+        readonly required: readonly ["snippet"];
+        readonly optional: readonly ["ifMissing", "description"];
+    };
+    readonly 'insert-after': {
+        readonly required: readonly ["anchor", "snippet"];
+        readonly optional: readonly ["ifMissing", "description"];
+    };
+    readonly 'insert-before': {
+        readonly required: readonly ["anchor", "snippet"];
+        readonly optional: readonly ["ifMissing", "description"];
+    };
+    readonly replace: {
+        readonly required: readonly ["find", "replaceWith"];
+        readonly optional: readonly ["expectMatches", "description"];
+    };
+    readonly export: {
+        readonly required: readonly ["from"];
+        readonly optional: readonly ["symbols", "ifMissing", "description"];
+    };
+    readonly 'ensure-import': {
+        readonly required: readonly ["from"];
+        readonly optional: readonly ["symbols", "typeOnly", "defaultBinding", "namespaceBinding", "description"];
+    };
+    readonly 'insert-enum-entry': {
+        readonly required: readonly ["enumName", "entryName", "entryValue"];
+        readonly optional: readonly ["description"];
+    };
+    readonly 'insert-object-entry': {
+        readonly required: readonly ["objectName", "entryKey", "entryValue"];
+        readonly optional: readonly ["shorthand", "description"];
+    };
+    readonly 'insert-array-entry': {
+        readonly required: readonly ["arrayName", "entryValue"];
+        readonly optional: readonly ["arrayNameAlternatives", "manualStepInstruction", "ifMissing", "description"];
+    };
+    readonly 'insert-before-closing-brace': {
+        readonly required: readonly ["containerName", "snippet"];
+        readonly optional: readonly ["ifMissing", "description"];
+    };
+    readonly 'insert-between-anchors': {
+        readonly required: readonly ["beginAnchor", "endAnchor", "snippet"];
+        readonly optional: readonly ["ifMissing", "description"];
+    };
+};
+/**
+ * Check one rendered op against the table. `kindKnown: false` means the kind is
+ * not a planned-operation kind at all; `missing` lists required fields that are
+ * absent; `unknown` lists keys the evaluator would silently drop; `suggestions`
+ * pairs an unknown key with the missing field it most likely meant
+ * (`value→entryValue`).
+ */
+export declare function validatePlannedOperation(op: unknown): {
+    readonly kindKnown: boolean;
+    readonly kind: string;
+    readonly missing: readonly string[];
+    readonly unknown: readonly string[];
+    readonly suggestions: readonly string[];
+};
+/**
+ * One sentence naming what is wrong with an op, or `undefined` when the op is
+ * well-formed (unknown extra keys alone are reported by the caller as a
+ * warning, not here).
+ */
+export declare function describeInvalidPlannedOperation(shape: ReturnType<typeof validatePlannedOperation>, where: string): string | undefined;
+//# sourceMappingURL=planned-operation-fields.d.ts.map

package/dist/planned-operation-fields.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planned-operation-fields.d.ts","sourceRoot":"","sources":["../src/planned-operation-fields.ts"],"names":[],"mappings":"AAcA,eAAO,MAAM,wBAAwB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CA+BpC,CAAC;AA2BF;;;;;;GAMG;AACH,wBAAgB,wBAAwB,CAAC,EAAE,EAAE,OAAO,GAAG;IACrD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;IACpC,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;CACzC,CAuBA;AAED;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,KAAK,EAAE,UAAU,CAAC,OAAO,wBAAwB,CAAC,EAClD,KAAK,EAAE,MAAM,GACZ,MAAM,GAAG,SAAS,CASpB"}

package/dist/planned-operation-fields.js

@@ -0,0 +1,100 @@
+export const PLANNED_OPERATION_FIELDS = {
+    create: { required: ['content'], optional: ['description'] },
+    append: { required: ['snippet'], optional: ['ifMissing', 'description'] },
+    'insert-after': { required: ['anchor', 'snippet'], optional: ['ifMissing', 'description'] },
+    'insert-before': { required: ['anchor', 'snippet'], optional: ['ifMissing', 'description'] },
+    replace: { required: ['find', 'replaceWith'], optional: ['expectMatches', 'description'] },
+    export: { required: ['from'], optional: ['symbols', 'ifMissing', 'description'] },
+    'ensure-import': {
+        required: ['from'],
+        optional: ['symbols', 'typeOnly', 'defaultBinding', 'namespaceBinding', 'description'],
+    },
+    'insert-enum-entry': { required: ['enumName', 'entryName', 'entryValue'], optional: ['description'] },
+    'insert-object-entry': {
+        required: ['objectName', 'entryKey', 'entryValue'],
+        optional: ['shorthand', 'description'],
+    },
+    'insert-array-entry': {
+        required: ['arrayName', 'entryValue'],
+        optional: ['arrayNameAlternatives', 'manualStepInstruction', 'ifMissing', 'description'],
+    },
+    'insert-before-closing-brace': {
+        required: ['containerName', 'snippet'],
+        optional: ['ifMissing', 'description'],
+    },
+    'insert-between-anchors': {
+        required: ['beginAnchor', 'endAnchor', 'snippet'],
+        optional: ['ifMissing', 'description'],
+    },
+};
+/** Explicit near-misses authors write for a required field. */
+const NEAR_MISS = {
+    key: ['entryKey'],
+    value: ['entryValue', 'snippet', 'content'],
+    name: ['entryName', 'arrayName', 'objectName', 'enumName', 'containerName'],
+    body: ['content', 'snippet'],
+    text: ['snippet', 'content'],
+    code: ['snippet', 'content'],
+    snippet: ['content'],
+    content: ['snippet'],
+    replace: ['replaceWith'],
+    with: ['replaceWith'],
+    search: ['find'],
+    pattern: ['find'],
+    begin: ['beginAnchor'],
+    end: ['endAnchor'],
+    target: ['arrayName', 'objectName', 'enumName', 'containerName'],
+};
+function isPresent(value) {
+    if (value === undefined || value === null)
+        return false;
+    if (typeof value === 'string')
+        return true;
+    return true;
+}
+/**
+ * Check one rendered op against the table. `kindKnown: false` means the kind is
+ * not a planned-operation kind at all; `missing` lists required fields that are
+ * absent; `unknown` lists keys the evaluator would silently drop; `suggestions`
+ * pairs an unknown key with the missing field it most likely meant
+ * (`value→entryValue`).
+ */
+export function validatePlannedOperation(op) {
+    if (!op || typeof op !== 'object') {
+        return { kindKnown: false, kind: String(op), missing: [], unknown: [], suggestions: [] };
+    }
+    const record = op;
+    const kind = typeof record.kind === 'string' ? record.kind : String(record.kind);
+    const spec = PLANNED_OPERATION_FIELDS[kind];
+    if (!spec)
+        return { kindKnown: false, kind, missing: [], unknown: [], suggestions: [] };
+    const missing = spec.required.filter((f) => !isPresent(record[f]));
+    const allowed = new Set(['kind', ...spec.required, ...spec.optional]);
+    const unknown = Object.keys(record).filter((k) => !allowed.has(k));
+    const suggestions = [];
+    for (const u of unknown) {
+        const explicit = (NEAR_MISS[u.toLowerCase()] ?? []).filter((f) => missing.includes(f));
+        const contained = missing.filter((f) => !explicit.includes(f) && f.toLowerCase().includes(u.toLowerCase()) && u.length >= 3);
+        const target = explicit[0] ?? contained[0];
+        if (target)
+            suggestions.push(`${u}→${target}`);
+    }
+    return { kindKnown: true, kind, missing, unknown, suggestions };
+}
+/**
+ * One sentence naming what is wrong with an op, or `undefined` when the op is
+ * well-formed (unknown extra keys alone are reported by the caller as a
+ * warning, not here).
+ */
+export function describeInvalidPlannedOperation(shape, where) {
+    if (!shape.kindKnown) {
+        return `${where}: unknown operation kind "${shape.kind}" — must be one of ${Object.keys(PLANNED_OPERATION_FIELDS).join(', ')}`;
+    }
+    if (shape.missing.length === 0)
+        return undefined;
+    const parts = [`missing required ${shape.missing.join(', ')}`];
+    if (shape.unknown.length > 0)
+        parts.push(`unknown keys ${shape.unknown.join(', ')}`);
+    const hint = shape.suggestions.length > 0 ? ` — did you mean ${shape.suggestions.join(', ')}?` : '';
+    return `${where} (${shape.kind}): ${parts.join('; ')}${hint}`;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shrkcrft/generator",
-  "version": "0.1.0-alpha.30",
+  "version": "0.1.0-alpha.31",
   "description": "SharkCraft plan-first generator: GenerationPlan, FileChange, dry-run, safe writes.",
   "license": "MIT",
   "author": "SharkCraft contributors",
@@ -43,10 +43,10 @@
     "typecheck": "tsc --noEmit -p tsconfig.json"
   },
   "dependencies": {
-    "@shrkcrft/core": "^0.1.0-alpha.30",
-    "@shrkcrft/templates": "^0.1.0-alpha.30",
-    "@shrkcrft/rules": "^0.1.0-alpha.30",
-    "@shrkcrft/paths": "^0.1.0-alpha.30"
+    "@shrkcrft/core": "^0.1.0-alpha.31",
+    "@shrkcrft/templates": "^0.1.0-alpha.31",
+    "@shrkcrft/rules": "^0.1.0-alpha.31",
+    "@shrkcrft/paths": "^0.1.0-alpha.31"
   },
   "publishConfig": {
     "access": "public"