@gspothq/cli 0.0.0-stage → 0.1.1

package/configurations/language/swift/rules/UIKIT.md

@@ -0,0 +1,99 @@
+# UIKit
+
+## Framework boundaries
+
+Use UIKit for UIKit screens and components. Use SwiftUI for SwiftUI screens. Preserve the
+project's chosen presentation framework; importing UIKit does not require a SwiftUI migration.
+When the two frameworks meet, use `UIViewRepresentable`, `UIViewControllerRepresentable`, or
+`UIHostingController` at the presentation boundary appropriate to the direction of integration.
+
+Keep UI updates on the main actor. Translate framework callbacks into application operations
+without moving network, persistence, or authorization work into reusable views.
+
+### Presentation organization
+
+<!-- level: all -->
+
+Keep framework types out of domain contracts unless those contracts explicitly represent UI.
+Follow declared import boundaries. Put reusable delegate or data-source behavior in a dedicated
+owner when multiple screens need it or the controller mixes unrelated responsibilities.
+A view controller can own a small list's data source and delegate directly.
+
+Use existing navigation and dependency-construction owners. Do not introduce a coordinator,
+router, view model, or composition type solely to satisfy a prescribed type layout.
+
+## View-controller lifecycle
+
+Install and constrain owned views through the controller's lifecycle. Balance child-controller
+containment calls when embedding controllers. Retain objects whose lifetime the screen owns,
+and cancel screen-owned asynchronous work when its results become irrelevant.
+
+An asynchronous result must still belong to the visible item
+or current screen before it changes the UI.
+
+### Controller responsibilities
+
+<!-- level: all -->
+
+Large `viewDidLoad`, `viewDidAppear`, app delegate, or scene delegate methods move their
+setup into named private methods or composition objects. A mode flag that forces the same
+branching across several methods becomes separate strategy or data source objects or an
+explicit state type. Composition shares UI behavior. Inheritance serves framework
+requirements or stable shared behavior rather than default reuse:
+
+```swift
+currentDataSource = SectionedProductsDataSource(products: products)
+tableView.dataSource = currentDataSource
+tableView.reloadData()
+```
+
+Preserve supported storyboard, nib, and programmatic construction paths. Mark an initializer
+unavailable only when the component's actual construction contract excludes it.
+
+## Lists and reusable cells
+
+- Retain separately owned data sources and delegates. Table and collection views do not keep
+  these weakly referenced owners alive for the screen.
+- Use stable item identifiers. An `IndexPath` identifies a position in the current collection,
+  not an item across insertions, removals, or asynchronous work.
+- Look up the current item before handling selection. Do not retain an old index path as identity.
+- Configure every reusable cell's visible and accessibility state for its current item.
+- Cancel or replace image work when the table reuses a cell. Apply a result only when its item identity
+  still matches, and keep UI updates on the main actor.
+- Preserve the relationship between cell registration, dequeueing, and the expected cell type.
+  Do not force-cast unrelated cells to conceal a registration mismatch.
+- Keep list mutations and data-source updates consistent so the view never receives impossible
+  row or section counts.
+
+### Cell registration
+
+Create a `UICollectionView.CellRegistration` outside the diffable data source's cell-provider
+closure and reuse it for configured dequeueing. Creating it inside that closure prevents cell
+reuse and can raise an exception. See [Apple's cell-registration documentation](https://developer.apple.com/documentation/uikit/uicollectionviewcellregistration?language=swift).
+
+### Cell models
+
+<!-- level: all -->
+
+Pass cells the values needed for rendering and interaction. Keep provider records and database
+mechanics at their existing boundary. Use a feature-owned enum for a closed set of heterogeneous
+rows when it makes the relationship explicit. Add a shared configurator only for repeated
+behavior that existing registration APIs do not already own.
+
+## Diffable data sources
+
+Use diffable data sources when snapshot-based updates fit the screen. Keep item identifiers
+unique and stable across snapshots. Do not identify an item by mutable display text.
+
+Build each snapshot from a consistent state. Resolve cells and selection through the current
+data source. When you write tests, cover insertion, removal, reordering, and asynchronous refresh
+when the screen owns those transitions. Keep snapshot-building code with the presentation behavior
+it serves.
+
+## Accessibility and interaction
+
+Expose meaningful values, traits, and actions, and keep accessibility state correct after cell
+reuse and snapshot updates. When you write tests, cover focus and selection when content changes
+or a modal screen closes.
+
+Use constraints that fit Dynamic Type, safe areas, and every supported size class.

package/configurations/language/swift/semgrep/swift.yml

@@ -0,0 +1,126 @@
+rules:
+    - id: gspot.swift.keychain-accessible-always
+      pattern: kSecAttrAccessibleAlways
+      message: This Keychain class permits access regardless of device lock state.
+          Choose an accessibility class that matches when the item must be
+          available.
+      languages:
+          - swift
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-922
+          category: security
+    - id: gspot.swift.no-secrets-in-userdefaults
+      patterns:
+          - pattern-either:
+                - pattern: 'UserDefaults.$INSTANCE.set($VALUE, forKey: $KEY)'
+                - pattern: 'UserDefaults(...).set($VALUE, forKey: $KEY)'
+                - pattern: 'UserDefaults(...)!.set($VALUE, forKey: $KEY)'
+                - patterns:
+                      - pattern: '$DEFAULTS.set($VALUE, forKey: $KEY)'
+                      - pattern-either:
+                            - pattern-inside: |-
+                                  let $DEFAULTS = UserDefaults.$INSTANCE
+                                  ...
+                            - pattern-inside: |-
+                                  var $DEFAULTS = UserDefaults.$INSTANCE
+                                  ...
+                            - pattern-inside: |-
+                                  let $DEFAULTS = UserDefaults(...)!
+                                  ...
+                            - pattern-inside: |-
+                                  var $DEFAULTS = UserDefaults(...)!
+                                  ...
+                            - pattern-inside: |-
+                                  let $DEFAULTS: UserDefaults = ...
+                                  ...
+                            - pattern-inside: |-
+                                  var $DEFAULTS: UserDefaults = ...
+                                  ...
+                            - pattern-inside: 'func $FUNCTION(..., $DEFAULTS: UserDefaults, ...) { ... }'
+          - metavariable-regex:
+                metavariable: $KEY
+                regex: (?i).*(token|password|secret|credential).*
+      message: Sensitive data stored in UserDefaults (unencrypted plist). Use the
+          Keychain for tokens, passwords, and credentials.
+      languages:
+          - swift
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-312
+          category: security
+    - id: gspot.swift.no-secrets-in-plist
+      patterns:
+          - pattern-either:
+                - pattern: Bundle.main.infoDictionary?[$KEY]
+                - pattern: 'Bundle.main.object(forInfoDictionaryKey: $KEY)'
+          - metavariable-regex:
+                metavariable: $KEY
+                regex: .*(Secret|Password|PrivateKey).*
+      message: 'Reading secrets from Info.plist: plist values are not encrypted. Use
+          the Keychain or environment-injected configuration.'
+      languages:
+          - swift
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-312
+          category: security
+    - id: gspot.swift.weak-hash-algorithm
+      pattern-either:
+          - pattern: Insecure.MD5
+          - pattern: Insecure.SHA1
+          - pattern: CC_MD5(...)
+          - pattern: CC_SHA1(...)
+      message: Weak hash algorithm (MD5/SHA1). Use SHA-256 or stronger from CryptoKit.
+      languages:
+          - swift
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-328
+          category: security
+    - id: gspot.swift.log-sensitive-data
+      patterns:
+          - pattern-either:
+                - patterns:
+                      - pattern-either:
+                            - pattern: print("...\($SECRET)...")
+                            - pattern: print($SECRET)
+                            - pattern: NSLog("...\($SECRET)...")
+                            - pattern: NSLog($FORMAT, ..., $SECRET, ...)
+                            - pattern: os_log("...\($SECRET)...", ...)
+                            - pattern: os_log($FORMAT, ..., $SECRET, ...)
+                      - metavariable-regex:
+                            metavariable: $SECRET
+                            regex: (?i)^(?:[a-z_][a-z0-9_]*\.)*[a-z0-9_]*(?:token|password|secret|credential)[a-z0-9_]*$
+                - patterns:
+                      - pattern-either:
+                            - patterns:
+                                  - pattern: $LOGGER.$LEVEL($SECRET)
+                                  - metavariable-regex:
+                                        metavariable: $SECRET
+                                        regex: (?i)^(?:[a-z_][a-z0-9_]*\.)*[a-z0-9_]*(?:token|password|secret|credential)[a-z0-9_]*$
+                            - patterns:
+                                  - pattern: $LOGGER.$LEVEL("...\($SECRET)...")
+                                  - pattern: $LOGGER.$LEVEL($MESSAGE)
+                                  - metavariable-regex:
+                                        metavariable: $SECRET
+                                        regex: (?i)^(?:[a-z_][a-z0-9_]*\.)*[a-z0-9_]*(?:token|password|secret|credential)[a-z0-9_]*$
+                                  - metavariable-regex:
+                                        metavariable: $MESSAGE
+                                        regex: (?is)^".*(?<!\\)\\\(\s*(?:[a-z_][a-z0-9_]*\.)*[a-z0-9_]*(?:token|password|secret|credential)[a-z0-9_]*\s*(?:,\s*privacy:\s*\.public)?\s*\)
+                      - metavariable-regex:
+                            metavariable: $LEVEL
+                            regex: ^(trace|debug|info|notice|warning|warn|error|fault|critical|log)$
+      message: Potentially logging sensitive data. Redact tokens, passwords, and
+          credentials before logging.
+      languages:
+          - swift
+      severity: ERROR
+      metadata:
+          cwe:
+              - CWE-532
+          category: security

package/configurations/language/typescript/eslint-presets.json

@@ -0,0 +1,215 @@
+{
+    "strict": {
+        "package": "typescript-eslint",
+        "version": "8.70.0",
+        "source": "configs.strictTypeChecked",
+        "blocks": [
+            { "parser": true },
+            {
+                "files": ["**/*.ts", "**/*.tsx", "**/*.mts", "**/*.cts"],
+                "parser": false,
+                "rules": {
+                    "constructor-super": "off",
+                    "getter-return": "off",
+                    "no-class-assign": "off",
+                    "no-const-assign": "off",
+                    "no-dupe-args": "off",
+                    "no-dupe-class-members": "off",
+                    "no-dupe-keys": "off",
+                    "no-func-assign": "off",
+                    "no-import-assign": "off",
+                    "no-new-native-nonconstructor": "off",
+                    "no-new-symbol": "off",
+                    "no-obj-calls": "off",
+                    "no-redeclare": "off",
+                    "no-setter-return": "off",
+                    "no-this-before-super": "off",
+                    "no-undef": "off",
+                    "no-unreachable": "off",
+                    "no-unsafe-negation": "off",
+                    "no-var": "error",
+                    "no-with": "off",
+                    "prefer-const": "error",
+                    "prefer-rest-params": "error",
+                    "prefer-spread": "error"
+                }
+            },
+            {
+                "parser": false,
+                "rules": {
+                    "@typescript-eslint/await-thenable": "error",
+                    "@typescript-eslint/ban-ts-comment": ["error", { "minimumDescriptionLength": 10 }],
+                    "no-array-constructor": "off",
+                    "@typescript-eslint/no-array-constructor": "error",
+                    "@typescript-eslint/no-array-delete": "error",
+                    "@typescript-eslint/no-base-to-string": "error",
+                    "@typescript-eslint/no-confusing-void-expression": "error",
+                    "@typescript-eslint/no-deprecated": "error",
+                    "@typescript-eslint/no-duplicate-enum-values": "error",
+                    "@typescript-eslint/no-duplicate-type-constituents": "error",
+                    "@typescript-eslint/no-dynamic-delete": "error",
+                    "@typescript-eslint/no-empty-object-type": "error",
+                    "@typescript-eslint/no-explicit-any": "error",
+                    "@typescript-eslint/no-extra-non-null-assertion": "error",
+                    "@typescript-eslint/no-extraneous-class": "error",
+                    "@typescript-eslint/no-floating-promises": "error",
+                    "@typescript-eslint/no-for-in-array": "error",
+                    "@typescript-eslint/no-generated-empty-object-type": "error",
+                    "no-implied-eval": "off",
+                    "@typescript-eslint/no-implied-eval": "error",
+                    "@typescript-eslint/no-invalid-void-type": "error",
+                    "@typescript-eslint/no-meaningless-void-operator": "error",
+                    "@typescript-eslint/no-misused-new": "error",
+                    "@typescript-eslint/no-misused-promises": "error",
+                    "@typescript-eslint/no-misused-spread": "error",
+                    "@typescript-eslint/no-mixed-enums": "error",
+                    "@typescript-eslint/no-namespace": "error",
+                    "@typescript-eslint/no-non-null-asserted-nullish-coalescing": "error",
+                    "@typescript-eslint/no-non-null-asserted-optional-chain": "error",
+                    "@typescript-eslint/no-non-null-assertion": "error",
+                    "@typescript-eslint/no-redundant-type-constituents": "error",
+                    "@typescript-eslint/no-require-imports": "error",
+                    "@typescript-eslint/no-this-alias": "error",
+                    "@typescript-eslint/no-unnecessary-boolean-literal-compare": "error",
+                    "@typescript-eslint/no-unnecessary-condition": "error",
+                    "@typescript-eslint/no-unnecessary-template-expression": "error",
+                    "@typescript-eslint/no-unnecessary-type-arguments": "error",
+                    "@typescript-eslint/no-unnecessary-type-assertion": "error",
+                    "@typescript-eslint/no-unnecessary-type-constraint": "error",
+                    "@typescript-eslint/no-unnecessary-type-conversion": "error",
+                    "@typescript-eslint/no-unnecessary-type-parameters": "error",
+                    "@typescript-eslint/no-unsafe-argument": "error",
+                    "@typescript-eslint/no-unsafe-assignment": "error",
+                    "@typescript-eslint/no-unsafe-call": "error",
+                    "@typescript-eslint/no-unsafe-declaration-merging": "error",
+                    "@typescript-eslint/no-unsafe-enum-comparison": "error",
+                    "@typescript-eslint/no-unsafe-function-type": "error",
+                    "@typescript-eslint/no-unsafe-member-access": "error",
+                    "@typescript-eslint/no-unsafe-return": "error",
+                    "@typescript-eslint/no-unsafe-unary-minus": "error",
+                    "no-unused-expressions": "off",
+                    "@typescript-eslint/no-unused-expressions": "error",
+                    "no-unused-vars": "off",
+                    "@typescript-eslint/no-unused-vars": "error",
+                    "no-useless-constructor": "off",
+                    "@typescript-eslint/no-useless-constructor": "error",
+                    "@typescript-eslint/no-useless-default-assignment": "error",
+                    "@typescript-eslint/no-wrapper-object-types": "error",
+                    "no-throw-literal": "off",
+                    "@typescript-eslint/only-throw-error": "error",
+                    "@typescript-eslint/prefer-as-const": "error",
+                    "@typescript-eslint/prefer-literal-enum-member": "error",
+                    "@typescript-eslint/prefer-namespace-keyword": "error",
+                    "prefer-promise-reject-errors": "off",
+                    "@typescript-eslint/prefer-promise-reject-errors": "error",
+                    "@typescript-eslint/prefer-reduce-type-parameter": "error",
+                    "@typescript-eslint/prefer-return-this-type": "error",
+                    "@typescript-eslint/related-getter-setter-pairs": "error",
+                    "require-await": "off",
+                    "@typescript-eslint/require-await": "error",
+                    "@typescript-eslint/restrict-plus-operands": [
+                        "error",
+                        {
+                            "allowAny": false,
+                            "allowBoolean": false,
+                            "allowNullish": false,
+                            "allowNumberAndString": false,
+                            "allowRegExp": false
+                        }
+                    ],
+                    "@typescript-eslint/restrict-template-expressions": [
+                        "error",
+                        {
+                            "allowAny": false,
+                            "allowBoolean": false,
+                            "allowNever": false,
+                            "allowNullish": false,
+                            "allowNumber": false,
+                            "allowRegExp": false
+                        }
+                    ],
+                    "no-return-await": "off",
+                    "@typescript-eslint/return-await": ["error", "error-handling-correctness-only"],
+                    "@typescript-eslint/triple-slash-reference": "error",
+                    "@typescript-eslint/unbound-method": "error",
+                    "@typescript-eslint/unified-signatures": "error",
+                    "@typescript-eslint/use-unknown-in-catch-callback-variable": "error"
+                }
+            }
+        ]
+    },
+    "untyped": {
+        "package": "typescript-eslint",
+        "version": "8.70.0",
+        "source": "configs.disableTypeChecked",
+        "blocks": [
+            {
+                "parser": false,
+                "rules": {
+                    "@typescript-eslint/await-thenable": "off",
+                    "@typescript-eslint/consistent-return": "off",
+                    "@typescript-eslint/consistent-type-exports": "off",
+                    "@typescript-eslint/dot-notation": "off",
+                    "@typescript-eslint/naming-convention": "off",
+                    "@typescript-eslint/no-array-delete": "off",
+                    "@typescript-eslint/no-base-to-string": "off",
+                    "@typescript-eslint/no-confusing-void-expression": "off",
+                    "@typescript-eslint/no-deprecated": "off",
+                    "@typescript-eslint/no-duplicate-type-constituents": "off",
+                    "@typescript-eslint/no-floating-promises": "off",
+                    "@typescript-eslint/no-for-in-array": "off",
+                    "@typescript-eslint/no-generated-empty-object-type": "off",
+                    "@typescript-eslint/no-implied-eval": "off",
+                    "@typescript-eslint/no-meaningless-void-operator": "off",
+                    "@typescript-eslint/no-misused-promises": "off",
+                    "@typescript-eslint/no-misused-spread": "off",
+                    "@typescript-eslint/no-mixed-enums": "off",
+                    "@typescript-eslint/no-redundant-type-constituents": "off",
+                    "@typescript-eslint/no-unnecessary-boolean-literal-compare": "off",
+                    "@typescript-eslint/no-unnecessary-condition": "off",
+                    "@typescript-eslint/no-unnecessary-qualifier": "off",
+                    "@typescript-eslint/no-unnecessary-template-expression": "off",
+                    "@typescript-eslint/no-unnecessary-type-arguments": "off",
+                    "@typescript-eslint/no-unnecessary-type-assertion": "off",
+                    "@typescript-eslint/no-unnecessary-type-conversion": "off",
+                    "@typescript-eslint/no-unnecessary-type-parameters": "off",
+                    "@typescript-eslint/no-unsafe-argument": "off",
+                    "@typescript-eslint/no-unsafe-assignment": "off",
+                    "@typescript-eslint/no-unsafe-call": "off",
+                    "@typescript-eslint/no-unsafe-enum-comparison": "off",
+                    "@typescript-eslint/no-unsafe-member-access": "off",
+                    "@typescript-eslint/no-unsafe-return": "off",
+                    "@typescript-eslint/no-unsafe-type-assertion": "off",
+                    "@typescript-eslint/no-unsafe-unary-minus": "off",
+                    "@typescript-eslint/no-useless-default-assignment": "off",
+                    "@typescript-eslint/non-nullable-type-assertion-style": "off",
+                    "@typescript-eslint/only-throw-error": "off",
+                    "@typescript-eslint/prefer-destructuring": "off",
+                    "@typescript-eslint/prefer-find": "off",
+                    "@typescript-eslint/prefer-includes": "off",
+                    "@typescript-eslint/prefer-nullish-coalescing": "off",
+                    "@typescript-eslint/prefer-optional-chain": "off",
+                    "@typescript-eslint/prefer-promise-reject-errors": "off",
+                    "@typescript-eslint/prefer-readonly": "off",
+                    "@typescript-eslint/prefer-readonly-parameter-types": "off",
+                    "@typescript-eslint/prefer-reduce-type-parameter": "off",
+                    "@typescript-eslint/prefer-regexp-exec": "off",
+                    "@typescript-eslint/prefer-return-this-type": "off",
+                    "@typescript-eslint/prefer-string-starts-ends-with": "off",
+                    "@typescript-eslint/promise-function-async": "off",
+                    "@typescript-eslint/related-getter-setter-pairs": "off",
+                    "@typescript-eslint/require-array-sort-compare": "off",
+                    "@typescript-eslint/require-await": "off",
+                    "@typescript-eslint/restrict-plus-operands": "off",
+                    "@typescript-eslint/restrict-template-expressions": "off",
+                    "@typescript-eslint/return-await": "off",
+                    "@typescript-eslint/strict-boolean-expressions": "off",
+                    "@typescript-eslint/strict-void-return": "off",
+                    "@typescript-eslint/switch-exhaustiveness-check": "off",
+                    "@typescript-eslint/unbound-method": "off",
+                    "@typescript-eslint/use-unknown-in-catch-callback-variable": "off"
+                }
+            }
+        ]
+    }
+}

package/configurations/language/typescript/manifest.toml

@@ -0,0 +1,72 @@
+allowed_words = ["TypeScript"]
+
+[prefix_collisions]
+prefixes = ["tsconfig"]
+
+[configuration]
+title = "TypeScript"
+requires = ["javascript"]
+suggests = []
+description = "The strict compiler, ESLint with typescript-eslint and the gspot structural rules over every TypeScript file, and knip for dead code."
+
+[detect]
+extensions = [".ts", ".tsx", ".mts", ".cts"]
+filenames = ["tsconfig.json"]
+
+[files]
+extensions = [".ts", ".tsx", ".mts", ".cts", ".d.ts"]
+filenames = ["tsconfig.json", "tsconfig.*.json"]
+
+[[tool]]
+name = "typescript-eslint"
+requires = ["tsc"]
+rule_prefix = "@typescript-eslint"
+rule_url = "https://typescript-eslint.io/rules/{rule}"
+kind = "library"
+version = "8.70.0"
+npm = "typescript-eslint"
+
+[tool.eslint]
+extensions = [".ts", ".tsx", ".mts", ".cts"]
+
+[[check]]
+name = "tsc"
+example = "The TypeScript declaration `const count: number = \"one\";` reports an incompatible assignment. Correct it to `const count: number = 1;` when the contract requires a number."
+level = "recommended"
+stage = "push"
+runs = "scope"
+cwd = "scope"
+tool = "tsc"
+summary = "Checks that every TypeScript file type-checks with the strict compiler options."
+why = "A file that does not type-check can crash at run time in a way the editor already knew about."
+help = "Read the first error tsc prints and fix that file; later errors are often the same mistake."
+
+[check.output]
+format = "regex"
+pattern = "^(?<file>[^(]+)\\((?<line>\\d+),(?<column>\\d+)\\): error (?<rule>TS\\d+): (?<message>.*)$"
+
+[[check]]
+name = "tsconfig"
+example = "Your TypeScript configuration setting `strict` to `false` reports the required compiler option. Enable `strict` and fix the type errors it reports."
+level = "recommended"
+stage = "commit"
+summary = "Requires strict, noUncheckedIndexedAccess, exactOptionalPropertyTypes, noImplicitOverride, and noFallthroughCasesInSwitch in every tsconfig you write. Level all also requires noImplicitReturns and noPropertyAccessFromIndexSignature."
+why = "One tsconfig that drops strict lets untyped code back in for that whole scope."
+help = "Enable the reported compiler option in your TypeScript configuration."
+
+[eslint]
+all_level_rules = ["@typescript-eslint/ban-ts-comment", "@typescript-eslint/consistent-type-definitions", "@typescript-eslint/consistent-type-exports", "@typescript-eslint/consistent-type-imports", "@typescript-eslint/explicit-module-boundary-types", "@typescript-eslint/no-explicit-any", "@typescript-eslint/no-extraneous-class", "@typescript-eslint/no-magic-numbers", "@typescript-eslint/no-mixed-enums", "@typescript-eslint/no-namespace", "@typescript-eslint/no-non-null-assertion", "@typescript-eslint/no-require-imports", "@typescript-eslint/no-this-alias", "@typescript-eslint/no-unnecessary-type-parameters", "@typescript-eslint/prefer-readonly", "@typescript-eslint/prefer-reduce-type-parameter", "@typescript-eslint/prefer-return-this-type", "@typescript-eslint/strict-boolean-expressions", "@typescript-eslint/triple-slash-reference", "@typescript-eslint/unified-signatures"]
+
+[eslint.presets.strict]
+package = "typescript-eslint"
+source = "configs.strictTypeChecked"
+
+[eslint.presets.untyped]
+package = "typescript-eslint"
+source = "configs.disableTypeChecked"
+
+[[tool_file]]
+target = ".gspot/config/eslint.config.mjs"
+tool = "eslint"
+fragment = true
+required_tools = ["typescript-eslint"]

package/configurations/language/typescript/rules/NAMING.md

@@ -0,0 +1,73 @@
+# TypeScript Naming
+
+TypeScript naming follows the project rules here. Use Google TypeScript guidance as
+a strong default for many language choices. The rules below deliberately override some of it, and
+say so where they do.
+
+## TypeScript files and modules
+
+<!-- level: all -->
+
+- File names describe the primary exported type, function, route, or cohesive
+  capability.
+- Do not use namespaces, `module`, triple-slash references, or
+  `import x = require(...)` to simulate ownership.
+- Do not create files named only for generic reuse.
+- Keep generated file names only when generator-owned.
+
+## TypeScript variables
+
+<!-- level: all -->
+
+- Use meaningful, pronounceable names.
+- Use the same vocabulary for the same concept.
+- Use explanatory destructuring names.
+- Avoid mental mapping with single-letter names except tiny local scopes.
+- Use named constants for meaningful repeated numbers or strings.
+- Do not add context already present in the type or owner.
+
+For a range comparison, name the value `value` and the bounds `minimum` and
+`maximum`. Use a type that supports the comparison, such as `number`; an
+unconstrained generic does not establish ordering semantics.
+
+When iterating a map of users, destructure its entries as `[userId, user]`
+instead of naming each pair `keyValue`.
+
+Name a reused daily timer duration `MILLISECONDS_PER_DAY` and define it as
+`86_400_000`. The name explains both the interval and its unit.
+
+## TypeScript functions
+
+<!-- level: all -->
+
+- Function names say what they do.
+- Prefer two or fewer parameters.
+- Use an options object for many arguments, multiple same-type arguments,
+  optional groups, or boolean flags.
+- Do not use boolean flags to choose separate behaviors.
+- Prefer a positive predicate name plus `!` at the call site over a negative
+  predicate function.
+- Use async/await in names only to distinguish from a blocking counterpart. Normally the return type communicates async.
+- Name functions by domain work, not implementation mechanics.
+
+## TypeScript types
+
+<!-- level: all -->
+
+- Use unions and discriminated unions for alternatives.
+- Use interfaces only when a framework contract, declaration merging, or
+  `implements` relationship makes an interface the clearest tool.
+- Do not encode optionality in an alias name.
+- Use optional fields and parameters for values callers can omit.
+- Avoid return-type-only generics. When using an existing return-type-only
+  generic API, specify the generic explicitly.
+- Name index keys meaningfully when the type needs an index signature.
+- Prefer `Map` for key/value operations.
+
+Name a coffee response union `CoffeeResponse`; put `| undefined` on an
+operation that can return no response. Name a user index `UsersById` and its
+index key `userId`.
+
+A function that selects a collection element ties its generic to the input
+collection. Its return contract must account for an empty collection unless
+the input type or validation proves that an element exists.