@knitting-tools/core 2.0.0

package/README.md

@@ -0,0 +1,76 @@
+# @knitting-tools/core
+
+A knitting pattern engine for expanding rows, applying shaping, and compiling pattern DSL.
+
+## What it includes
+
+- Expand repeat-based row definitions
+- Evenly distribute increases/decreases
+- Apply physical shaping to stitch streams
+- Compile simple knitting DSL
+
+## Install
+
+```bash
+pnpm add @knitting-tools/core
+```
+
+## Quick example
+
+```ts
+import {
+  compilePattern,
+  compileRowDsl,
+  parseRowDsl,
+  rowToRowDsl,
+} from "@knitting-tools/core";
+
+const row = parseRowDsl("[k1]s (k2 p2) p1 [k1]e");
+const normalised = rowToRowDsl(row);
+const stitches = compileRowDsl(normalised, 10);
+
+const compiled = compilePattern(
+  {
+    rows: [row],
+  },
+  10
+);
+
+console.log(stitches.length);
+console.log(compiled.rows[0].normalisedRowDsl);
+```
+
+## Development
+
+Run from the repository root:
+
+```bash
+pnpm --dir packages/knitting-math typecheck
+pnpm --dir packages/knitting-math test
+pnpm --dir packages/knitting-math test:coverage
+pnpm --dir packages/knitting-math check
+```
+
+## API Stability & Breaking Changes
+
+This package follows [Semantic Versioning](https://semver.org/). The public API surface is locked in with snapshot tests. Any change to exports, types, or function signatures will cause tests to fail, ensuring breaking changes are intentional and documented.
+
+**Quick links:**
+- [API Compatibility Policy](./API_COMPATIBILITY.md) — Detailed policy on versioning and breaking changes
+- [API Quick Reference](./API_COMPATIBILITY_QUICK_REF.md) — Commands and workflows for development
+- [Test Snapshots](./src/__snapshots__/api.compatibility.test.ts.snap) — Current API surface
+
+**Key principle**: Breaking changes require a major version bump and must be documented in Changesets before release.
+
+## Release flow
+
+Package releases are managed with Changesets from the repository root:
+
+```bash
+pnpm changeset
+pnpm release:status
+pnpm release:version
+pnpm release:publish
+```
+
+See the repository README for the wider monorepo workflow.

package/dist/index.d.ts

@@ -0,0 +1,480 @@
+declare const INCH_TO_CM: number;
+declare const CM_TO_INCH: number;
+declare const MM_TO_CM: number;
+declare const CM_TO_MM: number;
+
+type UnitSystem = "imperial" | "metric";
+interface MetricGauge {
+    rowsPer10cm: number;
+    stitchesPer10cm: number;
+    unit: "metric";
+}
+interface ImperialGauge {
+    rowsPer4in: number;
+    stitchesPer4in: number;
+    unit: "imperial";
+}
+type Gauge = MetricGauge | ImperialGauge;
+/**
+ * Get the number of stitches per centimeter based on the gauge.
+ *
+ * @param gauge - The gauge information.
+ * @returns The number of stitches per centimeter.
+ */
+declare function stitchesPerCm(gauge: Gauge): number;
+/**
+ * Get the number of rows per centimeter based on the gauge.
+ *
+ * @param gauge - The gauge information.
+ * @returns The number of rows per centimeter.
+ */
+declare function rowsPerCm(gauge: Gauge): number;
+
+/**
+ * Convert a centimetre measurement into a rounded stitch count for the given gauge.
+ *
+ * @param cm - The measurement in centimetres.
+ * @param gauge - The gauge definition used for conversion.
+ * @returns The nearest whole-number stitch count.
+ */
+declare function cmToStitches(cm: number, gauge: Gauge): number;
+/**
+ * Convert a centimetre measurement into a rounded row count for the given gauge.
+ *
+ * @param cm - The measurement in centimetres.
+ * @param gauge - The gauge definition used for conversion.
+ * @returns The nearest whole-number row count.
+ */
+declare function cmToRows(cm: number, gauge: Gauge): number;
+
+/**
+ * Convert a length value between centimeters and inches.
+ *
+ * @param value - The length value to convert.
+ * @param from - The unit of the input value ("cm" or "in").
+ * @param to - The unit to convert to ("cm" or "in").
+ * @returns The converted length value.
+ */
+declare function convertLength(value: number, from: "cm" | "in", to: "cm" | "in"): number;
+/**
+ * Normalise a length measurement to centimeters.
+ *
+ * @param value - The length value to normalise.
+ * @param unit - The unit of the input value ("cm" or "in").
+ * @returns The normalised length value in centimeters.
+ */
+declare function normaliseMeasurement(value: number, unit: "cm" | "in"): number;
+/**
+ * Round a number of stitches to the nearest whole number.
+ *
+ * @param stitches - The number of stitches to round.
+ * @returns The rounded number of stitches.
+ */
+declare function roundStitches(stitches: number): number;
+
+type StitchType = "knit" | "purl" | "decrease" | "increase";
+type StitchVariant = "inv-l" | "inv-r" | "k1-b" | "k2tog" | "kfb" | "kfbf" | "m1" | "p1-b" | "p2tog" | "pfb" | "psso" | "s2kp" | "sk2p" | "skp" | "sl" | "sl1" | "slip" | "ssp" | "ssk" | "tbl" | "yfon" | "yfrn" | "yo" | "yon" | "yrn";
+type StitchVariantParameterValue = boolean | number | string;
+type StitchVariantParameters = Record<string, StitchVariantParameterValue>;
+interface ShapingElement {
+    count: number;
+    direction?: "centre" | "left" | "right";
+    shapingType: "decrease" | "increase";
+    /**
+     * The ground stitch type this shaping operates on.
+     * When provided, `createInstructionFromShaping` may infer purl-side variants
+     * (e.g. `p2tog`, `ssp`) rather than defaulting to knit-side variants.
+     */
+    stitch?: "knit" | "purl";
+    type: "shaping";
+    variant?: StitchVariant;
+    variantParameters?: StitchVariantParameters;
+}
+type EdgeElement = ShapingElement | StitchInstruction;
+type RowElement = ShapingElement | StitchInstruction | RepeatBlock;
+interface StitchInstruction {
+    count: number;
+    type: StitchType;
+    variant?: StitchVariant;
+    variantParameters?: StitchVariantParameters;
+}
+type RepeatBlock = {
+    allowPartial?: never;
+    maxRepeats?: never;
+    remainingStitches?: never;
+    sequence: RowElement[];
+    times: number;
+    toEnd?: never;
+    targetStitches?: never;
+    type: "repeat";
+} | {
+    allowPartial?: boolean;
+    maxRepeats?: number;
+    remainingStitches?: never;
+    sequence: RowElement[];
+    times?: never;
+    toEnd: true;
+    targetStitches?: never;
+    type: "repeat";
+} | {
+    allowPartial?: never;
+    maxRepeats?: number;
+    remainingStitches?: never;
+    sequence: RowElement[];
+    times?: never;
+    toEnd?: never;
+    targetStitches: number;
+    type: "repeat";
+} | {
+    allowPartial?: never;
+    maxRepeats?: number;
+    remainingStitches: number;
+    sequence: RowElement[];
+    times?: never;
+    toEnd?: never;
+    targetStitches?: never;
+    type: "repeat";
+};
+interface Row {
+    edgeEnd?: EdgeElement[];
+    edgeStart?: EdgeElement[];
+    elements: RowElement[];
+}
+/**
+ * Expand a row into a full list of stitch instructions based on the total number of stitches.
+ *
+ * Internal contract (lightweight):
+ * - never mutates input
+ * - never consumes more source stitches than totalStitches
+ * - deterministic output for identical inputs
+ * - throws on invalid structure
+ *
+ * @param row - The row to expand.
+ * @param totalStitches - The total number of stitches in the row.
+ * @returns An array of stitch instructions representing the expanded row.
+ */
+declare function expandRow(row: Row, totalStitches: number): StitchInstruction[];
+/**
+ * Expand a row into a full list of stitch instructions based on the total number of stitches,
+ * then compress consecutive stitches of the same type into single instructions with counts.
+ *
+ * @param row - The row to expand and compress.
+ * @param totalStitches - The total number of stitches in the row.
+ * @returns An array of stitch instructions representing the expanded and compressed row.
+ */
+declare function expandRowToStitches(row: Row, totalStitches: number): StitchInstruction[];
+/**
+ * Count the total number of stitches represented by compressed stitch instructions.
+ *
+ * @param instructions - Instructions to total.
+ * @returns The summed stitch count.
+ */
+declare function countStitchesInInstructions(instructions: ReadonlyArray<Pick<StitchInstruction, "count">>): number;
+/**
+ * Expand a row into a full list of stitch types based on the total number of stitches.
+ *
+ * @param row - The row to expand.
+ * @param totalStitches - The total number of stitches in the row.
+ * @returns An array of stitch types representing the expanded row.
+ */
+declare function expandRowToStitchTypes(row: Row, totalStitches: number): StitchType[];
+
+/**
+ * Pattern interface with optional row repeats.
+ */
+interface Pattern {
+    repeatRows?: number;
+    rows: Row[];
+}
+/**
+ * Result of expanding a single row when shaping is involved.
+ */
+interface ShapedRowResult {
+    outputStitches: number;
+    stitches: StitchInstruction[];
+}
+type PatternCompileMode = "fixed" | "shaped";
+interface CompilePatternOptions {
+    mode?: PatternCompileMode;
+}
+interface RowShapingOperation {
+    count: number;
+    direction?: "centre" | "left" | "right";
+    shapingType: "decrease" | "increase";
+    variant?: StitchVariant;
+}
+interface CompiledPatternRow {
+    carriedStitches: number;
+    hasShaping: boolean;
+    inputStitches: number;
+    normalisedRowDsl: string;
+    outputStitches: number;
+    repeatIndex: number;
+    rowNumber: number;
+    shapingOperations: RowShapingOperation[];
+    sourceRowIndex: number;
+    stitchDelta: number;
+    stitches: StitchInstruction[];
+}
+interface CompiledPattern {
+    finalStitches: number;
+    initialStitches: number;
+    mode: PatternCompileMode;
+    rows: CompiledPatternRow[];
+}
+/**
+ * Example helper: create a repeat block row
+ */
+declare function createRepeatRow(sequence: Row["elements"], times: number): Row;
+
+declare function compilePattern(pattern: Pattern, initialStitches: number, options?: CompilePatternOptions): CompiledPattern;
+declare function expandPattern(pattern: Pattern, stitchesPerRow: number): StitchInstruction[][];
+declare function shapedExpandPattern(pattern: Pattern, initialStitches: number): StitchInstruction[][];
+declare function printPattern(pattern: Pattern, stitchesPerRow: number): void;
+
+type KnittingStyle = "flat" | "in-the-round";
+type LengthUnit = "cm" | "in";
+interface CastOnInput {
+    ease?: number;
+    easeUnit?: LengthUnit;
+    gauge: Gauge;
+    size: number;
+    style: KnittingStyle;
+    unit: LengthUnit;
+}
+/**
+ * Calculate the number of stitches to cast on based on the size and gauge.
+ *
+ * @param input - The input parameters for the cast-on calculation.
+ * @returns The number of stitches to cast on.
+ */
+declare function calculateCastOn(input: CastOnInput): number;
+/**
+ * Calculate the number of stitches to cast on based on the size, gauge, and ease.
+ *
+ * @param input - The input parameters for the cast-on calculation.
+ * @returns The number of stitches to cast on.
+ */
+declare function calculateCastOnStitches(input: CastOnInput): number;
+
+type KnittingMathErrorCode = "EXPANSION_ERROR" | "PARSE_ERROR" | "VALIDATION_ERROR";
+interface KnittingMathErrorContext {
+    [key: string]: boolean | number | string | undefined;
+}
+declare abstract class KnittingMathError extends Error {
+    readonly code: KnittingMathErrorCode;
+    readonly context?: KnittingMathErrorContext;
+    protected constructor(name: string, code: KnittingMathErrorCode, message: string, context?: KnittingMathErrorContext, cause?: unknown);
+}
+declare class KnittingMathParseError extends KnittingMathError {
+    constructor(message: string, context?: KnittingMathErrorContext, cause?: unknown);
+}
+declare class KnittingMathValidationError extends KnittingMathError {
+    constructor(message: string, context?: KnittingMathErrorContext, cause?: unknown);
+}
+declare class KnittingMathExpansionError extends KnittingMathError {
+    constructor(message: string, context?: KnittingMathErrorContext, cause?: unknown);
+}
+declare function ensureKnittingMathError<TError extends KnittingMathError>(error: unknown, createError: (message: string, cause?: unknown) => TError): TError;
+
+interface ResolveOptions {
+    /**
+     * When true, unknown tokens throw a descriptive error instead of returning null.
+     */
+    throwOnUnknown?: boolean;
+}
+interface StitchRegistry {
+    /**
+     * Get the default count for a variant, or 1 if not registered.
+     */
+    getDefaultCount(variant: string): number;
+    /**
+     * Check if a token is registered.
+     */
+    isKnown(token: string): boolean;
+    /**
+     * Check if a variant locks its count.
+     */
+    isLockedCountVariant(variant: string): boolean;
+    /**
+     * Check if a token is specifically a variant abbreviation (not a type alias).
+     */
+    isVariant(token: string): boolean;
+    /**
+     * Register a stitch abbreviation (short-form variant token).
+     * Example: registerAbbreviation("yo", "increase")
+     */
+    registerAbbreviation(abbreviation: string, canonicalType: StitchType): void;
+    /**
+     * Register a stitch variant with default count.
+     * Example: registerDefaultCount("k1b", 1)
+     */
+    registerDefaultCount(variant: string, count: number): void;
+    /**
+     * Register a variant that locks its count (rejects explicit count suffix).
+     * Example: registerLockedCountVariant("k1b")
+     */
+    registerLockedCountVariant(variant: string): void;
+    /**
+     * Register a stitch type alias (long form).
+     * Example: registerType("knit", "k")
+     */
+    registerType(alias: string, canonicalType: StitchType): void;
+    /**
+     * Resolve a token to its canonical stitch type.
+     * Returns null if unknown, unless `options.throwOnUnknown` is true.
+     * In strict mode the error includes the expected `KnittingPattern::StitchType`
+     * tokens and registered abbreviations known to the registry.
+     */
+    resolve(token: string, options?: ResolveOptions): StitchType | null;
+}
+/**
+ * Create a default registry pre-populated with standard stitches.
+ */
+declare function createDefaultStitchRegistry(): StitchRegistry;
+/**
+ * Create an empty registry for testing.
+ * Useful for unit tests that want full control over available stitches.
+ */
+declare function createEmptyStitchRegistry(): StitchRegistry;
+
+interface RowDslAstEdgeStartElement {
+    stitches: EdgeElement[];
+    type: "edge-start";
+}
+interface RowDslAstBodyElement {
+    elements: RowElement[];
+    type: "body";
+}
+interface RowDslAstEdgeEndElement {
+    stitches: EdgeElement[];
+    type: "edge-end";
+}
+type RowDslAstElement = RowDslAstEdgeStartElement | RowDslAstBodyElement | RowDslAstEdgeEndElement;
+interface RowDslAst {
+    elements: RowDslAstElement[];
+}
+/**
+ * Non-throwing structural check for AST shape constraints.
+ *
+ * This helper only validates AST shape invariants:
+ * exactly one body node, and at most one edge-start/edge-end node.
+ * It does not perform semantic validation of row contents.
+ */
+declare function isRowDslAstWellFormed(ast: RowDslAst): boolean;
+
+declare function parseRowDsl(input: string, registry?: StitchRegistry): Row;
+declare function parseCompatibleRowDsl(input: string, registry?: StitchRegistry): Row;
+declare function compileRowDsl(input: string, totalStitches: number, registry?: StitchRegistry): StitchInstruction[];
+declare function compileCompatibleRowDsl(input: string, totalStitches: number, registry?: StitchRegistry): StitchInstruction[];
+declare function rowToRowDsl(row: Row): string;
+declare function parseRowDslAst(input: string, registry?: StitchRegistry): RowDslAst;
+declare function parseCompatibleRowDslAst(input: string, registry?: StitchRegistry): RowDslAst;
+declare function resolveRowDslAst(ast: RowDslAst): Row;
+
+type ShapingType = "decrease" | "increase";
+
+interface ShapeRowInput {
+    row: Row;
+    shaping: {
+        type: ShapingType;
+        count: number;
+    };
+    totalStitches: number;
+}
+interface ShapedStitch {
+    isShaping?: boolean;
+    operationIndex?: number;
+    shapingType?: ShapingType;
+    sourceIndex: number;
+    type: StitchType;
+}
+interface ShapeRowResult {
+    shapedStitches: ShapedStitch[];
+    stitches: StitchInstruction[];
+    totalStitches: number;
+}
+interface ShapingOperationGroup {
+    operationIndex: number;
+    outputIndices: number[];
+    shapingType: ShapingType;
+    sourceIndices: number[];
+    stitches: ShapedStitch[];
+}
+
+type ShapingDslParseResult = ShapeRowInput;
+type ShapingDslElement = {
+    row: Row;
+    type: "row";
+} | {
+    shapingCount: number;
+    shapingType: ShapingType;
+    type: "shaping";
+} | {
+    totalStitches: number;
+    type: "total";
+};
+interface ShapingDslAst {
+    elements: ShapingDslElement[];
+}
+
+interface ShapingDebugLine {
+    legend: string;
+    markers: string;
+    row: string;
+}
+interface ShapingDebugOptions {
+    /**
+     * Width of each stitch cell in characters.
+     * Defaults to 1.
+     */
+    cellWidth?: number;
+    /**
+     * Symbol rendered in the marker line beneath a shaping operation.
+     * Defaults to "^".
+     */
+    markerSymbol?: string;
+    /**
+     * Override symbols for each stitch type in the row line.
+     * Merged with the default symbol map.
+     */
+    symbols?: Partial<Record<ShapingType | "knit" | "purl", string>>;
+}
+/**
+ * Render a shaped stitch stream into a pair of diagnostic strings that make
+ * shaping placement visible at a glance.
+ *
+ * Output has three parts:
+ *  - `row`:     one character (or cell) per output stitch, e.g. `K K \ K K \ K K`
+ *  - `markers`: `^` beneath each shaping stitch to show exact positions
+ *  - `legend`:  a concise key listing each marker's meaning
+ *
+ * @param shapedStitches - Stitch stream from `shapeRow`.
+ * @param options - Optional rendering overrides.
+ * @returns An object with `row`, `markers`, and `legend` strings.
+ */
+declare function renderShapingDebug(shapedStitches: ShapedStitch[], options?: ShapingDebugOptions): ShapingDebugLine;
+/**
+ * Convenience wrapper that shapes a row and renders debug output in one step.
+ *
+ * @param input - Standard shapeRow input.
+ * @param options - Optional rendering overrides.
+ * @returns Rendered debug line data.
+ */
+declare function renderShapingDebugForInput(input: ShapeRowInput, options?: ShapingDebugOptions): ShapingDebugLine;
+/**
+ * Print a shaping debug diagram to the console.
+ *
+ * @param shapedStitches - Stitch stream from `shapeRow`.
+ * @param label - Optional row label printed above the diagram.
+ * @param options - Optional rendering overrides.
+ */
+declare function printShapingDebug(shapedStitches: ShapedStitch[], label?: string, options?: ShapingDebugOptions): void;
+
+declare function parseShapingDslAst(input: string): ShapingDslAst;
+declare function parseShapingDsl(input: string): ShapingDslParseResult;
+declare function compileShapingDsl(input: string): ShapeRowResult;
+declare function shapeRow(input: ShapeRowInput): ShapeRowResult;
+declare function groupShapedStitchesByOperation(shapedStitches: ShapedStitch[]): ShapingOperationGroup[];
+
+export { CM_TO_INCH, CM_TO_MM, type CastOnInput, type CompilePatternOptions, type CompiledPattern, type CompiledPatternRow, type EdgeElement, type Gauge, INCH_TO_CM, type ImperialGauge, KnittingMathError, type KnittingMathErrorCode, type KnittingMathErrorContext, KnittingMathExpansionError, KnittingMathParseError, KnittingMathValidationError, MM_TO_CM, type MetricGauge, type Pattern, type PatternCompileMode, type RepeatBlock, type ResolveOptions, type Row, type RowDslAst, type RowDslAstElement, type RowElement, type RowShapingOperation, type ShapeRowInput, type ShapeRowResult, type ShapedRowResult, type ShapedStitch, type ShapingDebugLine, type ShapingDebugOptions, type ShapingDslAst, type ShapingDslElement, type ShapingDslParseResult, type ShapingElement, type ShapingOperationGroup, type StitchInstruction, type StitchRegistry, type StitchType, type StitchVariant, type StitchVariantParameterValue, type StitchVariantParameters, type UnitSystem, calculateCastOn, calculateCastOnStitches, cmToRows, cmToStitches, compileCompatibleRowDsl, compilePattern, compileRowDsl, compileShapingDsl, convertLength, countStitchesInInstructions, createDefaultStitchRegistry, createEmptyStitchRegistry, createRepeatRow, ensureKnittingMathError, expandPattern, expandRow, expandRowToStitchTypes, expandRowToStitches, groupShapedStitchesByOperation, isRowDslAstWellFormed, normaliseMeasurement, parseCompatibleRowDsl, parseCompatibleRowDslAst, parseRowDsl, parseRowDslAst, parseShapingDsl, parseShapingDslAst, printPattern, printShapingDebug, renderShapingDebug, renderShapingDebugForInput, resolveRowDslAst, roundStitches, rowToRowDsl, rowsPerCm, shapeRow, shapedExpandPattern, stitchesPerCm };