pasika 0.3.3 → 0.3.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pasika",
-  "version": "0.3.3",
+  "version": "0.3.4",
   "description": "Reusable agent setup package",
   "repository": {
     "type": "git",
@@ -22,9 +22,8 @@
     "dist"
   ],
   "scripts": {
-    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "build": "tsup",
     "coverage": "tsx cli/index.ts coverage",
-    "docs": "eslint docs",
     "fix": "eslint . --fix",
     "lint": "eslint .",
     "prepack": "npm run build",
@@ -49,6 +48,7 @@
     "eslint": "^10.9.1",
     "jiti": "^2.7.0",
     "prettier": "^3.8.1",
+    "tsup": "^8.5.1",
     "tsx": "^4.23.12",
     "typescript": "^5.9.2",
     "zirka": "^0.0.42"

package/dist/cli/output.d.ts

@@ -1,3 +0,0 @@
-export declare function log(message: string): void;
-export declare function error(message: string): void;
-export declare function json(data: unknown): void;

package/dist/cli/output.js

@@ -1,11 +0,0 @@
-/* eslint-disable no-console -- cli-reports-to-terminal: stdout is the CLI's output channel */
-export function log(message) {
-    console.log(message);
-}
-export function error(message) {
-    console.error(message);
-}
-export function json(data) {
-    console.log(JSON.stringify(data, undefined, 2));
-}
-/* eslint-enable no-console -- re-enable after CLI output block */

package/dist/enforcement/coverage.d.ts

@@ -1,55 +0,0 @@
-import { type EnforcementKind, type Registry, type Requirement } from "./types.js";
-export interface CoverageIssue {
-    kind: "new" | "changed" | "removed" | "unknown-ref" | "missing-test";
-    doc: string;
-    line?: number;
-    text: string;
-    /** Hash of the requirement as it reads now, so a new entry can be recorded without recomputing it. */
-    hash?: string;
-    detail?: string;
-}
-export interface CoverageReport {
-    counts: Record<EnforcementKind, number>;
-    total: number;
-    mechanical: number;
-    issues: CoverageIssue[];
-    /** Registry updated for `--accept`: reworded requirements rehashed, removed ones dropped. */
-    nextRegistry: Registry;
-}
-export declare function buildCoverageReport(options: {
-    docsRoot: string;
-    registry: Registry;
-    rulesDir: string;
-}): CoverageReport;
-export interface ClassifyInput {
-    /** Hash of the requirement, as `coverage` prints it. */
-    hash: string;
-    kind: EnforcementKind;
-    ref?: string;
-    note?: string;
-}
-export interface ClassifyResult {
-    registry: Registry;
-    requirement: Requirement;
-    /** The kind this requirement carried before, when it was already classified. */
-    previousKind?: EnforcementKind;
-}
-/**
- * Records how a requirement is checked.
- *
- * Validates that the requirement exists in the documentation as written, that a
- * ref names a check that exists, and that the kinds which are meaningless
- * without an explanation carry one. Throws with a readable message otherwise, so
- * the caller can print it and exit.
- */
-export declare function classifyRequirement(options: {
-    docsRoot: string;
-    registry: Registry;
-    input: ClassifyInput;
-}): ClassifyResult;
-export declare function readRegistry(registryPath: string): Registry;
-/**
- * Writes the registry sorted in the same order the requirements appear in the
- * docs: document order, then line order within each document.
- */
-export declare function writeRegistry(registryPath: string, registry: Registry, docsRoot: string): void;

package/dist/enforcement/coverage.js

@@ -1,239 +0,0 @@
-import { readdirSync, readFileSync, writeFileSync, statSync } from "node:fs";
-import path from "node:path";
-import { z } from "zod";
-import { allPasikaRuleIds } from "../eslint/pasika/index.js";
-import { normalizeRequirement } from "./normalize.js";
-import { parseDocs } from "./parse-docs.js";
-import { MECHANICAL_KINDS, registrySchema } from "./types.js";
-/** Ratio of shared words, used only to guess which stored requirement a reworded bullet came from. */
-function similarity(left, right) {
-    const leftWords = new Set(left.toLowerCase().split(/\W+/).filter(Boolean));
-    const rightWords = new Set(right.toLowerCase().split(/\W+/).filter(Boolean));
-    const shared = [...leftWords].filter((word) => rightWords.has(word)).length;
-    const union = new Set([...leftWords, ...rightWords]).size;
-    return union === 0 ? 0 : shared / union;
-}
-/** Titles passed to `describe` or `test` in the rule test files, recursing into subfolders. */
-function collectTestTitles(rulesDir) {
-    const titles = new Set();
-    const visit = (dir) => {
-        for (const entry of readdirSync(dir)) {
-            const entryPath = path.join(dir, entry);
-            if (statSync(entryPath).isDirectory()) {
-                visit(entryPath);
-                continue;
-            }
-            if (!entry.endsWith(".test.ts"))
-                continue;
-            const body = readFileSync(entryPath, "utf8");
-            const titlePattern = /\b(?:describe|test|it)\(\s*(?:"(?<double>(?:[^"\\]|\\.)*)"|'(?<single>(?:[^'\\]|\\.)*)')/g;
-            for (const match of body.matchAll(titlePattern)) {
-                const title = match.groups?.double ?? match.groups?.single ?? "";
-                titles.add(title.replaceAll('\\\\"', '"').replaceAll("\\\\'", "'"));
-            }
-        }
-    };
-    visit(rulesDir);
-    return titles;
-}
-/** A requirement several checks cover lists them comma-separated. */
-function refParts(ref) {
-    return (ref ?? "")
-        .split(",")
-        .map((part) => part.trim())
-        .filter(Boolean);
-}
-function isRefKnown(requirement) {
-    const parts = refParts(requirement.ref);
-    if (requirement.kind === "eslint")
-        return parts.length > 0 && parts.every((part) => allPasikaRuleIds.includes(part));
-    // Doctor checks do not exist yet, so a `doctor` entry is a forward reference.
-    return true;
-}
-export function buildCoverageReport(options) {
-    const { docsRoot, registry, rulesDir } = options;
-    const docs = parseDocs(docsRoot);
-    const testTitles = collectTestTitles(rulesDir);
-    const byHash = new Map(registry.requirements.map((requirement) => [requirement.hash, requirement]));
-    const matched = new Set();
-    const issues = [];
-    const counts = {
-        eslint: 0,
-        doctor: 0,
-        planned: 0,
-        judgment: 0,
-        permission: 0,
-    };
-    const nextRequirements = [];
-    const parsed = docs.flatMap((doc) => doc.requirements.map((requirement) => ({ doc: doc.doc, requirement })));
-    for (const { doc, requirement } of parsed) {
-        const recorded = byHash.get(requirement.hash);
-        if (recorded) {
-            matched.add(requirement.hash);
-            counts[recorded.kind] += 1;
-            nextRequirements.push({ ...recorded, doc, text: requirement.raw });
-            if (!isRefKnown(recorded)) {
-                issues.push({
-                    kind: "unknown-ref",
-                    doc,
-                    line: requirement.line,
-                    text: requirement.raw,
-                    detail: `${recorded.kind} ref "${recorded.ref ?? "(none)"}" does not exist`,
-                });
-            }
-            if (recorded.kind === "eslint" && !testTitles.has(requirement.text)) {
-                issues.push({
-                    kind: "missing-test",
-                    doc,
-                    line: requirement.line,
-                    text: requirement.raw,
-                    detail: `no rule test is titled with this requirement`,
-                });
-            }
-            continue;
-        }
-        // Not recorded under this hash: either a reworded requirement or a new one.
-        const candidate = registry.requirements
-            .filter((entry) => entry.doc === doc && !matched.has(entry.hash))
-            .map((entry) => ({ entry, score: similarity(normalizeRequirement(entry.text), requirement.text) }))
-            .sort((left, right) => right.score - left.score)
-            .find(({ score }) => score >= 0.5);
-        if (candidate) {
-            matched.add(candidate.entry.hash);
-            counts[candidate.entry.kind] += 1;
-            nextRequirements.push({ ...candidate.entry, doc, text: requirement.raw, hash: requirement.hash });
-            issues.push({
-                kind: "changed",
-                doc,
-                line: requirement.line,
-                text: requirement.raw,
-                hash: requirement.hash,
-                detail: `was "${candidate.entry.text}" — re-verify ${candidate.entry.kind}${candidate.entry.ref ? ` ${candidate.entry.ref}` : ""}`,
-            });
-        }
-        else {
-            issues.push({ kind: "new", doc, line: requirement.line, text: requirement.raw, hash: requirement.hash });
-        }
-    }
-    for (const entry of registry.requirements) {
-        if (matched.has(entry.hash))
-            continue;
-        issues.push({
-            kind: "removed",
-            doc: entry.doc,
-            text: entry.text,
-            detail: `recorded as ${entry.kind}${entry.ref ? ` ${entry.ref}` : ""} but the bullet is gone`,
-        });
-    }
-    const total = parsed.length;
-    let mechanical = 0;
-    for (const kind of MECHANICAL_KINDS)
-        mechanical += counts[kind];
-    return {
-        counts,
-        total,
-        mechanical,
-        issues,
-        nextRegistry: { requirements: nextRequirements },
-    };
-}
-/**
- * Records how a requirement is checked.
- *
- * Validates that the requirement exists in the documentation as written, that a
- * ref names a check that exists, and that the kinds which are meaningless
- * without an explanation carry one. Throws with a readable message otherwise, so
- * the caller can print it and exit.
- */
-export function classifyRequirement(options) {
-    const { docsRoot, registry, input } = options;
-    const parsed = parseDocs(docsRoot).flatMap((doc) => doc.requirements.map((requirement) => ({ doc: doc.doc, requirement })));
-    const match = parsed.find((entry) => entry.requirement.hash === input.hash);
-    if (!match) {
-        throw new Error(`No requirement in the documentation has hash "${input.hash}". Run coverage to list them.`);
-    }
-    const refs = refParts(input.ref);
-    if (input.kind === "eslint") {
-        if (refs.length === 0)
-            throw new Error('Kind "eslint" needs --ref naming the rule that reports it.');
-        const unknown = refs.filter((ref) => !allPasikaRuleIds.includes(ref));
-        if (unknown.length > 0) {
-            throw new Error(`--ref ${unknown.map((ref) => `"${ref}"`).join(", ")} is not a rule in the plugin.`);
-        }
-    }
-    else if (input.kind !== "doctor" && refs.length > 0) {
-        throw new Error(`Kind "${input.kind}" takes no --ref, because nothing reports it.`);
-    }
-    if ((input.kind === "judgment" || input.kind === "planned") && (input.note ?? "").trim() === "") {
-        const reason = input.kind === "judgment" ? "why no check can decide it" : "the check that should cover it";
-        throw new Error(`Kind "${input.kind}" needs --note naming ${reason}.`);
-    }
-    const requirement = {
-        doc: match.doc,
-        text: match.requirement.raw,
-        hash: match.requirement.hash,
-        kind: input.kind,
-        ...(refs.length > 0 ? { ref: refs.join(", ") } : {}),
-        ...((input.note ?? "").trim() === "" ? {} : { note: input.note?.trim() }),
-    };
-    const existing = registry.requirements.find((entry) => entry.hash === input.hash);
-    const requirements = registry.requirements.filter((entry) => entry.hash !== input.hash);
-    requirements.push(requirement);
-    return { registry: { requirements }, requirement, previousKind: existing?.kind };
-}
-export function readRegistry(registryPath) {
-    const parsed = JSON.parse(readFileSync(registryPath, "utf8"));
-    const result = registrySchema.safeParse(parsed);
-    if (!result.success) {
-        throw new Error(`${registryPath} is not a valid enforcement registry:\n${z.prettifyError(result.error)}`);
-    }
-    return result.data;
-}
-/**
- * Sequence position of each requirement in the docs: doc order as `parseDocs`
- * yields it, then line order within each doc. Entries whose hash no longer
- * exists in the docs (removed, not yet accepted) sort after everything parsed.
- */
-function buildDocOrder(docsRoot) {
-    const order = new Map();
-    let position = 0;
-    for (const doc of parseDocs(docsRoot)) {
-        for (const requirement of doc.requirements) {
-            order.set(requirement.hash, position);
-            position += 1;
-        }
-    }
-    return order;
-}
-/**
- * Code-point order on doc then text. Deliberately not `localeCompare`, whose
- * result depends on the host's locale data — a generated file that is committed
- * has to sort the same way everywhere.
- */
-function compareRequirements(left, right) {
-    if (left.doc !== right.doc)
-        return left.doc < right.doc ? -1 : 1;
-    if (left.text !== right.text)
-        return left.text < right.text ? -1 : 1;
-    return 0;
-}
-/**
- * Writes the registry sorted in the same order the requirements appear in the
- * docs: document order, then line order within each document.
- */
-export function writeRegistry(registryPath, registry, docsRoot) {
-    const order = buildDocOrder(docsRoot);
-    const withPosition = registry.requirements.map((requirement) => ({
-        requirement,
-        position: order.get(requirement.hash) ?? Number.MAX_SAFE_INTEGER,
-    }));
-    withPosition.sort((left, right) => {
-        if (left.position !== right.position)
-            return left.position - right.position;
-        // Two entries with the same hash cannot coexist; this fallback orders
-        // entries whose hash the docs no longer contain, deterministically.
-        return compareRequirements(left.requirement, right.requirement);
-    });
-    const sorted = { requirements: withPosition.map((entry) => entry.requirement) };
-    writeFileSync(registryPath, `${JSON.stringify(sorted, null, 2)}\n`);
-}

package/dist/enforcement/doctor.d.ts

@@ -1,16 +0,0 @@
-/**
- * `pasika doctor` checks.
- *
- * Diagnoses gaps between a consumer repository and the pasika framework
- * baseline. Scope: dependencies, configuration, managed files, and
- * source structure. Code-level and path-level rules belong to ESLint.
- */
-export interface DoctorFinding {
-    /** Which requirement this relates to. */
-    check: string;
-    /** Human-readable description. */
-    message: string;
-    /** Severity: error blocks adoption, warning is informational. */
-    severity: "error" | "warning";
-}
-export declare function runDoctor(cwd: string): DoctorFinding[];

package/dist/enforcement/doctor.js

@@ -1,249 +0,0 @@
-/**
- * `pasika doctor` checks.
- *
- * Diagnoses gaps between a consumer repository and the pasika framework
- * baseline. Scope: dependencies, configuration, managed files, and
- * source structure. Code-level and path-level rules belong to ESLint.
- */
-import fs from "node:fs";
-import path from "node:path";
-import { z } from "zod";
-const packageJsonSchema = z.object({
-    dependencies: z.record(z.string(), z.string()).optional(),
-    devDependencies: z.record(z.string(), z.string()).optional(),
-    scripts: z.record(z.string(), z.string()).optional(),
-});
-function readPackageJson(filePath) {
-    try {
-        const result = packageJsonSchema.safeParse(JSON.parse(fs.readFileSync(filePath, "utf8")));
-        if (result.success)
-            return result.data;
-    }
-    catch {
-        // missing or unparseable
-    }
-    return {};
-}
-/**
- * Check that pasika and zirka are installed at compatible versions.
- */
-function checkFrameworkPackages(pkg) {
-    const findings = [];
-    const allDeps = { ...pkg.dependencies, ...pkg.devDependencies };
-    if (!allDeps.pasika) {
-        findings.push({
-            check: "pasika-installed",
-            message: "pasika is not listed in package.json.",
-            severity: "error",
-        });
-    }
-    if (!allDeps.zirka) {
-        findings.push({
-            check: "zirka-installed",
-            message: "zirka is not listed in package.json.",
-            severity: "error",
-        });
-    }
-    return findings;
-}
-/**
- * Check that application source lives under src/.
- */
-function checkSourceRoot(cwd) {
-    const findings = [];
-    const srcDir = path.join(cwd, "src");
-    if (!fs.existsSync(srcDir)) {
-        findings.push({
-            check: "source-under-src",
-            message: "Application source must live under src/.",
-            severity: "error",
-        });
-        return findings;
-    }
-    // Check for common non-src source directories at the project root
-    const entries = fs.readdirSync(cwd, { withFileTypes: true });
-    const suspicious = entries.filter((e) => e.isDirectory() &&
-        !e.name.startsWith(".") &&
-        e.name !== "src" &&
-        e.name !== "node_modules" &&
-        e.name !== "dist" &&
-        e.name !== "build" &&
-        e.name !== ".vulyk" &&
-        e.name !== "docs" &&
-        e.name !== "enforcement" &&
-        e.name !== "eslint" &&
-        e.name !== "cli" &&
-        e.name !== "__tests__" &&
-        e.name !== "test" &&
-        e.name !== "tests" &&
-        e.name !== "coverage" &&
-        e.name !== ".github" &&
-        e.name !== ".agents" &&
-        e.name !== ".husky" &&
-        e.name !== ".next" &&
-        e.name !== ".turbo" &&
-        e.name !== ".vercel" &&
-        e.name !== ".cache" &&
-        e.name !== ".tmp" &&
-        e.name !== "tmp" &&
-        e.name !== "public" &&
-        e.name !== "static" &&
-        e.name !== "assets" &&
-        e.name !== "bin" &&
-        e.name !== "vendor");
-    if (suspicious.length > 0) {
-        const names = suspicious.map((e) => e.name).join(", ");
-        findings.push({
-            check: "source-under-src",
-            message: `Possible source directories outside src/: ${names}.`,
-            severity: "warning",
-        });
-    }
-    return findings;
-}
-/**
- * Find the global CSS file that registers Tailwind.
- */
-function findGlobalStylesheet(cwd) {
-    const candidates = ["src/app/globals.css", "src/styles/globals.css", "src/globals.css"];
-    for (const candidate of candidates) {
-        const full = path.join(cwd, candidate);
-        if (fs.existsSync(full))
-            return full;
-    }
-    // Search for any CSS file containing @import "tailwindcss"
-    const srcDir = path.join(cwd, "src");
-    if (!fs.existsSync(srcDir))
-        return undefined;
-    const walk = (dir) => {
-        for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
-            const full = path.join(dir, entry.name);
-            if (entry.isDirectory() && entry.name !== "node_modules" && entry.name !== ".next") {
-                const found = walk(full);
-                if (found)
-                    return found;
-            }
-            if (entry.isFile() && entry.name.endsWith(".css")) {
-                const content = fs.readFileSync(full, "utf8");
-                if (content.includes('@import "tailwindcss"') || content.includes("@import 'tailwindcss'")) {
-                    return full;
-                }
-            }
-        }
-        return undefined;
-    };
-    return walk(srcDir);
-}
-/**
- * Check that the repository has a global stylesheet entry point that
- * registers Tailwind. The stylesheet's contents are the ESLint CSS rules'
- * concern, so doctor only checks that it exists.
- */
-function checkGlobalStylesheet(cwd) {
-    const findings = [];
-    const stylesheet = findGlobalStylesheet(cwd);
-    if (!stylesheet) {
-        findings.push({
-            check: "global-stylesheet",
-            message: 'No global stylesheet found. Create src/app/globals.css with @import "tailwindcss".',
-            severity: "error",
-        });
-    }
-    return findings;
-}
-/**
- * Check that configuration files follow the pasika baseline.
- *
- * Repositories must take their lint, format, and TypeScript configuration
- * from pasika and zirka rather than restating it locally.
- */
-function checkConfigBaseline(cwd) {
-    const findings = [];
-    // eslint.config.ts must exist and reference zirka
-    const eslintConfigs = ["eslint.config.ts", "eslint.config.mjs", "eslint.config.js"];
-    const eslintConfig = eslintConfigs.find((name) => fs.existsSync(path.join(cwd, name)));
-    if (!eslintConfig) {
-        findings.push({
-            check: "config-baseline",
-            message: "No eslint config found. Create eslint.config.ts extending the pasika/zirka baseline.",
-            severity: "error",
-        });
-    }
-    else {
-        const content = fs.readFileSync(path.join(cwd, eslintConfig), "utf8");
-        if (!content.includes("zirka")) {
-            findings.push({
-                check: "config-baseline",
-                message: `eslint config does not reference zirka. Use the pasika/zirka baseline configuration.`,
-                severity: "warning",
-            });
-        }
-    }
-    // tsconfig.json must exist
-    if (!fs.existsSync(path.join(cwd, "tsconfig.json"))) {
-        findings.push({
-            check: "config-baseline",
-            message: "No tsconfig.json found. Create one extending the pasika baseline.",
-            severity: "error",
-        });
-    }
-    return findings;
-}
-/**
- * Check that vulyk-managed files have not been hand-edited.
- *
- * Files listed in the .vulyk manifest are generated by vulyk commands
- * and must not be edited directly.
- */
-function checkManagedFiles(cwd) {
-    const findings = [];
-    const vulykDir = path.join(cwd, ".vulyk");
-    if (!fs.existsSync(vulykDir))
-        return findings;
-    const manifestPath = path.join(vulykDir, "manifest.json");
-    if (!fs.existsSync(manifestPath))
-        return findings;
-    try {
-        const manifestEntrySchema = z.looseObject({
-            targets: z.array(z.string()).optional(),
-        });
-        const manifestSchema = z.record(z.string(), manifestEntrySchema);
-        const result = manifestSchema.safeParse(JSON.parse(fs.readFileSync(manifestPath, "utf8")));
-        if (!result.success)
-            return findings;
-        for (const [, entry] of Object.entries(result.data)) {
-            const targets = entry.targets ?? [];
-            for (const target of targets) {
-                const targetPath = path.join(cwd, target);
-                if (fs.existsSync(targetPath)) {
-                    // File exists — check it hasn't been modified since vulyk last wrote it
-                    const stat = fs.statSync(targetPath);
-                    const vulykStat = fs.statSync(manifestPath);
-                    // If target is newer than the manifest, it was edited after vulyk wrote it
-                    if (stat.mtimeMs > vulykStat.mtimeMs + 1000) {
-                        findings.push({
-                            check: "managed-file-edit",
-                            message: `File "${target}" appears to have been edited after vulyk wrote it. Use vulyk commands to update managed files.`,
-                            severity: "warning",
-                        });
-                    }
-                }
-            }
-        }
-    }
-    catch {
-        // manifest unreadable
-    }
-    return findings;
-}
-export function runDoctor(cwd) {
-    const pkgPath = path.join(cwd, "package.json");
-    const pkg = readPackageJson(pkgPath);
-    return [
-        ...checkFrameworkPackages(pkg),
-        ...checkConfigBaseline(cwd),
-        ...checkManagedFiles(cwd),
-        ...checkSourceRoot(cwd),
-        ...checkGlobalStylesheet(cwd),
-    ];
-}

package/dist/enforcement/normalize.d.ts

@@ -1,11 +0,0 @@
-/**
- * Reduces a requirement bullet to the text its meaning depends on.
- *
- * Markdown links collapse to their link text and code spans lose their
- * backticks, so editing a URL or adding backticks does not read as a change in
- * what the requirement demands. Whitespace collapses so re-wrapping a long
- * bullet is not a change either.
- */
-export declare function normalizeRequirement(bullet: string): string;
-/** Short, stable fingerprint of a canonical requirement text. */
-export declare function hashRequirement(canonicalText: string): string;

package/dist/enforcement/normalize.js

@@ -1,21 +0,0 @@
-import { createHash } from "node:crypto";
-/**
- * Reduces a requirement bullet to the text its meaning depends on.
- *
- * Markdown links collapse to their link text and code spans lose their
- * backticks, so editing a URL or adding backticks does not read as a change in
- * what the requirement demands. Whitespace collapses so re-wrapping a long
- * bullet is not a change either.
- */
-export function normalizeRequirement(bullet) {
-    return bullet
-        .replace(/^\s*[-*]\s+/, "")
-        .replaceAll(/\[(?<text>[^\]]+)\]\([^)]*\)/g, "$<text>")
-        .replaceAll("`", "")
-        .replaceAll(/\s+/g, " ")
-        .trim();
-}
-/** Short, stable fingerprint of a canonical requirement text. */
-export function hashRequirement(canonicalText) {
-    return createHash("sha256").update(canonicalText).digest("hex").slice(0, 10);
-}