@vertekum/schema-builder 0.1.7 → 0.2.0

package/src/cli.ts

@@ -1,10 +1,18 @@
-import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { basename, dirname, isAbsolute, join, relative } from 'node:path';
 import type { CommandDescriptor, CommandResult } from '@vertekum/core';
-import { assertOpenSetsAreNameSets, build } from './build';
+import {
+  assertOpenSetsAreNameSets,
+  build,
+  evaluateProduction,
+  type PatternRef,
+  type TreeNode,
+} from './build';
 import { emit, isStamped } from './emit';
+import { DfnError } from './error';
+import { fixSource, formatSource, resolveIndent } from './format';
 import { lintModule } from './lint';
-import { resolveModule } from './resolve';
+import { type ResolvedModule, resolveModule } from './resolve';
 
 /**
  * `vertekum schema build [module]` (ADR-0030): expand `.dfn` modules and DECLARE the built JSON
@@ -17,6 +25,32 @@ import { resolveModule } from './resolve';
 /** The slice of the CLI's Project this command reads. */
 interface ProjectDir {
   projectDir: string;
+  /** The consumer's `format.indent`, when set — fmt honors it (JSON writes already do). */
+  indent?: string | number;
+  /** The kernel's config store — where this extension's own settings slice lives. */
+  kernel?: { config: { get<T>(id: string): T } };
+}
+
+/** The extension's configured input/output pair, defaults included. */
+function settingsOf(ctx: { project: unknown }): {
+  source: string;
+  out?: string;
+  link: boolean;
+  schemaId?: string;
+} {
+  const kernel = (ctx.project as ProjectDir).kernel;
+  const slice = kernel?.config.get<{
+    source?: string;
+    out?: string;
+    link?: boolean;
+    schemaId?: string;
+  }>('vtk.schema-builder');
+  return {
+    source: slice?.source ?? './schemas',
+    out: slice?.out,
+    link: slice?.link === true,
+    schemaId: slice?.schemaId,
+  };
 }
 
 function modulesUnder(dir: string): string[] {
@@ -26,22 +60,125 @@ function modulesUnder(dir: string): string[] {
     .map((f) => join(dir, f));
 }
 
-export function buildModule(
-  modulePath: string,
+/**
+ * What a command's `[module]` argument means: nothing → the default sweep (`./schemas`);
+ * a directory → sweep it; a file → that module alone (`explicitFile` — build's rootless
+ * error applies only there). A path that exists as neither is an error up front.
+ */
+function resolveModules(
+  projectDir: string,
+  arg: string | undefined,
+  sourceDefault: string,
+): { modules: string[]; explicitFile: boolean; root: string } {
+  if (!arg) {
+    const root = join(projectDir, sourceDefault);
+    return { modules: modulesUnder(root), explicitFile: false, root };
+  }
+  const target = join(projectDir, arg);
+  if (!existsSync(target)) {
+    throw new Error(`no such file or directory: ${arg}`);
+  }
+  if (statSync(target).isDirectory()) {
+    return { modules: modulesUnder(target), explicitFile: false, root: target };
+  }
+  return { modules: [target], explicitFile: true, root: dirname(target) };
+}
+
+/** A module's NATURE: the `scope` pragma, defaulted by root presence. */
+export function natureOf(
+  resolved: ResolvedModule,
+): 'document' | 'def' | 'inline' {
+  return (
+    resolved.module.meta.scope ?? (resolved.module.root ? 'document' : 'def')
+  );
+}
+
+export interface BuildModuleOptions {
   /** The module name the provenance stamp records; default: the basename. Pass a relative
    *  path when modules nest, so same-named modules stamp distinguishably. */
-  moduleLabel?: string,
+  label?: string;
+  /** Where the artifact lands; default: beside the module. */
+  targetDir?: string;
+  /** Derived `$id` for this artifact (configured base + path); the `id` pragma wins. */
+  schemaId?: string;
+  /** Linked emission: resolve a module to the artifact path a cross-file `$ref` should use. */
+  linkResolve?: (module: ResolvedModule) => string | undefined;
+}
+
+export function buildModule(
+  modulePath: string,
+  options: BuildModuleOptions = {},
 ): {
   target: string;
   content: string;
 } {
   const resolved = resolveModule(modulePath);
   assertOpenSetsAreNameSets(resolved);
-  const tree = build(resolved);
-  const moduleFile = moduleLabel ?? basename(modulePath);
+  const nature = natureOf(resolved);
+  if (nature === 'inline') {
+    throw new DfnError(
+      `${resolved.name}.dfn is scope "inline" — it is never emitted`,
+      1,
+      1,
+      resolved.path,
+    );
+  }
+  if (nature === 'document' && !resolved.module.root) {
+    throw new DfnError(
+      `scope "document" requires a root — ${resolved.name}.dfn declares none`,
+      1,
+      1,
+      resolved.path,
+    );
+  }
+
+  const tree = resolved.module.root ? build(resolved) : undefined;
+
+  // Public patterns in declaration order, bare-evaluated; plus a memoized provider for
+  // emission's deep-checks (covering cross-module patterns and def-scope roots).
+  const patterns = new Map<string, TreeNode>();
+  for (const name of resolved.module.productions.keys()) {
+    if (resolved.module.private.has(name)) continue;
+    patterns.set(name, evaluateProduction(resolved, name));
+  }
+  const bareMemo = new Map<string, TreeNode | undefined>();
+  const bare = (ref: PatternRef): TreeNode | undefined => {
+    const key = ref.module
+      ? `@${ref.module.path}/${ref.root ? '/root' : ref.name}`
+      : ref.name;
+    if (!bareMemo.has(key)) {
+      let value: TreeNode | undefined;
+      if (!ref.module) value = patterns.get(ref.name);
+      else if (ref.root) value = build(ref.module);
+      else value = evaluateProduction(ref.module, ref.name);
+      bareMemo.set(key, value);
+    }
+    return bareMemo.get(key);
+  };
+
+  const moduleFile = options.label ?? basename(modulePath);
+  const meta = resolved.module.meta;
   return {
-    target: join(dirname(modulePath), `${resolved.name}.json`),
-    content: emit(tree, { moduleFile, ...resolved.module.meta }),
+    target: join(
+      options.targetDir ?? dirname(modulePath),
+      `${resolved.name}.json`,
+    ),
+    content: emit(tree, {
+      moduleFile,
+      id: meta.id,
+      schemaId: options.schemaId,
+      title: meta.title,
+      description: meta.description,
+      scopeKind: nature,
+      // A def file is pattern-natured: its body stays unsealed unless the author seals it,
+      // so consumers can whole-file-compose it. A document validates alone: sealed.
+      sealed: meta.sealed ?? nature === 'document',
+      patterns,
+      rootDefName:
+        nature === 'def' && resolved.module.root ? 'root' : undefined,
+      bare,
+      linkResolve: options.linkResolve,
+    }),
   };
 }
 
@@ -59,41 +196,169 @@ export const schemaLintCommand: CommandDescriptor = {
     {
       name: 'module',
       required: false,
-      description: "a .dfn file; default: every module under './schemas'",
+      description:
+        "a .dfn file or directory; default: every module under './schemas'",
+    },
+  ],
+  options: [
+    {
+      flag: '--fix',
+      description: "apply mechanical repairs (a misplaced '*') before linting",
     },
   ],
   run(ctx): CommandResult {
     const { projectDir } = ctx.project as ProjectDir;
-    const modules = ctx.args.module
-      ? [join(projectDir, ctx.args.module)]
-      : modulesUnder(join(projectDir, 'schemas'));
+    const { modules } = resolveModules(
+      projectDir,
+      ctx.args.module,
+      settingsOf(ctx).source,
+    );
     if (modules.length === 0) {
       return { summary: 'no .dfn modules found' };
     }
 
     const project = (file: string) =>
       isAbsolute(file) ? relative(projectDir, file) : file;
-    const diagnostics = modules.flatMap((modulePath) =>
-      lintModule(modulePath).map((d) => ({ ...d, file: project(d.file) })),
+
+    // --fix first: repaired content is linted IN MEMORY (the runner owns writing), so the
+    // remaining diagnostics describe the state the fix would leave on disk.
+    const files: Array<{ path: string; content: string }> = [];
+    const fixed: string[] = [];
+    const sources = new Map<string, string>();
+    if (ctx.options.fix === true) {
+      for (const modulePath of modules) {
+        if (!existsSync(modulePath)) continue;
+        const source = readFileSync(modulePath, 'utf8');
+        const result = fixSource(source);
+        if (result.fixes.length === 0) continue;
+        sources.set(modulePath, result.content);
+        files.push({ path: project(modulePath), content: result.content });
+        for (const fix of result.fixes) {
+          fixed.push(
+            `${project(modulePath)}:${fix.line}:${fix.column} ${fix.message}`,
+          );
+        }
+      }
+    }
+
+    const found = modules.flatMap((modulePath) =>
+      lintModule(modulePath, sources).map((d) => ({
+        ...d,
+        file: project(d.file),
+      })),
     );
+    const warningLine = (d: (typeof found)[number]) =>
+      `  ${d.file}:${d.line}:${d.column} warning: ${d.message}`;
+    const warnings = found.filter((d) => d.severity === 'warning');
+    const diagnostics = found.filter((d) => d.severity !== 'warning');
 
     if (diagnostics.length > 0) {
       throw new Error(
         [
+          ...(fixed.length > 0
+            ? [`fixed ${fixed.length}:`, ...fixed.map((f) => `  ${f}`)]
+            : []),
           `${diagnostics.length} problem(s) in the .dfn modules:`,
           ...diagnostics.map(
             (d) => `  ${d.file}:${d.line}:${d.column} ${d.message}`,
           ),
+          ...warnings.map(warningLine),
         ].join('\n'),
       );
     }
+    const notes = [
+      ...(fixed.length > 0
+        ? [`fixed ${fixed.length} problem(s):`, ...fixed.map((f) => `  ${f}`)]
+        : []),
+      ...warnings.map(warningLine),
+      `${modules.length} module(s) clean${warnings.length > 0 ? `, ${warnings.length} warning(s)` : ''}`,
+    ];
     return {
-      summary: `${modules.length} module(s) clean`,
-      data: { modules: modules.map(project) },
+      summary: notes.join('\n'),
+      files,
+      data: { modules: modules.map(project), fixed, warnings },
     };
   },
 };
 
+/**
+ * `vertekum schema fmt [module]`: canonical formatting for the `.dfn` sources — block indent
+ * from `format.indent`/.editorconfig, canonical spacing, hygiene. A module whose grammar cannot
+ * be lexed is skipped with a notice (broken grammar is lint's report — fmt never rewrites what
+ * it cannot read). `--check` verifies instead of writing: the CI gate.
+ */
+export const schemaFmtCommand: CommandDescriptor = {
+  name: 'schema fmt',
+  description: 'format .dfn vocabulary modules canonically',
+  args: [
+    {
+      name: 'module',
+      required: false,
+      description:
+        "a .dfn file or directory; default: every module under './schemas'",
+    },
+  ],
+  options: [
+    {
+      flag: '--check',
+      description: 'verify formatting; write nothing',
+    },
+  ],
+  run(ctx): CommandResult {
+    const { projectDir, indent } = ctx.project as ProjectDir;
+    const { modules } = resolveModules(
+      projectDir,
+      ctx.args.module,
+      settingsOf(ctx).source,
+    );
+    if (modules.length === 0) {
+      return { summary: 'no .dfn modules found', files: [] };
+    }
+
+    const project = (file: string) =>
+      isAbsolute(file) ? relative(projectDir, file) : file;
+    const files: Array<{ path: string; content: string }> = [];
+    const skipped: string[] = [];
+    const unformatted: string[] = [];
+
+    for (const modulePath of modules) {
+      const source = readFileSync(modulePath, 'utf8');
+      let formatted: string;
+      try {
+        formatted = formatSource(source, {
+          indent: resolveIndent(modulePath, indent),
+        });
+      } catch (error) {
+        skipped.push(
+          `${project(modulePath)} does not lex (${error instanceof Error ? error.message : String(error)}) — run \`vertekum schema lint\``,
+        );
+        continue;
+      }
+      if (formatted === source) continue;
+      if (ctx.options.check === true) {
+        unformatted.push(project(modulePath));
+        continue;
+      }
+      files.push({ path: project(modulePath), content: formatted });
+    }
+
+    if (unformatted.length > 0) {
+      throw new Error(
+        `unformatted .dfn modules: ${unformatted.join(', ')} — run \`vertekum schema fmt\``,
+      );
+    }
+    const notes = [
+      ctx.options.check === true
+        ? `${modules.length - skipped.length} module(s) formatted`
+        : files.length > 0
+          ? `formatted ${files.length} module(s)`
+          : `${modules.length - skipped.length} module(s) already formatted`,
+      ...skipped,
+    ];
+    return { summary: notes.join('\n'), files, data: { skipped } };
+  },
+};
+
 export const schemaBuildCommand: CommandDescriptor = {
   name: 'schema build',
   description: 'build .dfn vocabulary modules into JSON Schema files',
@@ -101,7 +366,14 @@ export const schemaBuildCommand: CommandDescriptor = {
     {
       name: 'module',
       required: false,
-      description: "a .dfn file; default: every module under './schemas'",
+      description:
+        "a .dfn file or directory; default: the configured source ('./schemas')",
+    },
+    {
+      name: 'out',
+      required: false,
+      description:
+        'output directory for this run; default: the configured out, else beside each module',
     },
   ],
   options: [
@@ -112,30 +384,86 @@ export const schemaBuildCommand: CommandDescriptor = {
   ],
   run(ctx): CommandResult {
     const { projectDir } = ctx.project as ProjectDir;
-    const modules = ctx.args.module
-      ? [join(projectDir, ctx.args.module)]
-      : modulesUnder(join(projectDir, 'schemas'));
+    const settings = settingsOf(ctx);
+    const { modules, explicitFile, root } = resolveModules(
+      projectDir,
+      ctx.args.module,
+      settings.source,
+    );
     if (modules.length === 0) {
       return { summary: 'no .dfn modules found', files: [] };
     }
 
+    // Where a module's artifact lands: the positional `[out]` pairs with THIS invocation's
+    // module root; the configured `out` pairs with the configured `source`; a module outside
+    // its pair's root builds beside itself — input and output are a pair, not a redirect.
+    const outArg = ctx.args.out as string | undefined;
+    const outDir = outArg
+      ? join(projectDir, outArg)
+      : settings.out
+        ? join(projectDir, settings.out)
+        : undefined;
+    const pairRoot = outArg ? root : join(projectDir, settings.source);
+    const targetDirFor = (modulePath: string): string | undefined => {
+      if (!outDir) return undefined;
+      if (outArg && explicitFile) return outDir;
+      const within = relative(pairRoot, dirname(modulePath));
+      if (within.startsWith('..') || isAbsolute(within)) return undefined;
+      return join(outDir, within);
+    };
+
     const files: Array<{ path: string; content: string }> = [];
     const skipped: string[] = [];
     const fragments: string[] = [];
     const stale: string[] = [];
 
     for (const modulePath of modules) {
-      // A rootless module is a FRAGMENT — imports for other modules. The sweep skips it;
+      // A `scope "inline"` module is never emitted — the sweep skips it with a notice;
       // naming one explicitly stays an error (buildModule throws), since silence there
-      // would hide a typo'd `root`.
-      if (!ctx.args.module && !resolveModule(modulePath).module.root) {
-        fragments.push(relative(projectDir, modulePath));
-        continue;
+      // would hide the wrong pragma.
+      if (!explicitFile) {
+        const resolved = resolveModule(modulePath);
+        const nature =
+          resolved.module.meta.scope ??
+          (resolved.module.root ? 'document' : 'def');
+        if (nature === 'inline') {
+          fragments.push(relative(projectDir, modulePath));
+          continue;
+        }
       }
-      const { target, content } = buildModule(
-        modulePath,
-        relative(projectDir, modulePath),
-      );
+      const parentTargetDir = targetDirFor(modulePath) ?? dirname(modulePath);
+      // Linked mode: a child links only when THIS project builds it — its artifact must be
+      // computable through the same source/out mapping. Package modules inline.
+      const linkResolve = settings.link
+        ? (child: ResolvedModule): string | undefined => {
+            const within = relative(projectDir, child.path);
+            if (within.startsWith('..') || within.includes('node_modules')) {
+              return undefined;
+            }
+            const childDir = targetDirFor(child.path) ?? dirname(child.path);
+            const ref = relative(
+              parentTargetDir,
+              join(childDir, `${child.name}.json`),
+            );
+            return ref.startsWith('.') ? ref : `./${ref}`;
+          }
+        : undefined;
+      const derivedId = settings.schemaId
+        ? settings.schemaId.replace(/\/?$/, '/') +
+          relative(
+            outDir ?? join(projectDir, settings.source),
+            join(
+              parentTargetDir,
+              `${basename(modulePath).replace(/\.dfn$/, '')}.json`,
+            ),
+          )
+        : undefined;
+      const { target, content } = buildModule(modulePath, {
+        label: relative(projectDir, modulePath),
+        targetDir: targetDirFor(modulePath),
+        schemaId: derivedId,
+        linkResolve,
+      });
       const existing = existsSync(target)
         ? readFileSync(target, 'utf8')
         : undefined;
@@ -161,7 +489,7 @@ export const schemaBuildCommand: CommandDescriptor = {
       ctx.options.check === true
         ? `${modules.length - fragments.length} module(s) current`
         : `built ${files.length} module(s)`,
-      ...fragments.map((f) => `${f} declares no root (a fragment) — skipped`),
+      ...fragments.map((f) => `${f} is scope "inline" — skipped`),
       ...skipped.map((f) => `${f} has local edits (no stamp) — left as is`),
     ];
     return { summary: notes.join('\n'), files, data: { skipped, fragments } };