@konvert7/klint 0.38.0 → 1.0.1

package/cli/command.ts

@@ -1,189 +0,0 @@
-interface OptionSpec {
-  description: string;
-  value?: string;
-  short?: string;
-  aliases?: string[];
-}
-
-type OptionSpecs = Record<string, OptionSpec>;
-export type OptionValues = Record<string, string | true | undefined>;
-
-interface Leaf {
-  kind: "leaf";
-  summary: string;
-  options: OptionSpecs;
-  details?: () => string[];
-  run(values: OptionValues): unknown;
-}
-
-export interface Group {
-  kind: "group";
-  summary: string;
-  commands: Record<string, Leaf>;
-  aliases?: Record<string, string>;
-  defaultCommand?: Leaf;
-  details?: () => string[];
-}
-
-export type Command = Leaf | Group;
-
-const HELP_FLAGS = new Set(["-h", "--help"]);
-const HELP_WORD = "help";
-const HELP_OPTION: OptionSpec = { short: "h", description: "Show this help" };
-
-interface ParsedOptions {
-  values: OptionValues;
-  positionals: string[];
-  help: boolean;
-  error?: string;
-  rest: string[];
-}
-
-function findOption(
-  options: OptionSpecs,
-  token: string
-): [string, OptionSpec] | undefined {
-  return Object.entries(options).find(
-    ([name, spec]) =>
-      token === `--${name}` ||
-      (spec.short !== undefined && token === `-${spec.short}`) ||
-      (spec.aliases?.includes(token) ?? false)
-  );
-}
-
-function parseOptions(
-  args: string[],
-  options: OptionSpecs,
-  stopAtPositional: boolean
-): ParsedOptions {
-  const parsed: ParsedOptions = { values: {}, positionals: [], help: false, rest: [] };
-  for (let i = 0; i < args.length; i++) {
-    const token = args[i];
-    const match = findOption(options, token);
-    if (HELP_FLAGS.has(token)) {
-      parsed.help = true;
-    } else if (match?.[1].value !== undefined) {
-      const [name, spec] = match;
-      const value = args[i + 1];
-      if (value === undefined) parsed.error ??= `option '--${name}' needs ${spec.value}`;
-      else parsed.values[name] = value;
-      i++;
-    } else if (match) {
-      parsed.values[match[0]] = true;
-    } else if (token.startsWith("-")) {
-      parsed.error ??= `unknown option '${token}'`;
-    } else if (stopAtPositional) {
-      parsed.positionals.push(token);
-      parsed.rest = args.slice(i + 1);
-      return parsed;
-    } else {
-      parsed.positionals.push(token);
-    }
-  }
-  return parsed;
-}
-
-export async function runCommand(
-  command: Command,
-  args: string[],
-  path: string[]
-): Promise<number> {
-  return command.kind === "group"
-    ? runGroup(command, args, path)
-    : runLeaf(command, args, helpText(command, path));
-}
-
-async function runGroup(group: Group, args: string[], path: string[]): Promise<number> {
-  const help = helpText(group, path);
-  const parsed = parseOptions(args, group.defaultCommand?.options ?? {}, true);
-  const [name] = parsed.positionals;
-  if (parsed.help || name === HELP_WORD || group.aliases?.[name] === HELP_WORD) {
-    return showHelp(help);
-  }
-  if (name !== undefined) {
-    const sub = group.commands[group.aliases?.[name] ?? name];
-    if (!sub) return usageFailure(`unknown command '${name}'`, help);
-    if (parsed.error) return usageFailure(parsed.error, help);
-    return runCommand(sub, parsed.rest, [...path, name]);
-  }
-  if (!group.defaultCommand) return showHelp(help);
-  return runLeaf(group.defaultCommand, args, help);
-}
-
-async function runLeaf(leaf: Leaf, args: string[], help: string): Promise<number> {
-  const parsed = parseOptions(args, leaf.options, false);
-  if (parsed.help || parsed.positionals.includes(HELP_WORD)) return showHelp(help);
-  if (parsed.error) return usageFailure(parsed.error, help);
-  const [extra] = parsed.positionals;
-  if (extra !== undefined) return usageFailure(`unexpected argument '${extra}'`, help);
-  const result = await leaf.run(parsed.values);
-  return typeof result === "number" ? result : 0;
-}
-
-function showHelp(help: string): number {
-  process.stdout.write(`${help}\n`);
-  return 0;
-}
-
-function usageFailure(message: string, help: string): number {
-  process.stderr.write(`error: ${message}\n\n${help}\n`);
-  return 1;
-}
-
-function helpText(command: Command, path: string[]): string {
-  return command.kind === "group" ? groupHelp(command, path) : leafHelp(command, path);
-}
-
-function optionLabel(name: string, spec: OptionSpec): string {
-  const short = spec.short ? `-${spec.short}, ` : "";
-  const value = spec.value ? ` ${spec.value}` : "";
-  return `${short}--${name}${value}`;
-}
-
-function optionRows(options: OptionSpecs): string[] {
-  return table(
-    Object.entries({ ...options, help: HELP_OPTION }).map(([name, spec]) => [
-      optionLabel(name, spec),
-      spec.description,
-    ])
-  );
-}
-
-function leafHelp(leaf: Leaf, path: string[]): string {
-  return [
-    `Usage: ${path.join(" ")} [options]`,
-    "",
-    `  ${leaf.summary}`,
-    "",
-    "Options:",
-    ...optionRows(leaf.options),
-    ...detailLines(leaf.details),
-  ].join("\n");
-}
-
-function groupHelp(group: Group, path: string[]): string {
-  const fallback = group.defaultCommand;
-  const synopsis = fallback ? `[<command>] [options]` : "<command>";
-  return [
-    `Usage: ${path.join(" ")} ${synopsis}`,
-    "",
-    `  ${group.summary}`,
-    "",
-    "Commands:",
-    ...table(Object.entries(group.commands).map(([name, sub]) => [name, sub.summary])),
-    ...(fallback ? ["", "Options:", ...optionRows(fallback.options)] : []),
-    "",
-    ...(fallback ? [`With no command, ${fallback.summary.toLowerCase()}.`] : []),
-    `Run '${path.join(" ")} <command> --help' for its options.`,
-    ...detailLines(group.details),
-  ].join("\n");
-}
-
-function detailLines(details: (() => string[]) | undefined): string[] {
-  return details ? ["", ...details()] : [];
-}
-
-function table(rows: string[][]): string[] {
-  const width = Math.max(...rows.map(([label]) => label.length));
-  return rows.map(([label, text]) => `  ${label.padEnd(width)}  ${text}`);
-}

package/cli/commands.ts

@@ -1,90 +0,0 @@
-import { AGENT_SKILL_DIRS } from "../core/skill";
-import type { Group, OptionValues } from "./command";
-import { builtInRuleLines } from "./help";
-
-interface CommandHandlers {
-  lint(values: OptionValues): unknown;
-  stats(values: OptionValues): unknown;
-  installSkill(values: OptionValues): unknown;
-}
-
-export function klintCommand(handlers: CommandHandlers): Group {
-  return {
-    kind: "group",
-    summary:
-      "Architecture-as-Code linter: layer boundaries, import rules and forbidden patterns",
-    aliases: { h: "help" },
-    defaultCommand: {
-      kind: "leaf",
-      summary: "Lints the project",
-      options: {
-        config: {
-          value: "<dir>",
-          description:
-            "Directory containing klint.yaml or klint.config.json (default: cwd)",
-        },
-        rules: {
-          value: "<file>",
-          description:
-            "Custom rules file (default: <configDir>/klint.rules.ts if present)",
-        },
-        engine: {
-          value: "<name>",
-          description:
-            "Engine to use: ts (default), rust, compare, or auto (experimental)",
-        },
-        fix: { description: "Apply auto-fixes for fixable violations in place" },
-        json: { description: "Emit structured JSON to stdout (for agent and CI use)" },
-        debug: {
-          aliases: ["-debug"],
-          description: "Print file resolution and rule progress to stderr",
-        },
-        hook: { description: "Count this run as an agent hook run in klint stats" },
-        version: { short: "V", description: "Print the installed klint version" },
-      },
-      run: handlers.lint,
-    },
-    commands: {
-      stats: {
-        kind: "leaf",
-        summary:
-          "Print runs, violations reported and errors prevented, in total and per rule",
-        options: {
-          config: {
-            value: "<dir>",
-            description: "Directory holding .klint/stats.json (default: cwd)",
-          },
-        },
-        details: () => ["Set KLINT_NO_STATS=1 to stop recording."],
-        run: handlers.stats,
-      },
-      "install-skill": {
-        kind: "leaf",
-        summary: "Install the rule-authoring skill into agent config directories",
-        options: {
-          agents: {
-            value: "<list>",
-            description: `Comma-separated: ${Object.keys(AGENT_SKILL_DIRS).join(",")} (default: all)`,
-          },
-          symlink: {
-            aliases: ["--shared"],
-            description:
-              "Keep one skill in .agents/skills and symlink the others to it (default)",
-          },
-          copy: { description: "Give every agent directory its own copy" },
-          force: { description: "Replace a skill directory klint did not install" },
-        },
-        details: () => [
-          "Asks which agents and how to store the skill when run on a terminal without",
-          "--agents, --symlink or --copy.",
-          "",
-          "Installed skills record the version and hash they came from. klint warns with",
-          "klint/skill-stale once the shipped skill moves on, and with",
-          "klint/skill-legacy-link for old symlinks that point into node_modules.",
-        ],
-        run: handlers.installSkill,
-      },
-    },
-    details: builtInRuleLines,
-  };
-}

package/cli/help.ts

@@ -1,21 +0,0 @@
-import { BUILT_IN_PLUGINS } from "../plugins/index";
-import { BUILT_IN_RULES } from "../rules/index";
-
-export function builtInRuleLines(): string[] {
-  const pluginRules = new Set(
-    Object.values(BUILT_IN_PLUGINS).flatMap((p) => Object.keys(p.rules))
-  );
-  const standaloneRules = Object.keys(BUILT_IN_RULES).filter((r) => !pluginRules.has(r));
-  const pluginEntries = Object.entries(BUILT_IN_PLUGINS);
-
-  return [
-    `Built-in rules (${standaloneRules.length}):`,
-    ...standaloneRules.map((r) => `  ${r}`),
-    "",
-    `Plugins (${pluginEntries.length}):`,
-    ...pluginEntries.flatMap(([name, plugin]) => [
-      `  ${name}`,
-      ...Object.keys(plugin.rules).map((r) => `    ${r}`),
-    ]),
-  ];
-}

package/cli/install-skill.ts

@@ -1,260 +0,0 @@
-import { existsSync } from "node:fs";
-import { cp, lstat, mkdir, readFile, rm, symlink, writeFile } from "node:fs/promises";
-import { dirname, join, relative, resolve } from "node:path";
-import * as clack from "@clack/prompts";
-import {
-  AGENT_SKILL_DIRS,
-  type AgentKey,
-  agentSkillDirs,
-  CANONICAL_SKILL_DIR,
-  RECEIPT_FILE_NAME,
-  SKILL_DIR_NAME,
-  SKILL_FILE_NAME,
-  type SkillReceipt,
-  skillHash,
-} from "../core/skill";
-import type { OptionValues } from "./command";
-import { installedVersion, PACKAGE_ROOT } from "./paths";
-
-const AGENT_TARGETS = [
-  { value: "claude", label: "Claude Code" },
-  { value: "opencode", label: "opencode" },
-  { value: "cursor", label: "Cursor" },
-  { value: "codex", label: "Codex" },
-  { value: "copilot", label: "GitHub Copilot" },
-] as const satisfies ReadonlyArray<{ value: AgentKey; label: string }>;
-
-interface InstallPlan {
-  agents: AgentKey[];
-  shared: boolean;
-  force: boolean;
-}
-
-export async function installSkill(values: OptionValues): Promise<void> {
-  const skillSrc = join(PACKAGE_ROOT, "skill", SKILL_DIR_NAME);
-  if (!existsSync(skillSrc)) {
-    process.stderr.write(`klint: skill source not found at ${skillSrc}\n`);
-    process.exit(1);
-  }
-
-  const plan = await resolvePlan(values);
-  const dirs = agentSkillDirs(plan.agents);
-
-  try {
-    const report = plan.shared
-      ? await installShared({ dirs, force: plan.force, skillSrc })
-      : await installCopies({ dirs, force: plan.force, skillSrc });
-    for (const line of report) process.stdout.write(`klint: ${line}\n`);
-  } catch (error) {
-    process.stderr.write(`${(error as Error).message}\n`);
-    process.exit(1);
-  }
-
-  if (process.stdin.isTTY) {
-    clack.outro("Done.");
-  }
-}
-
-async function installShared({
-  dirs,
-  force,
-  skillSrc,
-}: {
-  dirs: string[];
-  force: boolean;
-  skillSrc: string;
-}): Promise<string[]> {
-  const hub = join(CANONICAL_SKILL_DIR, SKILL_DIR_NAME);
-  const report = [await installCopy(hub, skillSrc, force)];
-
-  for (const dir of dirs) {
-    if (dir === CANONICAL_SKILL_DIR) continue;
-    report.push(await linkToHub(join(dir, SKILL_DIR_NAME), hub, skillSrc, force));
-  }
-  return report;
-}
-
-async function installCopies({
-  dirs,
-  force,
-  skillSrc,
-}: {
-  dirs: string[];
-  force: boolean;
-  skillSrc: string;
-}): Promise<string[]> {
-  const report: string[] = [];
-  for (const dir of dirs) {
-    report.push(await installCopy(join(dir, SKILL_DIR_NAME), skillSrc, force));
-  }
-  return report;
-}
-
-async function installCopy(
-  target: string,
-  skillSrc: string,
-  force: boolean
-): Promise<string> {
-  const dest = resolve(process.cwd(), target);
-  await prepareDestination(dest, target, force);
-  await cp(skillSrc, dest, { recursive: true });
-  await writeReceipt(dest, skillSrc);
-  return `installed ${target}`;
-}
-
-async function linkToHub(
-  target: string,
-  hub: string,
-  skillSrc: string,
-  force: boolean
-): Promise<string> {
-  const dest = resolve(process.cwd(), target);
-  await prepareDestination(dest, target, force);
-
-  const absoluteHub = resolve(process.cwd(), hub);
-  const linkPath = relative(dirname(dest), absoluteHub);
-  if (await linkResolves(linkPath, dest, "dir")) return `linked ${target} -> ${linkPath}`;
-  if (await linkResolves(absoluteHub, dest, "junction"))
-    return `linked ${target} -> ${hub}`;
-
-  await cp(skillSrc, dest, { recursive: true });
-  await writeReceipt(dest, skillSrc);
-  return `installed ${target} (symlinks unavailable here)`;
-}
-
-async function linkResolves(
-  linkTarget: string,
-  dest: string,
-  type: "dir" | "junction"
-): Promise<boolean> {
-  try {
-    await symlink(linkTarget, dest, type);
-    if (existsSync(join(dest, SKILL_FILE_NAME))) return true;
-  } catch {
-    /* try the next strategy */
-  }
-  await rm(dest, { force: true, recursive: true });
-  return false;
-}
-
-async function prepareDestination(
-  dest: string,
-  target: string,
-  force: boolean
-): Promise<void> {
-  await mkdir(dirname(dest), { recursive: true });
-
-  const existing = await lstat(dest).catch(() => undefined);
-  if (existing === undefined) return;
-
-  if (!existing.isDirectory() || existsSync(join(dest, RECEIPT_FILE_NAME)) || force) {
-    await rm(dest, { force: true, recursive: true });
-    return;
-  }
-
-  throw new Error(
-    `klint: ${target} exists and was not installed by klint — pass --force to replace it`
-  );
-}
-
-async function writeReceipt(dest: string, skillSrc: string): Promise<void> {
-  const receipt: SkillReceipt = {
-    version: installedVersion(),
-    sha256: skillHash(await readFile(join(skillSrc, SKILL_FILE_NAME))),
-  };
-  await writeFile(join(dest, RECEIPT_FILE_NAME), `${JSON.stringify(receipt, null, 2)}\n`);
-}
-
-async function resolvePlan(values: OptionValues): Promise<InstallPlan> {
-  const flags = parseFlags(values);
-  const decided = flags.agents !== undefined || flags.shared !== undefined;
-
-  if (!process.stdin.isTTY || decided) {
-    return {
-      agents: flags.agents ?? everyAgent(),
-      shared: flags.shared ?? true,
-      force: flags.force,
-    };
-  }
-
-  clack.intro("klint install-skill");
-  return {
-    agents: await promptForAgents(),
-    shared: await promptForShared(),
-    force: flags.force,
-  };
-}
-
-function parseFlags(values: OptionValues): {
-  agents?: AgentKey[];
-  shared?: boolean;
-  force: boolean;
-} {
-  return {
-    agents: typeof values.agents === "string" ? parseAgents(values.agents) : undefined,
-    shared: sharedChoice(values),
-    force: values.force === true,
-  };
-}
-
-function sharedChoice(values: OptionValues): boolean | undefined {
-  if (values.copy) return false;
-  return values.symlink ? true : undefined;
-}
-
-function parseAgents(value: string): AgentKey[] {
-  return value
-    .split(",")
-    .map((agent) => agent.trim())
-    .filter((agent) => agent.length > 0)
-    .map((agent) => {
-      if (!(agent in AGENT_SKILL_DIRS)) {
-        process.stderr.write(
-          `klint: unknown agent "${agent}" (expected one of: ${everyAgent().join(", ")})\n`
-        );
-        process.exit(1);
-      }
-      return agent as AgentKey;
-    });
-}
-
-function everyAgent(): AgentKey[] {
-  return AGENT_TARGETS.map((target) => target.value);
-}
-
-async function promptForAgents(): Promise<AgentKey[]> {
-  const agents = await clack.multiselect<AgentKey>({
-    message: "Which agents should the skill be installed for?",
-    options: AGENT_TARGETS.map((a) => ({ value: a.value, label: a.label })),
-    initialValues: everyAgent(),
-  });
-  if (clack.isCancel(agents)) {
-    clack.cancel("Cancelled.");
-    process.exit(0);
-  }
-  return agents as AgentKey[];
-}
-
-async function promptForShared(): Promise<boolean> {
-  const mode = await clack.select<"shared" | "copy">({
-    message: "How should the skill be stored?",
-    initialValue: "shared",
-    options: [
-      {
-        value: "shared",
-        label: "Shared (recommended)",
-        hint: `one skill in ${CANONICAL_SKILL_DIR}, other agents symlink to it`,
-      },
-      {
-        value: "copy",
-        label: "Separate copies",
-        hint: "an independent copy in every agent directory",
-      },
-    ],
-  });
-  if (clack.isCancel(mode)) {
-    clack.cancel("Cancelled.");
-    process.exit(0);
-  }
-  return mode === "shared";
-}