quality.json reference

The package includes quality.schema.json; set $schema to its installed path for editor completion. quality.json is standard JSON.

Minimal configuration

{
  "$schema": "./node_modules/@terra-symposium/quality/quality.schema.json",
  "sourceRoots": ["src"],
  "extensions": [".js", ".jsx", ".ts", ".tsx"],
  "tools": { "prettier": "prettier", "eslint": "eslint", "knip": "knip", "tsc": "tsc" },
  "qualityCommands": [
    { "name": "build", "command": "pnpm", "args": ["run", "build"] },
    { "name": "test", "command": "pnpm", "args": ["run", "test"] }
  ]
}

sourceRoots and extensions are required. Keep only tools and commands installed and desired in your repository.

Scope and path fields

Field	Meaning
root	Repository root relative to the config file; defaults to the config directory.
sourceRoots	Required source discovery roots, relative to root.
includeRoots	Additional roots used by single-use analysis.
extensions	Required file extensions, including the leading dot.
skippedDirectories, skippedFiles	Additional excluded paths. Common generated directories are already skipped.
singleUse.skippedDirectories	Exclusions specific to single-use analysis.
aliases	Import prefixes mapped to repository paths, e.g. { "@/": "src/" }.
externalPrefixes	Import prefixes intentionally considered external.
protectedIdentifiers	Names the naming cleanup must preserve.
renameExports	Allow the naming rule to rename exports; defaults to false.

Paths resolve from root; express roots and exclusions consistently relative to it.

Check toggles and autofixes

Omitted enabledChecks entries remain enabled. Omitted autofix entries remain enabled for fix-capable checks. The --warn CLI option disables every autofix for that invocation.

{
  "enabledChecks": {
    "document": true, "format": true, "import": true, "name": true,
    "forward": true, "lint": true, "knip": true, "dead-code": true,
    "type": true, "recommend": true, "command": true, "diff": true,
    "alias": true, "security": true, "repeated-classes": true,
    "regex-dedup": true, "ui-patterns": true
  },
  "autofix": {
    "document": true, "format": true, "name": true, "lint": true,
    "knip": true, "alias": true, "forward": true,
    "repeatedClasses": true, "regexDedup": true
  }
}

security, repeatedClasses, regexDedup, and uiPatterns checks run only when their matching config object is supplied. Each check guide explains fixability and limits.

Documentation policy

{
  "documentation": {
    "required": { "types": true, "functions": true, "exportedFunctions": true, "noInlineFunctions": false }
  }
}

These booleans are independent. types covers classes, enums, interfaces, and type aliases. functions covers named function declarations. exportedFunctions can cover exported named functions when functions is false. noInlineFunctions reports arrow functions and function expressions. The fixer can add blank scaffolding, not prose.

Tools and type checks

Field	Meaning
tools.prettier, tools.eslint, tools.knip, tools.tsc	Executable name or path. A repository-local .bin tool is preferred for a name. Tools are not installed by this package.
oneLineImports	Enables long one-line import protection/canonicalization.
prettierPrintWidth	Print width for the formatting integration.
lintRoots	ESLint scope; defaults to selected source files.
tsconfig	TypeScript project config path.
typecheckRoots, typecheckExtensions	Source type-check scope.
typecheckCommand	Optional repository-owned typecheck executable and args.

Native tool configuration remains available for project-specific rules and plugins.

Required and advisory commands

qualityCommands lists required commands. Each item needs a unique lowercase name, command, and optional string-array args. enabledCommands toggles individual names. enabledChecks.command: false disables the category.

recommendationCommands uses the same shape. enabledRecommendations toggles each name; enabledChecks.recommend: false disables all. Recommendation statuses do not fail quality.

{
  "qualityCommands": [{ "name": "test", "command": "pnpm", "args": ["test"] }],
  "enabledCommands": { "test": true },
  "recommendationCommands": [{ "name": "dependency-report", "command": "pnpm", "args": ["run", "dependency-report"] }],
  "enabledRecommendations": { "dependency-report": true }
}

Commands run from root and inherit the calling process environment. The runner does not provision services or credentials.

Security policy

{
  "security": {
    "forbiddenTerms": ["temporary-secret"],
    "forbiddenImports": ["unsafe-package"],
    "clientRoots": ["src/client"],
    "allowProcessEnvRoots": ["src/server"]
  }
}

All fields are optional. Client roots identify code where secret-shaped environment access should be reported; runtime roots permit expected process-environment access. These are portable guardrails, not a full secret scanner or framework-aware trust analysis.

Pattern policies

Field	Options	Purpose
repeatedClasses	minimumCount, extensions, ignoredDirectories	Detect repeated static class strings.
regexDedup	minimumCount, extensions, ignoredFiles, sharedModule	Detect repeated regex sources; optional shared ESM factory enables cross-file fixes.
uiPatterns	forbidden, extensions, ignoredFiles	Report UI patterns that should use shared primitives.
tailwindCanonical	stylesheet, sourceRoots	Canonical stylesheet and optional Tailwind normalization roots.

Regex shared-module extraction expects a repository-relative .mjs and matching .d.mts. Unsupported cases remain review findings. See repeated classes and regex dedup.

Terra Shared’s own config

This repository scans packages and scripts, supports JS/TS module extensions, protects long one-line imports, and opts into build and test commands. It skips single-use in packages/quality, where declarations are part of reusable package APIs. Treat it as an example; choose scope to fit your own repository.