@aperant/framework 0.6.2

package/dist/cli/design/lint.d.mts

@@ -0,0 +1,54 @@
+/**
+ * Run the full lint.
+ *
+ * @param {object} input
+ * @param {AntiPattern[]} input.rules — antiPatterns from DESIGN.md frontmatter
+ * @param {{ file: string, text: string }[]} input.files — files to scan
+ * @returns {LintResult}
+ */
+export function lintAntiPatterns({ rules, files }: {
+    rules: AntiPattern[];
+    files: {
+        file: string;
+        text: string;
+    }[];
+}): LintResult;
+/**
+ * Group a flat violations array by file.  Convenience for report rendering.
+ *
+ * @param {Violation[]} violations
+ * @returns {Record<string, Violation[]>}
+ */
+export function groupByFile(violations: Violation[]): Record<string, Violation[]>;
+/**
+ * Build a short human-readable summary of the lint result.
+ *
+ * @param {LintResult} result
+ * @returns {string}
+ */
+export function summarize(result: LintResult): string;
+export type AntiPattern = {
+    id: string;
+    category: string;
+    pattern: string;
+    why: string;
+    rewrite: string;
+};
+export type Violation = {
+    file: string;
+    line: number;
+    column: number;
+    rule_id: string;
+    category: string;
+    match: string;
+    why: string;
+    rewrite: string;
+};
+export type LintResult = {
+    violations: Violation[];
+    warnings: string[];
+    files_scanned: number;
+    rules_compiled: number;
+    rules_skipped: number;
+};
+//# sourceMappingURL=lint.d.mts.map

package/dist/cli/design/lint.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lint.d.mts","sourceRoot":"","sources":["../../../src/cli/design/lint.mjs"],"names":[],"mappings":"AAoGA;;;;;;;GAOG;AACH,mDAJG;IAA6B,KAAK,EAA1B,WAAW,EAAE;IAC2B,KAAK,EAA7C;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;CACxC,GAAU,UAAU,CAsEtB;AAED;;;;;GAKG;AACH,wCAHW,SAAS,EAAE,GACT,MAAM,CAAC,MAAM,EAAE,SAAS,EAAE,CAAC,CASvC;AAED;;;;;GAKG;AACH,kCAHW,UAAU,GACR,MAAM,CAUlB;0BAnLY;IACR,EAAE,EAAE,MAAM,CAAC;IACX,QAAQ,EAAE,MAAM,CAAC;IACjB,OAAO,EAAE,MAAM,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;wBAES;IACR,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,OAAO,EAAE,MAAM,CAAC;CACjB;yBAES;IACR,UAAU,EAAE,SAAS,EAAE,CAAC;IACxB,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/dist/cli/design/lint.mjs

@@ -0,0 +1,203 @@
+/**
+ * design/lint.mjs — static grep-based anti-pattern lint for generated HTML/CSS (C11).
+ *
+ * Given a DESIGN.md (the project-root system contract) and a list of HTML/CSS
+ * files (mockups, component outputs, or plain stylesheets), compile each
+ * antiPatterns rule's `pattern` as a regular expression and scan each file
+ * for matches.  A match = a violation, carrying the rule id + category +
+ * the rewrite guidance authored alongside the pattern.
+ *
+ * Pure function: no I/O for rule compilation; callers read files and pass
+ * the text in.  This keeps it trivially testable from vitest without tmp
+ * dirs and lets the CLI layer do selective reads (e.g. only *.html under
+ * a task_dir).
+ *
+ * Regex compile:
+ *   - Patterns are stored as plain strings in the YAML frontmatter so
+ *     humans can read them.  We compile with `gm` flags — global for
+ *     line-spanning matches, multiline so `^` / `$` anchor per line.
+ *   - Rules that fail to compile are reported as lint warnings (skipped,
+ *     not fatal) so the catalog doesn't bring the pipeline down when a
+ *     typo slips through.
+ *
+ * Line numbers: we precompute line-start offsets once per file, then map
+ * match.index → line via binary search.  Matches are truncated at 120
+ * chars so JSON payloads stay small even on huge generated files.
+ */
+/**
+ * @typedef {{
+ *   id: string,
+ *   category: string,
+ *   pattern: string,
+ *   why: string,
+ *   rewrite: string,
+ * }} AntiPattern
+ *
+ * @typedef {{
+ *   file: string,
+ *   line: number,
+ *   column: number,
+ *   rule_id: string,
+ *   category: string,
+ *   match: string,
+ *   why: string,
+ *   rewrite: string,
+ * }} Violation
+ *
+ * @typedef {{
+ *   violations: Violation[],
+ *   warnings: string[],
+ *   files_scanned: number,
+ *   rules_compiled: number,
+ *   rules_skipped: number,
+ * }} LintResult
+ */
+const MATCH_TRUNCATE = 120;
+function buildLineOffsets(text) {
+    const offsets = [0];
+    for (let i = 0; i < text.length; i++) {
+        if (text.charCodeAt(i) === 10) {
+            offsets.push(i + 1);
+        }
+    }
+    return offsets;
+}
+function offsetToLineCol(offsets, offset) {
+    // binary search for the greatest offset <= our match index
+    let lo = 0;
+    let hi = offsets.length - 1;
+    while (lo < hi) {
+        const mid = (lo + hi + 1) >>> 1;
+        if (offsets[mid] <= offset)
+            lo = mid;
+        else
+            hi = mid - 1;
+    }
+    return { line: lo + 1, column: offset - offsets[lo] + 1 };
+}
+function truncate(s) {
+    if (!s)
+        return '';
+    return s.length > MATCH_TRUNCATE ? `${s.slice(0, MATCH_TRUNCATE - 1)}…` : s;
+}
+/**
+ * Compile a single antiPattern rule into a RegExp.  Returns null when the
+ * pattern doesn't compile — the caller should surface a warning.
+ *
+ * @param {AntiPattern} rule
+ * @returns {RegExp | null}
+ */
+function compileRule(rule) {
+    try {
+        return new RegExp(rule.pattern, 'gm');
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Run the full lint.
+ *
+ * @param {object} input
+ * @param {AntiPattern[]} input.rules — antiPatterns from DESIGN.md frontmatter
+ * @param {{ file: string, text: string }[]} input.files — files to scan
+ * @returns {LintResult}
+ */
+export function lintAntiPatterns({ rules, files }) {
+    if (!Array.isArray(rules)) {
+        return {
+            violations: [],
+            warnings: ['no antiPatterns array supplied'],
+            files_scanned: 0,
+            rules_compiled: 0,
+            rules_skipped: 0,
+        };
+    }
+    if (!Array.isArray(files)) {
+        throw new Error('lintAntiPatterns: files must be an array');
+    }
+    const warnings = [];
+    /** @type {Array<{ rule: AntiPattern, regex: RegExp }>} */
+    const compiled = [];
+    let skipped = 0;
+    for (const rule of rules) {
+        if (!rule || typeof rule.pattern !== 'string' || typeof rule.id !== 'string') {
+            warnings.push(`skipped rule with missing id or pattern: ${JSON.stringify(rule)}`);
+            skipped++;
+            continue;
+        }
+        const regex = compileRule(rule);
+        if (!regex) {
+            warnings.push(`rule "${rule.id}" failed to compile: ${rule.pattern}`);
+            skipped++;
+            continue;
+        }
+        compiled.push({ rule, regex });
+    }
+    /** @type {Violation[]} */
+    const violations = [];
+    for (const { file, text } of files) {
+        if (typeof text !== 'string' || text.length === 0)
+            continue;
+        const offsets = buildLineOffsets(text);
+        for (const { rule, regex } of compiled) {
+            regex.lastIndex = 0;
+            let m = regex.exec(text);
+            while (m !== null) {
+                const { line, column } = offsetToLineCol(offsets, m.index);
+                violations.push({
+                    file,
+                    line,
+                    column,
+                    rule_id: rule.id,
+                    category: rule.category,
+                    match: truncate(m[0]),
+                    why: rule.why,
+                    rewrite: rule.rewrite,
+                });
+                // Guard against zero-width regex infinite loop: advance by 1 when
+                // the match is empty.
+                if (regex.lastIndex === m.index)
+                    regex.lastIndex++;
+                m = regex.exec(text);
+            }
+        }
+    }
+    return {
+        violations,
+        warnings,
+        files_scanned: files.length,
+        rules_compiled: compiled.length,
+        rules_skipped: skipped,
+    };
+}
+/**
+ * Group a flat violations array by file.  Convenience for report rendering.
+ *
+ * @param {Violation[]} violations
+ * @returns {Record<string, Violation[]>}
+ */
+export function groupByFile(violations) {
+    const out = {};
+    for (const v of violations) {
+        if (!out[v.file])
+            out[v.file] = [];
+        out[v.file].push(v);
+    }
+    return out;
+}
+/**
+ * Build a short human-readable summary of the lint result.
+ *
+ * @param {LintResult} result
+ * @returns {string}
+ */
+export function summarize(result) {
+    const byCat = new Map();
+    for (const v of result.violations) {
+        byCat.set(v.category, (byCat.get(v.category) ?? 0) + 1);
+    }
+    const catSummary = byCat.size === 0 ? '' : ` (${[...byCat.entries()].map(([c, n]) => `${c}=${n}`).join(', ')})`;
+    return `${result.violations.length} violation(s) across ${result.files_scanned} file(s)${catSummary}; rules compiled=${result.rules_compiled} skipped=${result.rules_skipped}`;
+}
+//# sourceMappingURL=lint.mjs.map

package/dist/cli/design/lint.mjs.map

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

package/dist/cli/design/product-context.d.mts

@@ -0,0 +1,83 @@
+/**
+ * @typedef {Object} LoadedFeature
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ */
+/**
+ * @typedef {Object} LoadedProductContext
+ * @property {string} productName
+ * @property {string} productDescription
+ * @property {string} targetAudience
+ * @property {LoadedFeature[]} features
+ * @property {{ source?: string, updatedAt?: string }=} _meta
+ */
+/**
+ * @typedef {Object} LoadResult
+ * @property {boolean} present
+ * @property {'aperant-file' | 'none'} source
+ * @property {LoadedProductContext | null} productContext
+ * @property {string[]} errors
+ * @property {string[]} warnings
+ * @property {string} path   absolute path the loader resolved (may not exist)
+ */
+/**
+ * Resolve the canonical location of product-context.json for a project dir.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function productContextPath(projectDir: string): string;
+/**
+ * Load + normalize product-context from disk.
+ *
+ * - Missing file → `{ present: false, source: 'none', errors: [] }` (NOT an error).
+ * - Parse error or schema violation → `errors[]` populated, `present: false`.
+ * - Valid file → normalized `productContext` + `present: true`.
+ *
+ * @param {string} projectDir  absolute or cwd-relative path to the project root
+ * @returns {LoadResult}
+ */
+export function loadProductContext(projectDir: string): LoadResult;
+export const ProductContextSchema: z.ZodObject<{
+    productName: z.ZodString;
+    productDescription: z.ZodString;
+    targetAudience: z.ZodString;
+    features: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+    _meta: z.ZodOptional<z.ZodObject<{
+        source: z.ZodOptional<z.ZodString>;
+        updatedAt: z.ZodOptional<z.ZodString>;
+    }, z.core.$loose>>;
+}, z.core.$loose>;
+export type LoadedFeature = {
+    id: string;
+    name: string;
+    description: string;
+};
+export type LoadedProductContext = {
+    productName: string;
+    productDescription: string;
+    targetAudience: string;
+    features: LoadedFeature[];
+    _meta?: {
+        source?: string;
+        updatedAt?: string;
+    } | undefined;
+};
+export type LoadResult = {
+    present: boolean;
+    source: "aperant-file" | "none";
+    productContext: LoadedProductContext | null;
+    errors: string[];
+    warnings: string[];
+    /**
+     * absolute path the loader resolved (may not exist)
+     */
+    path: string;
+};
+import { z } from 'zod';
+//# sourceMappingURL=product-context.d.mts.map

package/dist/cli/design/product-context.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-context.d.mts","sourceRoot":"","sources":["../../../src/cli/design/product-context.mjs"],"names":[],"mappings":"AAqDA;;;;;GAKG;AAEH;;;;;;;GAOG;AAEH;;;;;;;;GAQG;AAEH;;;;;GAKG;AACH,+CAHW,MAAM,GACJ,MAAM,CAIlB;AAED;;;;;;;;;GASG;AACH,+CAHW,MAAM,GACJ,UAAU,CAqEtB;AA3HD;;;;;;;;;;;;;kBAQe;;QAID,MAAM;UACN,MAAM;iBACN,MAAM;;;iBAKN,MAAM;wBACN,MAAM;oBACN,MAAM;cACN,aAAa,EAAE;YACf;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,YAAC;;;aAKxC,OAAO;YACP,cAAc,GAAG,MAAM;oBACvB,oBAAoB,GAAG,IAAI;YAC3B,MAAM,EAAE;cACR,MAAM,EAAE;;;;UACR,MAAM;;kBApDF,KAAK"}

package/dist/cli/design/product-context.mjs

@@ -0,0 +1,160 @@
+/**
+ * design/product-context.mjs — loader + normalizer for .aperant/product-context.json (C44).
+ *
+ * Pure function: `loadProductContext(projectDir)` reads the on-disk
+ * product-context file (written by the Aperant app — framework CLI is
+ * read-only) and returns a structured envelope describing what was found.
+ *
+ * Missing file is NOT an error — it's the common case before a user has
+ * completed product-onboarding, so the loader returns `{ present: false }`
+ * and lets callers fall back to the generic drafting path. Parse errors and
+ * schema violations return `errors[]` populated.
+ *
+ * The canonical shape mirrors `WizardProductContext`
+ * (packages/ui/src/design-system/wizard/types.ts) so the file written by
+ * the wizard (project scope, out-of-scope for this task) and the file read
+ * by the framework share a single line of code for the contract.
+ *
+ * No network, no subprocess, no LLM — deterministic. CI-friendly. No API
+ * keys required. The LLM call site is `design/synthesize.mjs`, which is
+ * explicitly dependency-injected for tests.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { resolve as resolvePath } from 'node:path';
+import { z } from 'zod';
+const NonEmptyString = z.string().min(1);
+const FeatureSchema = z
+    .object({
+    id: NonEmptyString,
+    name: NonEmptyString,
+    description: z.string().optional(),
+})
+    .passthrough();
+const MetaSchema = z
+    .object({
+    source: z.string().optional(),
+    updatedAt: z.string().optional(),
+})
+    .passthrough();
+export const ProductContextSchema = z
+    .object({
+    productName: NonEmptyString,
+    productDescription: z.string(),
+    targetAudience: z.string(),
+    features: z.array(FeatureSchema),
+    _meta: MetaSchema.optional(),
+})
+    .passthrough();
+/**
+ * @typedef {Object} LoadedFeature
+ * @property {string} id
+ * @property {string} name
+ * @property {string} description
+ */
+/**
+ * @typedef {Object} LoadedProductContext
+ * @property {string} productName
+ * @property {string} productDescription
+ * @property {string} targetAudience
+ * @property {LoadedFeature[]} features
+ * @property {{ source?: string, updatedAt?: string }=} _meta
+ */
+/**
+ * @typedef {Object} LoadResult
+ * @property {boolean} present
+ * @property {'aperant-file' | 'none'} source
+ * @property {LoadedProductContext | null} productContext
+ * @property {string[]} errors
+ * @property {string[]} warnings
+ * @property {string} path   absolute path the loader resolved (may not exist)
+ */
+/**
+ * Resolve the canonical location of product-context.json for a project dir.
+ *
+ * @param {string} projectDir
+ * @returns {string}
+ */
+export function productContextPath(projectDir) {
+    return resolvePath(projectDir, '.aperant', 'product-context.json');
+}
+/**
+ * Load + normalize product-context from disk.
+ *
+ * - Missing file → `{ present: false, source: 'none', errors: [] }` (NOT an error).
+ * - Parse error or schema violation → `errors[]` populated, `present: false`.
+ * - Valid file → normalized `productContext` + `present: true`.
+ *
+ * @param {string} projectDir  absolute or cwd-relative path to the project root
+ * @returns {LoadResult}
+ */
+export function loadProductContext(projectDir) {
+    const path = productContextPath(projectDir);
+    const result = {
+        present: false,
+        source: /** @type {'aperant-file' | 'none'} */ ('none'),
+        productContext: /** @type {LoadedProductContext | null} */ (null),
+        errors: /** @type {string[]} */ ([]),
+        warnings: /** @type {string[]} */ ([]),
+        path,
+    };
+    if (!existsSync(path)) {
+        return result;
+    }
+    let raw;
+    try {
+        raw = readFileSync(path, 'utf8');
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result.errors.push(`failed to read ${path}: ${msg}`);
+        return result;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        result.errors.push(`product-context.json: invalid JSON — ${msg}`);
+        return result;
+    }
+    if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+        result.errors.push('product-context.json: top-level value must be an object');
+        return result;
+    }
+    const validation = ProductContextSchema.safeParse(parsed);
+    if (!validation.success) {
+        for (const issue of validation.error.issues) {
+            const pathStr = issue.path && issue.path.length > 0 ? issue.path.join('.') : '(root)';
+            result.errors.push(`product-context.${pathStr}: ${issue.message}`);
+        }
+        return result;
+    }
+    const value = /** @type {LoadedProductContext} */ (validation.data);
+    // Normalize features: ensure description is a string (fill empties).
+    const normFeatures = value.features.map((f) => ({
+        id: f.id,
+        name: f.name,
+        description: typeof f.description === 'string' ? f.description : '',
+    }));
+    result.present = true;
+    result.source = 'aperant-file';
+    result.productContext = {
+        productName: value.productName,
+        productDescription: value.productDescription,
+        targetAudience: value.targetAudience,
+        features: normFeatures,
+        ..._meta(value),
+    };
+    return result;
+}
+/**
+ * @param {LoadedProductContext} value
+ * @returns {{ _meta?: { source?: string, updatedAt?: string } }}
+ */
+function _meta(value) {
+    if (!value._meta || typeof value._meta !== 'object')
+        return {};
+    return { _meta: value._meta };
+}
+//# sourceMappingURL=product-context.mjs.map

package/dist/cli/design/product-context.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"product-context.mjs","sourceRoot":"","sources":["../../../src/cli/design/product-context.mjs"],"names":[],"mappings":"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"}

package/dist/cli/design/scan.d.mts

@@ -0,0 +1,47 @@
+/**
+ * Scan a project directory for design tokens.
+ *
+ * @param {string} projectRoot absolute or relative path to the project
+ * @param {{root?: string, maxFiles?: number, maxFileBytes?: number}} [opts]
+ *   root: optional subdirectory under projectRoot to scan (defaults to the
+ *     whole project). `node packages/framework/bin/apt-tools.mjs design-scan
+ *     . --root packages/ui` limits the scan to that tree.
+ * @returns {{
+ *   version: 1,
+ *   project_root: string,
+ *   scan: {files_scanned: number, files_skipped: number},
+ *   colors: ReturnType<typeof extractColors>,
+ *   spacing: ReturnType<typeof extractSpacing>,
+ *   typography: ReturnType<typeof extractTypography>,
+ *   radii: ReturnType<typeof extractRadii>,
+ *   shadows: ReturnType<typeof extractShadows>,
+ * }}
+ */
+export function scanDesignTokens(projectRoot: string, opts?: {
+    root?: string;
+    maxFiles?: number;
+    maxFileBytes?: number;
+}): {
+    version: 1;
+    project_root: string;
+    scan: {
+        files_scanned: number;
+        files_skipped: number;
+    };
+    colors: ReturnType<typeof extractColors>;
+    spacing: ReturnType<typeof extractSpacing>;
+    typography: ReturnType<typeof extractTypography>;
+    radii: ReturnType<typeof extractRadii>;
+    shadows: ReturnType<typeof extractShadows>;
+};
+export const SCAN_EXTENSIONS: Set<string>;
+export const SCAN_FILENAMES: Set<string>;
+export const EXCLUDED_DIRS: Set<string>;
+export const MAX_FILES: 2000;
+export const MAX_FILE_BYTES: number;
+import { extractColors } from './extract.mjs';
+import { extractSpacing } from './extract.mjs';
+import { extractTypography } from './extract.mjs';
+import { extractRadii } from './extract.mjs';
+import { extractShadows } from './extract.mjs';
+//# sourceMappingURL=scan.d.mts.map

package/dist/cli/design/scan.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scan.d.mts","sourceRoot":"","sources":["../../../src/cli/design/scan.mjs"],"names":[],"mappings":"AA2EA;;;;;;;;;;;;;;;;;;GAkBG;AACH,8CAhBW,MAAM,SACN;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,YAAY,CAAC,EAAE,MAAM,CAAA;CAAC,GAIvD;IACR,OAAO,EAAE,CAAC,CAAC;IACX,YAAY,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE;QAAC,aAAa,EAAE,MAAM,CAAC;QAAC,aAAa,EAAE,MAAM,CAAA;KAAC,CAAC;IACrD,MAAM,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC;IACzC,OAAO,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;IAC3C,UAAU,EAAE,UAAU,CAAC,OAAO,iBAAiB,CAAC,CAAC;IACjD,KAAK,EAAE,UAAU,CAAC,OAAO,YAAY,CAAC,CAAC;IACvC,OAAO,EAAE,UAAU,CAAC,OAAO,cAAc,CAAC,CAAC;CAC5C,CA2GH;AAxKD,0CAeE;AAKF,yCAKE;AAEF,wCAYE;AAEF,wBAAyB,IAAI,CAAA;AAC7B,oCAAwC;8BA5CjC,eAAe;+BAAf,eAAe;kCAAf,eAAe;6BAAf,eAAe;+BAAf,eAAe"}