@intentius/chant 0.124.12 → 0.124.14

package/dist/cli/commands/init-lexicon/templates/project.js

@@ -0,0 +1,240 @@
+/**
+ * Project-level template generators for init-lexicon scaffold.
+ */
+export function generatePackageJson(name, names) {
+    const pkg = {
+        name: names.packageName,
+        version: "0.0.1",
+        type: "module",
+        private: true,
+        files: ["src/", "dist/"],
+        exports: {
+            ".": {
+                development: "./src/index.ts",
+                types: "./dist/index.d.ts",
+                default: "./src/index.ts",
+            },
+            "./*": {
+                development: "./src/*.ts",
+                types: "./dist/*.d.ts",
+                default: "./src/*.ts",
+            },
+            "./manifest": "./dist/manifest.json",
+            "./meta": "./dist/meta.json",
+            "./types": "./dist/types/index.d.ts",
+        },
+        scripts: {
+            generate: "npx tsx src/codegen/generate-cli.ts",
+            validate: "npx tsx src/validate-cli.ts",
+            docs: "npx tsx src/codegen/docs-cli.ts",
+            build: 'tsc -p tsconfig.build.json && tsc-alias -p tsconfig.build.json && find dist -type f \\( -name "*.js" -o -name "*.js.map" \\) -delete',
+            prepack: "npm run generate && npm run bundle && npm run validate && npm run build",
+            bundle: "tsx src/package-cli.ts",
+        },
+        devDependencies: {
+            // `*` (not `workspace:*`) so a fresh lexicon `npm install`s under plain npm
+            // (the `workspace:` protocol is rejected outside a workspace).
+            "@intentius/chant": "*",
+            "tsc-alias": "^1.8.17",
+            typescript: "^5.9.3 || ^7.0.0",
+        },
+    };
+    return JSON.stringify(pkg, null, 2) + "\n";
+}
+export function generateTsConfig() {
+    const config = {
+        extends: "../../tsconfig.json",
+        compilerOptions: {
+            rootDir: "./src",
+            outDir: "./dist",
+        },
+        include: ["src/**/*"],
+    };
+    return JSON.stringify(config, null, 2) + "\n";
+}
+/**
+ * Build config used by `npm run build` (and CI's `tsc --noEmit`). Uses `bundler`
+ * resolution + the `development` condition so `@intentius/chant/*` resolves to the
+ * workspace source, and excludes tests/docs — the same setup the shipped lexicons
+ * use. (The plain `tsconfig.json` extends the monorepo root and can't be tsc'd on
+ * its own.)
+ */
+export function generateTsConfigBuild() {
+    const config = {
+        extends: "../../tsconfig.json",
+        compilerOptions: {
+            noEmit: false,
+            declaration: true,
+            declarationMap: true,
+            outDir: "dist",
+            rootDir: "src",
+            paths: {},
+            moduleResolution: "bundler",
+            customConditions: ["development"],
+        },
+        include: ["src/**/*"],
+        exclude: ["**/*.test.ts", "node_modules", "dist", "docs"],
+        "tsc-alias": { resolveFullPaths: true },
+    };
+    return JSON.stringify(config, null, 2) + "\n";
+}
+export function generateJustfile(name) {
+    return `# Default recipe - list all available commands
+default:
+    @just --list
+
+# Generate types and metadata from upstream schemas
+generate:
+    npx tsx src/codegen/generate-cli.ts
+
+# Validate generated artifacts
+validate:
+    npx tsx src/validate-cli.ts
+
+# Generate docs site, install deps, and start dev server
+docs:
+    npx tsx src/codegen/docs-cli.ts
+    npm install --prefix docs
+    npm run --prefix docs dev
+
+# Build docs site for production
+docs-build:
+    npx tsx src/codegen/docs-cli.ts
+    npm install --prefix docs
+    npm run --prefix docs build
+
+# Package the lexicon (generate + validate)
+package: generate validate
+`;
+}
+export function generateGitignore() {
+    return `dist/
+node_modules/
+.cache/
+`;
+}
+export function generateReadme(name, names) {
+    return `# ${names.packageName}
+
+${name} lexicon plugin for [chant](https://github.com/intentius/chant).
+
+## Getting started
+
+\`\`\`bash
+# Generate types from upstream spec
+just generate
+
+# Validate generated artifacts
+just validate
+
+# Generate documentation
+just docs
+\`\`\`
+
+## Project structure
+
+- \`src/plugin.ts\` — LexiconPlugin with all lifecycle methods
+- \`src/serializer.ts\` — Build output serializer
+- \`src/codegen/\` — Code generation pipeline
+- \`src/spec/\` — Upstream schema fetching and parsing
+- \`src/lint/rules/\` — Lint rules
+- \`src/lsp/\` — LSP completions and hover
+- \`src/generated/\` — Generated artifacts (do not edit)
+`;
+}
+export function generateSerializerTs(name, names) {
+    return `import type { Serializer, Declarable } from "@intentius/chant";
+
+/**
+ * ${name} serializer — produces minimal JSON output.
+ *
+ * TODO: Replace with your lexicon's output format.
+ */
+export const ${names.serializerVarName}: Serializer = {
+  name: "${name}",
+  rulePrefix: "${names.rulePrefix}",
+
+  serialize(entities: Map<string, Declarable>): string {
+    const resources: Record<string, unknown> = {};
+
+    for (const [entityName, entity] of entities) {
+      resources[entityName] = {
+        type: entity.entityType,
+        // TODO: Convert entity properties to your output format
+      };
+    }
+
+    return JSON.stringify({ resources }, null, 2);
+  },
+};
+`;
+}
+export function generateValidateTs(name) {
+    return `/**
+ * Validate generated lexicon-${name} artifacts.
+ *
+ * Thin wrapper around the core validation framework
+ * with ${name}-specific configuration.
+ */
+
+import { dirname } from "path";
+import { fileURLToPath } from "url";
+import { validateLexiconArtifacts, type ValidateResult } from "@intentius/chant/codegen/validate";
+
+export type { ValidateCheck, ValidateResult } from "@intentius/chant/codegen/validate";
+
+// TODO: Add names of required entities for your lexicon
+const REQUIRED_NAMES: string[] = [];
+
+/**
+ * Validate the generated lexicon-${name} artifacts.
+ */
+export async function validate(opts?: { basePath?: string }): Promise<ValidateResult> {
+  const basePath = opts?.basePath ?? dirname(dirname(fileURLToPath(import.meta.url)));
+
+  return validateLexiconArtifacts({
+    lexiconJsonFilename: "lexicon-${name}.json",
+    requiredNames: REQUIRED_NAMES,
+    basePath,
+  });
+}
+`;
+}
+export function generateValidateCliTs() {
+    return `#!/usr/bin/env tsx
+import { validate } from "./validate";
+
+// \`validate\` takes an optional { basePath }; defaults to the lexicon root.
+await validate();
+`;
+}
+/**
+ * Thin entry point for `npm run bundle`, called from `prepack`. Writes
+ * `src/generated/` (via the generate pipeline) and `dist/` (via the package
+ * pipeline plus `writeBundleSpec`), so `dist/manifest.json` exists before
+ * `npm run validate` and `npm run build` run.
+ */
+export function generatePackageCliTs() {
+    return `#!/usr/bin/env tsx
+import { generate, writeGeneratedFiles } from "./codegen/generate";
+import { packageLexicon } from "./codegen/package";
+import { writeBundleSpec } from "@intentius/chant/codegen/package";
+import { join, dirname } from "path";
+import { fileURLToPath } from "url";
+
+const srcDir = dirname(fileURLToPath(import.meta.url));
+
+// 1. Generate src/generated/ files (writeGeneratedFiles resolves its own target)
+const genResult = await generate({ verbose: true });
+writeGeneratedFiles(genResult);
+
+// 2. Run package pipeline and write dist/
+const { spec, stats } = await packageLexicon({ verbose: true });
+
+const distDir = join(dirname(srcDir), "dist");
+writeBundleSpec(spec, distDir);
+
+console.error(\`Packaged \${stats.resources} resources, \${stats.ruleCount} rules, \${stats.skillCount} skills\`);
+console.error(\`dist/ written to \${distDir}\`);
+`;
+}

package/dist/cli/commands/init-lexicon/templates/spec.js

@@ -0,0 +1,56 @@
+/**
+ * Spec template generators for init-lexicon scaffold.
+ */
+export function generateSpecFetchTs() {
+    return `import { fetchWithCache, extractFromZip } from "@intentius/chant/codegen/fetch";
+
+// TODO: Set this to your upstream schema source URL
+const SCHEMA_URL = "https://example.com/schemas.zip";
+const CACHE_FILE = ".cache/schemas.zip";
+
+/**
+ * Fetch upstream schemas with caching.
+ *
+ * TODO: Point SCHEMA_URL at your real upstream schema source.
+ */
+export async function fetchSchemas(options?: { force?: boolean }): Promise<Map<string, Buffer>> {
+  // \`force\` is the second argument to fetchWithCache (not a FetchConfig field).
+  const zipData = await fetchWithCache(
+    { url: SCHEMA_URL, cacheFile: CACHE_FILE },
+    options?.force,
+  );
+
+  // TODO: Adjust the filter to match your schema file names. extractFromZip yields
+  // Buffers — decode with \`.toString()\` in parse.ts as needed.
+  return extractFromZip(zipData, (name) => name.endsWith(".json"));
+}
+`;
+}
+export function generateSpecParseTs() {
+    return `/**
+ * Parsed schema result for a single schema file.
+ */
+export interface ParseResult {
+  typeName: string;
+  description?: string;
+  properties: Map<string, ParsedProperty>;
+  attributes: string[];
+}
+
+export interface ParsedProperty {
+  name: string;
+  type: string;
+  required: boolean;
+  description?: string;
+}
+
+/**
+ * Parse a single schema file into a ParseResult.
+ *
+ * TODO: Implement parsing for your schema format.
+ */
+export function parseSchema(name: string, content: string): ParseResult {
+  throw new Error(\`TODO: implement parseSchema for \${name}\`);
+}
+`;
+}

package/dist/cli/commands/init-lexicon/templates/tests.js

@@ -0,0 +1,66 @@
+/**
+ * Test file template generators for init-lexicon scaffold.
+ */
+export function generatePluginTestTs(name, names) {
+    return `import { describe, expect, it } from "vitest";
+import { ${names.pluginVarName} } from "./plugin.js";
+import { isLexiconPlugin } from "@intentius/chant/lexicon";
+
+describe("${name} plugin", () => {
+  it("is a valid LexiconPlugin", () => {
+    expect(isLexiconPlugin(${names.pluginVarName})).toBe(true);
+  });
+
+  it("has the correct name", () => {
+    expect(${names.pluginVarName}.name).toBe("${name}");
+  });
+
+  it("has a serializer", () => {
+    expect(${names.pluginVarName}.serializer).toBeDefined();
+  });
+});
+`;
+}
+export function generateSerializerTestTs(name, names) {
+    return `import { describe, expect, it } from "vitest";
+import { ${names.serializerVarName} } from "./serializer";
+
+describe("${name} serializer", () => {
+  it("serializes an empty map to valid JSON", () => {
+    const result = ${names.serializerVarName}.serialize(new Map());
+    expect(typeof result).toBe("string");
+    expect(() => JSON.parse(result)).not.toThrow();
+  });
+
+  it("has the correct name", () => {
+    expect(${names.serializerVarName}.name).toBe("${name}");
+  });
+});
+`;
+}
+export function generateCompletionsTestTs() {
+    return `import { describe, expect, it } from "vitest";
+import { completions } from "./completions";
+
+describe("LSP completions", () => {
+  it("returns an array", () => {
+    // TODO: Replace with a real CompletionContext
+    const result = completions({} as any);
+    expect(Array.isArray(result)).toBe(true);
+  });
+});
+`;
+}
+export function generateHoverTestTs() {
+    return `import { describe, expect, it } from "vitest";
+import { hover } from "./hover";
+
+describe("LSP hover", () => {
+  it("returns undefined for unknown context", () => {
+    // TODO: Replace with a real HoverContext
+    const result = hover({} as any);
+    expect(result).toBeUndefined();
+  });
+});
+`;
+}

package/dist/cli/commands/init-lexicon.js

@@ -0,0 +1,172 @@
+import { existsSync, mkdirSync, writeFileSync, readdirSync } from "fs";
+import { join, resolve } from "path";
+import { formatSuccess, formatWarning } from "../format.js";
+// Template generators
+import { generatePluginTs, generateIndexTs } from "./init-lexicon/templates/plugin.js";
+import { generateCodegenGenerateTs, generateCodegenGenerateCliTs, generateCodegenNamingTs, generateCodegenPackageTs, generateCodegenDocsTs, generateCodegenDocsCliTs } from "./init-lexicon/templates/codegen.js";
+import { generateSpecFetchTs, generateSpecParseTs } from "./init-lexicon/templates/spec.js";
+import { generateSampleRuleTs, generateLintRulesIndexTs } from "./init-lexicon/templates/lint.js";
+import { generateLspCompletionsTs, generateLspHoverTs } from "./init-lexicon/templates/lsp.js";
+import { generatePackageJson, generateTsConfig, generateTsConfigBuild, generateJustfile, generateGitignore, generateReadme, generateSerializerTs, generateValidateTs, generateValidateCliTs, generatePackageCliTs } from "./init-lexicon/templates/project.js";
+import { generatePluginTestTs, generateSerializerTestTs, generateCompletionsTestTs, generateHoverTestTs } from "./init-lexicon/templates/tests.js";
+import { generateDocsPackageJson, generateDocsTsConfig, generateDocsAstroConfig, generateDocsContentConfig, generateDocsIndexMdx, generateDocsGettingStartedMdx } from "./init-lexicon/templates/docs.js";
+import { generateExamplePackageJson, generateExampleInfraTs } from "./init-lexicon/templates/examples.js";
+// ── Name derivation helpers ──────────────────────────────────────────
+function toCamelCase(name) {
+    return name.replace(/[-_]+(.)/g, (_, c) => c.toUpperCase());
+}
+export function deriveNames(name) {
+    const camel = toCamelCase(name);
+    return {
+        pluginVarName: `${camel}Plugin`,
+        serializerVarName: `${camel}Serializer`,
+        rulePrefix: name.toUpperCase().replace(/[^A-Z0-9]/g, "").slice(0, 3),
+        packageName: `@intentius/chant-lexicon-${name}`,
+    };
+}
+// ── writeIfNotExists ─────────────────────────────────────────────────
+function writeIfNotExists(filePath, content, relativePath, createdFiles, warnings) {
+    if (!existsSync(filePath)) {
+        writeFileSync(filePath, content);
+        createdFiles.push(relativePath);
+    }
+    else {
+        warnings.push(`${relativePath} already exists, skipping`);
+    }
+}
+// ── Main command ─────────────────────────────────────────────────────
+/**
+ * Execute the init-lexicon command.
+ */
+export async function initLexiconCommand(options) {
+    const { name } = options;
+    const names = deriveNames(name);
+    const targetDir = resolve(options.path ?? join("lexicons", name));
+    const createdFiles = [];
+    const warnings = [];
+    // Check if directory is non-empty
+    if (existsSync(targetDir)) {
+        const contents = readdirSync(targetDir);
+        const nonHiddenFiles = contents.filter((f) => !f.startsWith("."));
+        if (nonHiddenFiles.length > 0 && !options.force) {
+            return {
+                success: false,
+                createdFiles: [],
+                warnings: [],
+                error: `Directory is not empty: ${targetDir}\nUse --force to initialize anyway.`,
+            };
+        }
+        if (nonHiddenFiles.length > 0) {
+            warnings.push("Initializing in non-empty directory");
+        }
+    }
+    // Create directory structure
+    const dirs = [
+        "",
+        "src",
+        "src/codegen",
+        "src/spec",
+        "src/lint",
+        "src/lint/rules",
+        "src/lsp",
+        "src/generated",
+        "docs",
+        "docs/src",
+        "docs/src/content",
+        "docs/src/content/docs",
+        "docs/pages",
+        "examples/getting-started",
+        "examples/getting-started/src",
+    ];
+    for (const dir of dirs) {
+        const fullPath = join(targetDir, dir);
+        if (!existsSync(fullPath)) {
+            mkdirSync(fullPath, { recursive: true });
+        }
+    }
+    // File map: relative path -> content
+    const files = {
+        "src/plugin.ts": generatePluginTs(name, names),
+        "src/index.ts": generateIndexTs(names),
+        "src/serializer.ts": generateSerializerTs(name, names),
+        "src/codegen/generate.ts": generateCodegenGenerateTs(),
+        "src/codegen/generate-cli.ts": generateCodegenGenerateCliTs(),
+        "src/codegen/naming.ts": generateCodegenNamingTs(),
+        "src/codegen/package.ts": generateCodegenPackageTs(name),
+        "src/codegen/docs.ts": generateCodegenDocsTs(name),
+        "src/codegen/docs-cli.ts": generateCodegenDocsCliTs(),
+        "src/spec/fetch.ts": generateSpecFetchTs(),
+        "src/spec/parse.ts": generateSpecParseTs(),
+        "src/lint/rules/sample.ts": generateSampleRuleTs(names),
+        "src/lint/rules/index.ts": generateLintRulesIndexTs(),
+        "src/lsp/completions.ts": generateLspCompletionsTs(name),
+        "src/lsp/hover.ts": generateLspHoverTs(name),
+        "src/lsp/completions.test.ts": generateCompletionsTestTs(),
+        "src/lsp/hover.test.ts": generateHoverTestTs(),
+        "src/plugin.test.ts": generatePluginTestTs(name, names),
+        "src/serializer.test.ts": generateSerializerTestTs(name, names),
+        "src/validate.ts": generateValidateTs(name),
+        "src/validate-cli.ts": generateValidateCliTs(),
+        "src/package-cli.ts": generatePackageCliTs(),
+        "package.json": generatePackageJson(name, names),
+        "tsconfig.json": generateTsConfig(),
+        "tsconfig.build.json": generateTsConfigBuild(),
+        "justfile": generateJustfile(name),
+        ".gitignore": generateGitignore(),
+        "README.md": generateReadme(name, names),
+        "docs/package.json": generateDocsPackageJson(name),
+        "docs/tsconfig.json": generateDocsTsConfig(),
+        "docs/astro.config.mjs": generateDocsAstroConfig(name),
+        "docs/src/content.config.ts": generateDocsContentConfig(),
+        "docs/src/content/docs/index.mdx": generateDocsIndexMdx(name),
+        "docs/pages/getting-started.mdx": generateDocsGettingStartedMdx(name),
+        "examples/getting-started/package.json": generateExamplePackageJson(name),
+        "examples/getting-started/src/infra.ts": generateExampleInfraTs(name, names),
+    };
+    // Write .gitkeep files
+    const gitkeeps = [
+        "src/generated/.gitkeep",
+    ];
+    for (const gk of gitkeeps) {
+        const fullPath = join(targetDir, gk);
+        if (!existsSync(fullPath)) {
+            writeFileSync(fullPath, "");
+            createdFiles.push(gk);
+        }
+    }
+    // Write all template files
+    for (const [relativePath, content] of Object.entries(files)) {
+        writeIfNotExists(join(targetDir, relativePath), content, relativePath, createdFiles, warnings);
+    }
+    return {
+        success: true,
+        createdFiles,
+        warnings,
+    };
+}
+/**
+ * Print the result of init-lexicon and show next steps.
+ */
+export async function printInitLexiconResult(result) {
+    if (!result.success) {
+        console.error(result.error);
+        return;
+    }
+    for (const warning of result.warnings) {
+        console.error(formatWarning({ message: warning }));
+    }
+    if (result.createdFiles.length > 0) {
+        console.log(formatSuccess("Created:"));
+        for (const file of result.createdFiles) {
+            console.log(`  ${file}`);
+        }
+    }
+    console.log("");
+    console.log("Next steps:");
+    console.log("  1. cd into the lexicon directory");
+    console.log("  2. npm install");
+    console.log("  3. Edit src/spec/fetch.ts — point at your upstream schema source");
+    console.log("  4. Edit src/spec/parse.ts — parse your schema format");
+    console.log("  5. just generate — generate types from spec");
+    console.log("  6. just validate — check generated artifacts");
+}