@design.estate/wcctools 6.0.0 → 6.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@design.estate/wcctools",
-  "version": "6.0.0",
+  "version": "6.1.0",
   "private": false,
   "description": "A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.",
   "bin": {
@@ -20,9 +20,11 @@
     "@design.estate/dees-domtools": "^5.0.0",
     "@design.estate/dees-element": "^4.0.0",
     "@git.zone/tswatch": "^6.0.1",
+    "@push.rocks/smartconfig": "^6.3.0",
     "@push.rocks/smartconsole": "^2.1.0",
     "@push.rocks/smartexit": "^2.2.0",
-    "lit": "^3.3.2"
+    "lit": "^3.3.2",
+    "typescript": "~6.0.3"
   },
   "devDependencies": {
     "@git.zone/tsbuild": "^5.1.2",

package/readme.md

@@ -503,6 +503,39 @@ Bundles and watches the catalogue as the project's `@git.zone/tswatch` configura
 
 `--port` overrides the configured port; `0` picks a free port.
 
+Every `wcctools` command exits with code 2 on a usage error (an unknown command or option, a missing or invalid option value) and with 1 on any other failure.
+
+### `wcctools check` and `wcctools fix`
+
+Check a catalogue against the wcctools component standard ([docs/standard.md](https://code.foss.global/design.estate/wcctools/src/branch/main/docs/standard.md), a draft: rule ids, severities and defaults may still change until it is declared stable): file layout, naming, element registration, barrels, demos and the attribute surface of public properties, plus the theme, wording and component-index ratchets of the dees-catalog family. Both commands run in the repository root and read `.smartconfig.json`:
+
+```json
+{
+  "@design.estate/wcctools": {
+    "standard": {
+      "profile": "base",
+      "tagPrefix": "my"
+    }
+  }
+}
+```
+
+`profile` is `base` or `dees`; `tagPrefix` is the tag prefix without its hyphen. Exceptions go into `standard.allowlist` (rule id → `'<file>#<member>'` → `'<category>: <reason>'`), accepted error counts of an existing codebase into `standard.baselines` (rule id → file → count, only shrinking).
+
+```bash
+wcctools check                      # findings as text; exit 0 ok, 1 failing errors, 2 configuration or usage error
+wcctools check --json               # one IStandardReport on stdout
+wcctools check --verbose            # also info findings, covered findings and baseline slack
+wcctools check --init-baseline      # record the current error counts (only while no baselines exist)
+wcctools check --update-baseline    # lower the baselines to the current counts; refuses to raise any
+
+wcctools fix --dry-run              # show the moves and edits without writing
+wcctools fix                        # apply every automatic fix
+wcctools fix --rule props/reflect-primitive   # also opt-in rules, one rule at a time
+```
+
+`wcctools fix` needs a clean work tree and never commits; it validates every path it would write before writing anything and refuses (exit code 2) a plan that leaves the repository root. It edits source text by syntax-node spans, so formatting and comments stay as they are; it moves files with `git mv` and rewrites the relative imports that pointed at them across the repository, and it checks again at the end. Review the result with `git diff` and commit it yourself.
+
 ### `setupWccTools(config)`
 
 Sets up the catalogue's preview document with sections configuration. The shell reads a data-only description of the sections from it; element classes and template factories never leave the preview document.
@@ -540,7 +573,7 @@ The wrapper provides full DOM API access:
 
 ### `@design.estate/wcctools/interfaces`
 
-The contracts between the shell, the preview document and the dev server, for tools that drive a preview: the catalogue manifest (`IWccCatalogManifest`), the preview bridge the preview document installs as `window.wccPreview` (`IWccPreviewBridge`: render a demo, switch the theme, read and edit the rendered element's properties) and the dev server's typed requests.
+The contracts between the shell, the preview document and the dev server, for tools that drive a preview: the catalogue manifest (`IWccCatalogManifest`), the preview bridge the preview document installs as `window.wccPreview` (`IWccPreviewBridge`: render a demo, switch the theme, read and edit the rendered element's properties) and the dev server's typed requests, and the component standard's configuration and reports (`IStandardConfig`, `IStandardReport`, `IStandardFixResult`).
 
 ```typescript
 import type { IWccPreviewBridge } from '@design.estate/wcctools/interfaces';

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@design.estate/wcctools',
-  version: '6.0.0',
+  version: '6.1.0',
   description: 'A set of web component tools for creating element catalogues, enabling the structured development and documentation of custom elements and pages.'
 }

package/ts/cli.ts

@@ -1,6 +1,7 @@
 import * as plugins from './plugins.js';
 import { commitinfo } from './00_commitinfo_data.js';
 import { WccDevServer } from './classes.devserver.js';
+import { StandardConfigError, StandardUsageError, registerStandardCommands } from './standards/index.js';
 
 /**
  * Registers the wcctools commands on the given console.
@@ -27,6 +28,8 @@ export const registerCommands = (out: plugins.smartconsole.SmartConsole): void =
     await out.log(`wcctools dev: ${address.url}`);
   });
 
+  registerStandardCommands(out);
+
   out.cli.default({}, async () => {
     await out.log(out.cli.renderHelp());
   });
@@ -39,7 +42,11 @@ export const runCli = async () => {
     await out.cli.run();
   } catch (error) {
     await out.error(error instanceof Error ? error.message : String(error));
-    process.exitCode = 1;
+    // Configuration and usage errors exit with 2, every other failure with 1.
+    const usageError = error instanceof plugins.smartconsole.CliUsageError
+      || error instanceof StandardConfigError
+      || error instanceof StandardUsageError;
+    process.exitCode = usageError ? 2 : 1;
   } finally {
     await out.dispose();
   }

package/ts/plugins.ts

@@ -1,9 +1,11 @@
 // node native scope
+import * as childProcess from 'node:child_process';
 import * as fs from 'node:fs/promises';
+import * as fsSync from 'node:fs';
 import * as path from 'node:path';
 import * as url from 'node:url';
 
-export { fs, path, url };
+export { childProcess, fs, fsSync, path, url };
 
 // @api.global scope
 import * as typedrequest from '@api.global/typedrequest';
@@ -17,10 +19,16 @@ import * as tswatch from '@git.zone/tswatch';
 export { tswatch };
 
 // @push.rocks scope
+import * as smartconfig from '@push.rocks/smartconfig';
 import * as smartconsole from '@push.rocks/smartconsole';
 import * as smartexit from '@push.rocks/smartexit';
 
-export { smartconsole, smartexit };
+export { smartconfig, smartconsole, smartexit };
+
+// third party scope
+import typescript from 'typescript';
+
+export { typescript };
 
 // project scope
 import * as interfaces from '../ts_interfaces/index.js';

package/ts/standards/baselines.ts

@@ -0,0 +1,100 @@
+import * as plugins from '../plugins.js';
+import { allowlistStaleRuleId } from './rules/index.js';
+
+type IStandardConfig = plugins.interfaces.IStandardConfig;
+type IStandardReport = plugins.interfaces.IStandardReport;
+type TBaselines = NonNullable<IStandardConfig['baselines']>;
+
+/**
+ * Baseline arithmetic of the ratchet. Pure functions: persisting the result goes through
+ * IStandardConfigWriter (see config.ts).
+ */
+
+/** Per rule and file, the error findings a baseline would have to accept (allowlisted findings excluded). */
+const errorCounts = (reportArg: IStandardReport): TBaselines => {
+  const counts: TBaselines = {};
+  for (const finding of reportArg.findings) {
+    if (finding.severity !== 'error' || finding.covered === 'allowlist' || finding.ruleId === allowlistStaleRuleId) {
+      continue;
+    }
+    counts[finding.ruleId] ??= {};
+    counts[finding.ruleId][finding.file] = (counts[finding.ruleId][finding.file] ?? 0) + 1;
+  }
+  return counts;
+};
+
+const sortBaselines = (baselinesArg: TBaselines): TBaselines => {
+  const sorted: TBaselines = {};
+  for (const ruleId of Object.keys(baselinesArg).sort()) {
+    const files = Object.keys(baselinesArg[ruleId]).sort();
+    if (files.length > 0) {
+      sorted[ruleId] = Object.fromEntries(files.map((fileArg) => [fileArg, baselinesArg[ruleId][fileArg]]));
+    }
+  }
+  return sorted;
+};
+
+/** `--init-baseline`: the current error counts of every rule. Only valid while the configuration has no baselines. */
+export const initialBaselines = (reportArg: IStandardReport): TBaselines => sortBaselines(errorCounts(reportArg));
+
+export interface IBaselineRaise {
+  ruleId: string;
+  file: string;
+  baseline: number;
+  current: number;
+}
+
+/**
+ * `--update-baseline`: lowers every count to the current one and removes entries that reach 0.
+ * `raised` lists every file whose count would have to grow, including files without an entry;
+ * when it is not empty the update is refused.
+ */
+export const updatedBaselines = (reportArg: IStandardReport, baselinesArg: TBaselines): { baselines: TBaselines; raised: IBaselineRaise[] } => {
+  const current = errorCounts(reportArg);
+  const raised: IBaselineRaise[] = [];
+  const baselines: TBaselines = {};
+  for (const [ruleId, counts] of Object.entries(baselinesArg)) {
+    baselines[ruleId] = {};
+    for (const [file, baseline] of Object.entries(counts)) {
+      const count = current[ruleId]?.[file] ?? 0;
+      if (count > baseline) {
+        raised.push({ ruleId, file, baseline, current: count });
+      } else if (count > 0) {
+        baselines[ruleId][file] = count;
+      }
+    }
+  }
+  for (const [ruleId, counts] of Object.entries(current)) {
+    for (const [file, count] of Object.entries(counts)) {
+      if (baselinesArg[ruleId]?.[file] === undefined) {
+        raised.push({ ruleId, file, baseline: 0, current: count });
+      }
+    }
+  }
+  return { baselines: sortBaselines(baselines), raised };
+};
+
+/** The configuration with allowlist and baseline file paths moved along with `wcctools fix` moves. */
+export const rekeyStandardConfig = (configArg: IStandardConfig, movesArg: readonly plugins.interfaces.IStandardFileMove[]): { config: IStandardConfig; changed: string[] } => {
+  const moved = new Map(movesArg.map((moveArg) => [moveArg.from, moveArg.to]));
+  const changed: string[] = [];
+  const rekey = (keyArg: string): string => {
+    const [file, ...member] = keyArg.split('#');
+    const target = moved.get(file);
+    if (!target) {
+      return keyArg;
+    }
+    changed.push(keyArg);
+    return [target, ...member].join('#');
+  };
+  const config: IStandardConfig = { ...configArg };
+  if (configArg.allowlist) {
+    config.allowlist = Object.fromEntries(Object.entries(configArg.allowlist).map(([ruleId, entries]) =>
+      [ruleId, Object.fromEntries(Object.entries(entries).map(([key, value]) => [rekey(key), value]))]));
+  }
+  if (configArg.baselines) {
+    config.baselines = Object.fromEntries(Object.entries(configArg.baselines).map(([ruleId, counts]) =>
+      [ruleId, Object.fromEntries(Object.entries(counts).map(([file, count]) => [rekey(file), count]))]));
+  }
+  return { config, changed };
+};

package/ts/standards/checker.ts

@@ -0,0 +1,114 @@
+import * as plugins from '../plugins.js';
+import type { StandardProject } from './classes.standardproject.js';
+import type { ILoadedStandardConfig } from './config.js';
+import { severityIn, type IRuleFinding, type IStandardRule } from './rule.js';
+import { allowlistStaleRuleId, standardRules } from './rules/index.js';
+
+type IStandardFinding = plugins.interfaces.IStandardFinding;
+type IStandardReport = plugins.interfaces.IStandardReport;
+type TStandardProfile = plugins.interfaces.TStandardProfile;
+
+/** The rules of a profile, in the order of docs/standard.md. */
+export const rulesOfProfile = (profileArg: TStandardProfile): IStandardRule[] =>
+  standardRules.filter((ruleArg) => severityIn(ruleArg, profileArg) !== null);
+
+/** The rules of a profile as the shell and the AI agent see them. */
+export const describeStandardRules = (profileArg: TStandardProfile): plugins.interfaces.IStandardRuleInfo[] =>
+  rulesOfProfile(profileArg).map((ruleArg) => ({
+    id: ruleArg.id,
+    severity: severityIn(ruleArg, profileArg)!,
+    fixMode: ruleArg.fixMode,
+    allowlistCategories: [...(ruleArg.allowlistCategories ?? [])],
+  }));
+
+/** A finding of one rule with its allowlist state. */
+export interface IDetectedFinding {
+  rule: IStandardRule;
+  finding: IRuleFinding;
+  allowlisted: boolean;
+}
+
+/** Runs the rules of the configured profile; findings carry their fix actions. */
+export const detectFindings = (
+  projectArg: StandardProject,
+  loadedArg: ILoadedStandardConfig,
+  rulesArg: readonly IStandardRule[] = rulesOfProfile(loadedArg.profile),
+): IDetectedFinding[] => {
+  const context = { project: projectArg, config: loadedArg.config, profile: loadedArg.profile };
+  const detected: IDetectedFinding[] = [];
+  for (const rule of rulesArg) {
+    const allowlist = loadedArg.config.allowlist?.[rule.id] ?? {};
+    for (const finding of rule.detect(context)) {
+      detected.push({ rule, finding, allowlisted: Object.hasOwn(allowlist, finding.key) });
+    }
+  }
+  return detected;
+};
+
+const locate = (projectArg: StandardProject, fileArg: string, positionArg: number): { line: number; column: number } => {
+  const text = projectArg.files.get(fileArg);
+  if (text === undefined) {
+    return { line: 1, column: 1 };
+  }
+  if (/\.(ts|tsx|mts|cts)$/.test(fileArg)) {
+    return projectArg.lineAndColumn(fileArg, positionArg);
+  }
+  const before = text.slice(0, positionArg);
+  return { line: before.split('\n').length, column: positionArg - before.lastIndexOf('\n') };
+};
+
+/** Checks a repository against the standard: findings, allowlist, baselines. */
+export const checkStandard = (projectArg: StandardProject, loadedArg: ILoadedStandardConfig): IStandardReport => {
+  const { config, profile } = loadedArg;
+  const detected = detectFindings(projectArg, loadedArg);
+  const findings: IStandardFinding[] = detected.map(({ rule, finding, allowlisted }) => ({
+    ruleId: rule.id,
+    severity: severityIn(rule, profile)!,
+    file: finding.file,
+    ...locate(projectArg, finding.file, finding.position),
+    message: finding.message,
+    fixable: !!finding.fix,
+    ...(allowlisted ? { covered: 'allowlist' as const } : {}),
+  }));
+
+  // An allowlist entry without its finding is stale: the list only shrinks.
+  for (const [ruleId, entries] of Object.entries(config.allowlist ?? {})) {
+    for (const key of Object.keys(entries)) {
+      if (!detected.some(({ rule, finding }) => rule.id === ruleId && finding.key === key)) {
+        findings.push({
+          ruleId: allowlistStaleRuleId,
+          severity: 'error',
+          file: '.smartconfig.json',
+          line: 1,
+          column: 1,
+          message: `the ${ruleId} allowlist entry '${key}' matches no finding; remove it`,
+          fixable: false,
+        });
+      }
+    }
+  }
+
+  // Baselines: per rule and file, a count at or below the baseline is covered; above it nothing is.
+  const baselineSlack: plugins.interfaces.IStandardBaselineSlack[] = [];
+  for (const [ruleId, counts] of Object.entries(config.baselines ?? {})) {
+    for (const [file, baseline] of Object.entries(counts)) {
+      const inFile = findings.filter((findingArg) => findingArg.ruleId === ruleId && findingArg.file === file && !findingArg.covered);
+      if (inFile.length <= baseline) {
+        inFile.forEach((findingArg) => {
+          findingArg.covered = 'baseline';
+        });
+      }
+      if (inFile.length < baseline) {
+        baselineSlack.push({ ruleId, file, baseline, current: inFile.length });
+      }
+    }
+  }
+
+  findings.sort((a, b) => a.file.localeCompare(b.file) || a.line - b.line || a.column - b.column || a.ruleId.localeCompare(b.ruleId));
+  return {
+    profile,
+    findings,
+    baselineSlack,
+    ok: !findings.some((findingArg) => findingArg.severity === 'error' && !findingArg.covered),
+  };
+};

package/ts/standards/classes.gitrepo.ts

@@ -0,0 +1,48 @@
+import * as plugins from '../plugins.js';
+
+/** The git operations `wcctools fix` needs, run with an argument vector and no shell. */
+export class GitRepo {
+  public readonly rootDir: string;
+
+  constructor(rootDirArg: string) {
+    this.rootDir = rootDirArg;
+  }
+
+  public run(argsArg: string[]): Promise<string> {
+    return new Promise((resolve, reject) => {
+      plugins.childProcess.execFile('git', argsArg, { cwd: this.rootDir, maxBuffer: 64 * 1024 * 1024, encoding: 'utf8' }, (error, stdout, stderr) => {
+        if (error) {
+          reject(new Error(`git ${argsArg.join(' ')} failed: ${stderr.trim() || error.message}`));
+          return;
+        }
+        resolve(stdout);
+      });
+    });
+  }
+
+  /** The repository's top-level directory, or null when the directory is not inside a git work tree. */
+  public async topLevel(): Promise<string | null> {
+    try {
+      return (await this.run(['rev-parse', '--show-toplevel'])).trim();
+    } catch (error) {
+      if (error instanceof Error && /not a git repository/i.test(error.message)) {
+        return null;
+      }
+      throw error;
+    }
+  }
+
+  /** `git status --porcelain` lines; empty for a clean tree (untracked files count as changes). */
+  public async statusLines(): Promise<string[]> {
+    return (await this.run(['status', '--porcelain'])).split('\n').filter((lineArg) => lineArg.length > 0);
+  }
+
+  /** Tracked files, relative to the repository root. */
+  public async trackedFiles(): Promise<string[]> {
+    return (await this.run(['ls-files', '-z'])).split('\0').filter((fileArg) => fileArg.length > 0);
+  }
+
+  public async move(fromArg: string, toArg: string): Promise<void> {
+    await this.run(['mv', '--', fromArg, toArg]);
+  }
+}

package/ts/standards/classes.sourceedits.ts

@@ -0,0 +1,58 @@
+import type { ITextEdit } from './helpers.ast.js';
+
+/**
+ * Span edits of one file's text. Edits never re-print the file: each replaces [start, end) of the
+ * original text. Identical edits count once; an edit overlapping an earlier accepted one is
+ * dropped (the fixer retries it on the edited text). Insertions at the same offset keep the order
+ * they were added in.
+ */
+export class SourceEdits {
+  private readonly accepted: Array<ITextEdit & { order: number }> = [];
+  public dropped = 0;
+
+  public add(editArg: ITextEdit): boolean {
+    if (editArg.start > editArg.end) {
+      throw new Error(`Invalid edit span ${editArg.start}-${editArg.end}`);
+    }
+    if (this.accepted.some((otherArg) => otherArg.start === editArg.start && otherArg.end === editArg.end && otherArg.text === editArg.text)) {
+      return true;
+    }
+    const overlaps = this.accepted.some((otherArg) => {
+      const otherIsInsert = otherArg.start === otherArg.end;
+      const isInsert = editArg.start === editArg.end;
+      if (otherIsInsert && isInsert) {
+        return false;
+      }
+      if (isInsert) {
+        return editArg.start > otherArg.start && editArg.start < otherArg.end;
+      }
+      if (otherIsInsert) {
+        return otherArg.start > editArg.start && otherArg.start < editArg.end;
+      }
+      return editArg.start < otherArg.end && otherArg.start < editArg.end;
+    });
+    if (overlaps) {
+      this.dropped++;
+      return false;
+    }
+    this.accepted.push({ ...editArg, order: this.accepted.length });
+    return true;
+  }
+
+  public get size(): number {
+    return this.accepted.length;
+  }
+
+  /** Applies the accepted edits from the end of the text backwards. */
+  public apply(textArg: string): string {
+    const ordered = [...this.accepted].sort((a, b) => b.start - a.start || b.end - a.end || b.order - a.order);
+    let text = textArg;
+    for (const edit of ordered) {
+      if (edit.end > text.length) {
+        throw new Error(`Edit span ${edit.start}-${edit.end} exceeds the text length ${text.length}`);
+      }
+      text = text.slice(0, edit.start) + edit.text + text.slice(edit.end);
+    }
+    return text;
+  }
+}