@sha3/code-standards 0.1.1 → 0.1.3

package/resources/ai/templates/examples/rules/async-bad.ts

@@ -0,0 +1,94 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+type SyncInvoicesCommand = { accountId: string };
+type Invoice = { id: string; accountId: string };
+type SyncResult = { saved: number };
+type InvoiceSource = { fetch(accountId: string): Promise<Invoice[]> };
+type InvoiceWriter = { persist(invoices: Invoice[]): Promise<SyncResult> };
+
+export class InvoiceSyncService {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly source: InvoiceSource;
+  private readonly writer: InvoiceWriter;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(source: InvoiceSource, writer: InvoiceWriter) {
+    this.source = source;
+    this.writer = writer;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(source: InvoiceSource, writer: InvoiceWriter): InvoiceSyncService {
+    const service = new InvoiceSyncService(source, writer);
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+    return this.source.fetch(command.accountId).then((invoices: Invoice[]) => {
+      return this.writer.persist(invoices);
+    });
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/async-good.ts

@@ -0,0 +1,94 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+type SyncInvoicesCommand = { accountId: string };
+type Invoice = { id: string; accountId: string };
+type SyncResult = { saved: number };
+type InvoiceSource = { fetch(accountId: string): Promise<Invoice[]> };
+type InvoiceWriter = { persist(invoices: Invoice[]): Promise<SyncResult> };
+
+export class InvoiceSyncService {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly source: InvoiceSource;
+  private readonly writer: InvoiceWriter;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(source: InvoiceSource, writer: InvoiceWriter) {
+    this.source = source;
+    this.writer = writer;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(source: InvoiceSource, writer: InvoiceWriter): InvoiceSyncService {
+    const service = new InvoiceSyncService(source, writer);
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public async execute(command: SyncInvoicesCommand): Promise<SyncResult> {
+    const invoices: Invoice[] = await this.source.fetch(command.accountId);
+    const result: SyncResult = await this.writer.persist(invoices);
+    return result;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/class-first-bad.ts

@@ -0,0 +1,90 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+type CreateInvoiceCommand = { customerId: string; amount: number };
+type Invoice = { id: string; customerId: string; amount: number };
+
+export class InvoiceService {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  // empty
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  // empty
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    if (!command.customerId) {
+      return Promise.reject(new Error("invalid command"));
+    }
+
+    const invoice: Invoice = { id: "1", customerId: command.customerId, amount: command.amount };
+    return invoice;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/class-first-good.ts

@@ -0,0 +1,99 @@
+/**
+ * @section imports:externals
+ */
+
+import { randomUUID } from "node:crypto";
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+const SERVICE_NAME = "invoice-service";
+
+/**
+ * @section types
+ */
+
+type CreateInvoiceCommand = { customerId: string; amount: number };
+type Invoice = { id: string; customerId: string; amount: number; createdAt: Date };
+
+export class InvoiceService {
+  /**
+   * @section private:attributes
+   */
+
+  private readonly requestId: string;
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly invoicesById: Map<string, Invoice>;
+
+  /**
+   * @section public:properties
+   */
+
+  public readonly serviceName: string;
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    this.invoicesById = new Map<string, Invoice>();
+    this.requestId = randomUUID();
+    this.serviceName = SERVICE_NAME;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceService {
+    const service = new InvoiceService();
+    return service;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private toInvoice(command: CreateInvoiceCommand): Invoice {
+    const invoice: Invoice = {
+      id: randomUUID(),
+      customerId: command.customerId,
+      amount: command.amount,
+      createdAt: new Date()
+    };
+    return invoice;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public async create(command: CreateInvoiceCommand): Promise<Invoice> {
+    const invoice: Invoice = this.toInvoice(command);
+    this.invoicesById.set(invoice.id, invoice);
+    return invoice;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/constructor-bad.ts

@@ -0,0 +1,98 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+const FALLBACK_PREFIX = "INV";
+
+/**
+ * @section types
+ */
+
+type Clock = () => Date;
+type IdFactory = () => string;
+
+export class InvoiceIdBuilder {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly clock: Clock;
+  private readonly idFactory: IdFactory;
+  private readonly prefix: string;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor() {
+    // Bad: constructor wires concrete dependencies and environment details directly.
+    this.clock = () => new Date();
+    this.idFactory = () => Math.random().toString(36).slice(2, 8);
+    this.prefix = process.env.INVOICE_PREFIX || FALLBACK_PREFIX;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): InvoiceIdBuilder {
+    const builder = new InvoiceIdBuilder();
+    return builder;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private currentYear(): number {
+    const year = this.clock().getUTCFullYear();
+    return year;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public build(): string {
+    const rawId = this.idFactory();
+    const year = this.currentYear();
+    const invoiceId = `${this.prefix}-${year}-${rawId}`;
+    return invoiceId;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/constructor-good.ts

@@ -0,0 +1,97 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+const DEFAULT_INVOICE_PREFIX = "INV";
+
+/**
+ * @section types
+ */
+
+type Clock = () => Date;
+type IdFactory = () => string;
+
+export class InvoiceIdBuilder {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  private readonly clock: Clock;
+  private readonly idFactory: IdFactory;
+  private readonly prefix: string;
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  public constructor(clock: Clock, idFactory: IdFactory, prefix = DEFAULT_INVOICE_PREFIX) {
+    this.clock = clock;
+    this.idFactory = idFactory;
+    this.prefix = prefix;
+  }
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(clock: Clock, idFactory: IdFactory): InvoiceIdBuilder {
+    const builder = new InvoiceIdBuilder(clock, idFactory);
+    return builder;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  private currentYear(): number {
+    const year = this.clock().getUTCFullYear();
+    return year;
+  }
+
+  /**
+   * @section public:methods
+   */
+
+  public build(): string {
+    const rawId = this.idFactory();
+    const year = this.currentYear();
+    const invoiceId = `${this.prefix}-${year}-${rawId}`;
+    return invoiceId;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}

package/resources/ai/templates/examples/rules/control-flow-bad.ts

@@ -0,0 +1,85 @@
+/**
+ * @section imports:externals
+ */
+
+// empty
+
+/**
+ * @section imports:internals
+ */
+
+// empty
+
+/**
+ * @section consts
+ */
+
+// empty
+
+/**
+ * @section types
+ */
+
+// empty
+
+export class ControlFlowPolicy {
+  /**
+   * @section private:attributes
+   */
+
+  // empty
+
+  /**
+   * @section private:properties
+   */
+
+  // empty
+
+  /**
+   * @section public:properties
+   */
+
+  // empty
+
+  /**
+   * @section constructor
+   */
+
+  // empty
+
+  /**
+   * @section static:properties
+   */
+
+  // empty
+
+  /**
+   * @section factory
+   */
+
+  public static create(): ControlFlowPolicy {
+    const policy = new ControlFlowPolicy();
+    return policy;
+  }
+
+  /**
+   * @section private:methods
+   */
+
+  // empty
+
+  /**
+   * @section public:methods
+   */
+
+  public badSnippet(): string {
+    const snippet = "if (isEnabled) executeTask();";
+    return snippet;
+  }
+
+  /**
+   * @section static:methods
+   */
+
+  // empty
+}