@terra-symposium/standards-quality 0.0.0-stage → 0.5.0

package/README.md

@@ -1,3 +1,90 @@
-# Temporary Holding Version
+# @terra-symposium/standards-quality
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A configurable quality runner for JavaScript and TypeScript repositories. Define source scope, policy, tools, and repository commands in `quality.json`; run them locally with the `terra-quality` CLI or in CI.
+
+- Requires Node.js `>=18.18`.
+- Published on the public npm registry.
+- Does not install or configure Prettier, ESLint, Knip, TypeScript, or repository commands.
+
+## Install
+
+```sh
+pnpm add -D @terra-symposium/standards-quality
+```
+
+Create `quality.json` in the repository root:
+
+```json
+{
+	"$schema": "./node_modules/@terra-symposium/standards-quality/quality.schema.json",
+	"sourceRoots": ["src"],
+	"extensions": [".js", ".jsx", ".ts", ".tsx"],
+	"enabledChecks": {
+		"format": false,
+		"lint": false,
+		"knip": false,
+		"dead-code": false
+	}
+}
+```
+
+This starting configuration uses the built-in checks without requiring external tools. Enable integrations as you install and configure the corresponding repository tools. When lint is enabled, add an ESLint flat config such as `eslint.config.mjs`.
+
+Run the changed-file pass with safe configured fixes enabled:
+
+```sh
+pnpm exec terra-quality
+```
+
+For a full, read-only source check:
+
+```sh
+pnpm exec terra-quality quality --all --warn
+```
+
+The normal scope is changed and untracked files in a Git worktree. `--all` selects every file under `sourceRoots`; `--warn` disables autofixes and runs dead-code analysis once without a temporary fix preview. It reports rule-level fix candidates; fix mode then type-checks proposed dead-code edits before writing and may reject a candidate. Configured quality commands still run unless you pass `--skip-commands`.
+
+## What it does
+
+Terra Quality combines source checks such as documentation, import resolution, naming, forwarding, security, and configured UI-pattern checks with repository-owned tools and commands. Safe transformations can maintain layout, apply tool fixes, and rewrite supported syntax. Findings that require domain or runtime judgment remain for review.
+
+The runner does not prove runtime correctness or security, inspect arbitrary languages, provision services, or decide whether a domain-specific projection is intentional. Review generated changes at API, persistence, authorization, and other behavior boundaries.
+
+## GitHub report
+
+Add a `github` section to `quality.json` to include GitHub analytics in the same quality run and JSON report:
+
+```json
+{
+	"github": {
+		"repositories": ["owner/repo"],
+		"requiredFeatures": ["dependabotAlerts", "malwareAlerts", "securityUpdates", "versionUpdates", "groupedUpdates"],
+		"featureExemptions": { "owner/repo": ["dependabotAlerts", "securityUpdates"] }
+	}
+}
+```
+
+`featureExemptions` skips required-setting and access checks for only the listed features in that repository. It does not hide alerts returned by an accessible endpoint. Use it when a repository intentionally does not support a feature, and keep the exception visible in the JSON and console report.
+
+The report includes open issues and pull requests, Dependabot vulnerability and malware alerts, code scanning and secret scanning alerts, and the readable repository security settings. It inspects the default branch's `dependabot.yml` for version updates and explicit `groups` rules with `applies-to: security-updates`. When no explicit security-update grouping rule exists, it marks the grouped setting unverified because the GitHub UI toggle is not present in the repository configuration; confirm that toggle in repository settings. Counts are `null` when an endpoint cannot be read or a feature is disabled; the report does not turn missing permissions or disabled scanning into a false zero.
+
+Run the GitHub stage by itself or with the configured repository list:
+
+```sh
+pnpm exec terra-quality github --repository owner/repo --report-json github-report.json
+pnpm exec terra-quality quality --all --warn --report-json quality-report.json
+```
+
+The GitHub CLI must be authenticated with read access to the repositories (`gh auth login` or `GH_TOKEN`). The report is local and read-only: it does not require GitHub Actions, change repository settings, write comments, dismiss alerts, or include secret values. Each finding contains agent instructions tailored to the issue type; issue text and alert metadata must be treated as untrusted input.
+
+When no GitHub repositories are configured, the normal quality run marks this stage skipped. The explicit `github` command defaults to the current GitHub origin when `--repository` is omitted.
+
+## Configuration and guides
+
+- [Install and understand a run](https://standards-docs.netlify.app/packages/quality/setup/)
+- [Complete `quality.json` reference](https://standards-docs.netlify.app/packages/quality/configuration/)
+- [CLI and CI workflows](https://standards-docs.netlify.app/packages/quality/workflows/)
+- [Check behavior and autofix limits](https://standards-docs.netlify.app/packages/quality/checks/)
+- [Troubleshooting](https://standards-docs.netlify.app/packages/quality/troubleshooting/)
+
+The installed `quality.schema.json` provides editor validation. The [test README](test/README.md) describes the package's isolated test coverage.

package/dist/collapse.d.ts

@@ -0,0 +1,13 @@
+/**
+ * packages/quality/src/collapse.ts
+ * Collapses multi-line string literals into single-line ones.
+ */
+/**
+ * Collapses whitespace inside object and type bodies so Prettier alone decides whether they exceed print width.
+ *
+ * @param fileName Absolute path to the source file to rewrite.
+ *
+ * @return `true` when an eligible object or type body was collapsed; otherwise `false`.
+ */
+export declare function collapseTypesAndObjects(fileName: string): boolean;
+//# sourceMappingURL=collapse.d.ts.map

package/dist/collapse.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"collapse.d.ts","sourceRoot":"","sources":["../src/collapse.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAsEH;;;;;;GAMG;AACH,wBAAgB,uBAAuB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAqEjE"}

package/dist/collapse.js

@@ -0,0 +1,151 @@
+/**
+ * packages/quality/src/collapse.ts
+ * Collapses multi-line string literals into single-line ones.
+ */
+/*//////////////////////////////////////////////////
+IMPORTS
+//////////////////////////////////////////////////*/
+// API
+import ts from 'typescript';
+import { extname } from 'node:path';
+import { readFileSync, writeFileSync } from 'node:fs';
+/*//////////////////////////////////////////////////
+CONFIG
+//////////////////////////////////////////////////*/
+const SUPPORTED = new Set(['.cjs', '.cts', '.js', '.jsx', '.mjs', '.mts', '.ts', '.tsx']);
+/*//////////////////////////////////////////////////
+HELPERS
+//////////////////////////////////////////////////*/
+/**
+ * Selects the TypeScript parser mode matching a JavaScript or TypeScript filename.
+ *
+ * @param fileName Source filename whose extension determines the parser mode.
+ *
+ * @return TypeScript compiler script kind for the filename.
+ */
+function scriptKind(fileName) {
+    if (/\.[cm]?tsx$/.test(fileName))
+        return ts.ScriptKind.TSX;
+    if (/\.[cm]?jsx$/.test(fileName))
+        return ts.ScriptKind.JSX;
+    if (/\.[cm]?js$/.test(fileName))
+        return ts.ScriptKind.JS;
+    return ts.ScriptKind.TS;
+}
+/**
+ * Finds the body span of an object, type literal, mapped type, or interface that can be collapsed safely.
+ *
+ * @param n AST node being considered for whitespace collapsing.
+ * @param src Original source text used to locate interface braces.
+ *
+ * @return Collapsible source span, or `undefined` when the node is unsupported or contains JSX.
+ */
+function candidateSpan(n, src) {
+    if (ts.isObjectLiteralExpression(n)) {
+        let containsJsx = false;
+        const findJsx = (c) => {
+            if (ts.isJsxElement(c) || ts.isJsxSelfClosingElement(c) || ts.isJsxFragment(c)) {
+                containsJsx = true;
+                return;
+            }
+            ts.forEachChild(c, findJsx);
+        };
+        ts.forEachChild(n, findJsx);
+        if (containsJsx)
+            return undefined;
+        return { start: n.getStart(), end: n.end };
+    }
+    if (ts.isTypeLiteralNode(n) || ts.isMappedTypeNode(n))
+        return { start: n.getStart(), end: n.end };
+    if (ts.isInterfaceDeclaration(n)) {
+        const start = src.indexOf('{', n.name.end);
+        const end = src.lastIndexOf('}', n.end - 1);
+        if (start >= 0 && end >= start)
+            return { start, end: end + 1 };
+    }
+    return undefined;
+}
+/*//////////////////////////////////////////////////
+EXPORTS
+//////////////////////////////////////////////////*/
+/**
+ * Collapses whitespace inside object and type bodies so Prettier alone decides whether they exceed print width.
+ *
+ * @param fileName Absolute path to the source file to rewrite.
+ *
+ * @return `true` when an eligible object or type body was collapsed; otherwise `false`.
+ */
+export function collapseTypesAndObjects(fileName) {
+    // ENVIRONMENT
+    if (!SUPPORTED.has(extname(fileName)))
+        return false;
+    const original = readFileSync(fileName, 'utf8');
+    const parsed = ts.createSourceFile(fileName, original, ts.ScriptTarget.Latest, true, scriptKind(fileName));
+    const edits = [];
+    // HELPERS
+    const collapse = (n, start, text) => {
+        if (!/[\r\n]/.test(text))
+            return undefined;
+        const protectedRanges = [];
+        const protectLiterals = (c) => {
+            if (ts.isStringLiteral(c) ||
+                ts.isRegularExpressionLiteral(c) ||
+                ts.isNoSubstitutionTemplateLiteral(c) ||
+                ts.isTemplateHead(c) ||
+                ts.isTemplateMiddle(c) ||
+                ts.isTemplateTail(c) ||
+                ts.isJsxText(c)) {
+                protectedRanges.push({ start: c.getStart(parsed) - start, end: c.end - start });
+                return;
+            }
+            ts.forEachChild(c, protectLiterals);
+        };
+        protectLiterals(n);
+        const isProtected = (pos) => protectedRanges.some((r) => pos >= r.start && pos < r.end);
+        const scanner = ts.createScanner(ts.ScriptTarget.Latest, false, parsed.languageVariant, text);
+        let result = '';
+        let whitespace = false;
+        for (let token = scanner.scan(); token !== ts.SyntaxKind.EndOfFileToken; token = scanner.scan()) {
+            const tokenStart = scanner.getTokenPos();
+            if ((token === ts.SyntaxKind.SingleLineCommentTrivia || token === ts.SyntaxKind.MultiLineCommentTrivia) && !isProtected(tokenStart))
+                return undefined;
+            if (token === ts.SyntaxKind.WhitespaceTrivia || token === ts.SyntaxKind.NewLineTrivia) {
+                if (isProtected(tokenStart)) {
+                    if (whitespace && result && !result.endsWith(' '))
+                        result += ' ';
+                    result += scanner.getTokenText();
+                    whitespace = false;
+                    continue;
+                }
+                whitespace = true;
+                continue;
+            }
+            if (whitespace && result && !result.endsWith(' '))
+                result += ' ';
+            result += scanner.getTokenText();
+            whitespace = false;
+        }
+        return result;
+    };
+    // ANALYSE
+    const visit = (n) => {
+        const span = candidateSpan(n, original);
+        if (span) {
+            const text = collapse(n, span.start, original.slice(span.start, span.end));
+            if (text !== undefined) {
+                edits.push({ ...span, text });
+                return;
+            }
+        }
+        ts.forEachChild(n, visit);
+    };
+    visit(parsed);
+    if (!edits.length)
+        return false;
+    const n = edits.sort((a, b) => b.start - a.start).reduce((t, e) => `${t.slice(0, e.start)}${e.text}${t.slice(e.end)}`, original);
+    if (n === original)
+        return false;
+    writeFileSync(fileName, n);
+    return true;
+}
+//# sourceMappingURL=collapse.js.map

package/dist/collapse.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"collapse.js","sourceRoot":"","sources":["../src/collapse.ts"],"names":[],"mappings":"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"}

package/dist/documentation.d.ts

@@ -0,0 +1,84 @@
+/**
+ * packages/quality/src/documentation.ts
+ * Create comments documenting the file, grouping imports, and sectioning code.
+ */
+import type { QualityAnalysis, QualityCfg } from './runner.js';
+/** Declaration categories that can require meaningful TSDoc descriptions. */
+export type DocumentationRequirements = {
+    types?: boolean;
+    functions?: boolean;
+    exportedFunctions?: boolean;
+    noInlineFunctions?: boolean;
+};
+/** A repeated named import reported within one source file. */
+export type DuplicateImportFinding = {
+    file: string;
+    line: number;
+    module: string;
+};
+/** One missing, malformed, or detached source-documentation item. */
+export type DocumentationFinding = {
+    file: string;
+    line: number;
+    column: number;
+    name: string;
+    kind: 'file' | 'summary' | 'param' | 'return' | 'tag' | 'type' | 'function' | 'inline' | 'orphan';
+    reason: string;
+    severity: 'warning' | 'error';
+};
+export declare const DOCUMENTATION_DESCRIPTION_NOTICE = "Ask an agent for meaningful documentation prose; this check only reports missing descriptions and never generates them in bulk.";
+/**
+ * Finds repeated named bindings that the source maintainer can merge without
+ * changing import evaluation order or side-effect-only imports.
+ *
+ * @param files Configured source files to inspect.
+ *
+ * @return One finding for each later import declaration that repeats a binding.
+ */
+export declare function duplicateImportFindings(files: string[]): DuplicateImportFinding[];
+/**
+ * Adds the canonical header, grouped imports, and top-level source sections.
+ *
+ * @param root Repository root used to create the file header path.
+ * @param fileName Absolute path to the source file to maintain.
+ *
+ * @return `true` when the file was rewritten; otherwise `false`.
+ */
+export declare function maintainSrcFile(root: string, fileName: string): boolean;
+/**
+ * Removes generated section scaffolding and empty or detached TSDoc after source edits.
+ *
+ * @param fileName Source filename whose generated or detached comments should be removed.
+ *
+ * @return Whether the file was changed after a validated write.
+ */
+export declare function removeNonCodeComments(fileName: string): boolean;
+/**
+ * Adds Prettier protection to one-line imports that exceed the configured print width.
+ *
+ * @param fileName Absolute path to the source file whose imports are inspected.
+ * @param printWidth Maximum line width before a Prettier ignore marker is inserted.
+ *
+ * @return `true` when one or more ignore markers were inserted.
+ */
+export declare function protectLongImports(fileName: string, printWidth?: number): boolean;
+/**
+ * Finds documentation-policy violations for the configured source scope.
+ *
+ * @param cfg Quality configuration containing required documentation policies.
+ * @param analysis Optional shared program and source cache for the current run.
+ *
+ * @return Documentation findings across the configured source scope.
+ */
+export declare function documentationFindings(cfg: QualityCfg, analysis?: QualityAnalysis): DocumentationFinding[];
+/**
+ * Inserts an empty TSDoc scaffold before declarations required to be documented.
+ * The scaffold never invents a description; prose must be authored after understanding the declaration.
+ *
+ * @param cfg Quality configuration containing documentation requirements.
+ * @param file Absolute source path to update.
+ *
+ * @return `true` when one or more scaffolds were inserted.
+ */
+export declare function documentSrcFile(cfg: QualityCfg, file: string): boolean;
+//# sourceMappingURL=documentation.d.ts.map

package/dist/documentation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"documentation.d.ts","sourceRoot":"","sources":["../src/documentation.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAaH,OAAO,KAAK,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAqC/D,6EAA6E;AAC7E,MAAM,MAAM,yBAAyB,GAAG;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,SAAS,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAAC,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAC3I,+DAA+D;AAC/D,MAAM,MAAM,sBAAsB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAMpF,qEAAqE;AACrE,MAAM,MAAM,oBAAoB,GAAG;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,UAAU,GAAG,QAAQ,GAAG,QAAQ,CAAC;IAClG,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,SAAS,GAAG,OAAO,CAAC;CAC9B,CAAC;AACF,eAAO,MAAM,gCAAgC,oIAAoI,CAAC;AAwKlL;;;;;;;GAOG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,MAAM,EAAE,GAAG,sBAAsB,EAAE,CAkCjF;AAkXD;;;;;;;GAOG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAwDvE;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CA6D/D;AAED;;;;;;;GAOG;AACH,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,MAAM,EAAE,UAAU,SAAM,GAAG,OAAO,CAyB9E;AAmWD;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,UAAU,EAAE,QAAQ,CAAC,EAAE,eAAe,GAAG,oBAAoB,EAAE,CAKzG;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAmBtE"}