@titan-design/style-analyzer 0.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Henry Jewkes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,124 @@
+# @titan-design/style-analyzer
+
+Tree-sitter style extractors, and the aggregator that turns their output into a style
+profile. Each extractor reads a parsed TypeScript or Python file and emits `Observation`
+records: one per naming choice, import, branch, comment, function metric, and so on. The
+aggregator groups observations by type into features with a dominant convention, a
+confidence, a stability and a severity. An optional enricher asks an injected LLM to
+describe the features that numbers alone cannot capture.
+
+Tier 2 of the titan-platform DAG (TP-134). Depends on `@titan-design/code-parser` (tier 0)
+and `@titan-design/style-profile` (tier 2). `zod` v4 is a peer because style-profile
+needs it at runtime. Ported unchanged from codewatch's
+`@codewatch/analyzer`.
+
+```sh
+npm install @titan-design/style-analyzer web-tree-sitter@^0.26.6 zod
+```
+
+```ts
+import { Aggregator, createStyleExtractors, parseFile } from "@titan-design/style-analyzer";
+
+const file = await parseFile(source, "src/users.ts", "typescript");
+const observations = createStyleExtractors().flatMap((extractor) => extractor.extract(file));
+// { type: "naming.function", category: "naming", value: "camelCase", file: "src/users.ts", line: 3 }
+
+const { features, reviewQueue, summary } = new Aggregator().aggregate(observations);
+features.get("formatting.quoteStyle"); // { convention: "double", confidence: 1, severity: "error", ... }
+```
+
+## API
+
+- `Observation` is `{ type, category, value, file, line, metadata? }`. `type` is the feature
+  (`naming.variable`, `complexity.cyclomatic`), `value` is a string, number or boolean, and
+  `line` is 1-based.
+- `StyleExtractor` is `Extractor<Observation>` from code-parser. `Extractor` is its
+  deprecated alias, kept for compatibility.
+- `createStyleExtractors()` returns the canonical nine, in a fixed order: `NamingExtractor`,
+  `StructureExtractor`, `ControlFlowExtractor`, `DocumentationExtractor`,
+  `ErrorHandlingExtractor`, `FormattingExtractor`, `ComplexityExtractor`, `IdiomsExtractor`,
+  `ReviewVoiceExtractor`.
+- `FormattingExtractor.extractFromConfig(path)` reads a `.prettierrc` or `.editorconfig`
+  from disk. `extractFromSource(text, path)` works on raw text.
+- `IdiomsExtractor.extractFromSources([{ path, content, language }])` finds repeated code
+  across files with jscpd.
+- `ReviewVoiceExtractor.extractFromComments([{ body }])` classifies review comments by
+  topic and keyword.
+- `new Aggregator(config?).aggregate(observations)` returns `{ features, reviewQueue,
+  summary }`. `features` maps each observation type to an `AggregatedFeature`.
+  - Confidence is `min(1, consistency * weight)`. Consistency is the dominant value's
+    share, and the weight comes from the type's stability (high 1.0, medium 0.85, low 0.7).
+  - Severity follows style-profile's thresholds.
+  - A feature below `reviewThreshold` (default 0.6) joins `reviewQueue`, lowest first.
+  - `computeConfidence`, `mapSeverity` and `lookupStability` are exported on their own.
+- `new Enricher({ provider, enabled?, totalTokenBudget? }).enrich(features)` sends one
+  prompt per AI-enriched feature (`AI_ENRICHED_FEATURES`, `needsAiEnrichment`).
+  - Prompts run sequentially and stop once the token budget is used up (default 20,000).
+  - A failed call becomes an entry in `errors` instead of a throw.
+  - `enabled: false` returns `skipped: true` without calling the provider.
+- `IngestConfig`, `CodeCorpus`, `CodeFile`, `ReviewComment`, `PullRequest`,
+  `PullRequestFile` and `IngestMetadata` are the corpus types codewatch's ingestion
+  produced. They are types only; the GitHub ingestion itself was not ported.
+- `parseFile`, `getSupportedLanguages`, `shouldIncludeFile` and `getLanguageFromPath` are
+  re-exported from code-parser, as the original re-exported them from `@codewatch/core`.
+
+## Plugging in an LLM
+
+The enricher never picks a model. It takes an `LlmProvider`:
+
+```ts
+interface LlmProvider {
+  name: string;
+  generate(messages: LlmMessage[], options: { maxTokens: number }): Promise<LlmResponse>;
+}
+// LlmMessage is { role: "system" | "user" | "assistant", content }
+// LlmResponse is { content, tokensUsed }
+```
+
+A product that uses `@titan-design/agent` adapts it in a few lines. This package does not
+depend on the agent package:
+
+```ts
+import { runAgent } from "@titan-design/agent";
+import type { LlmProvider } from "@titan-design/style-analyzer";
+
+const agentProvider: LlmProvider = {
+  name: "claude-agent",
+  async generate(messages) {
+    const prompt = messages.map((m) => m.content).join("\n\n");
+    const result = await runAgent({ prompt, cwd: process.cwd(), maxTurns: 1, maxBudgetUsd: 0.05 });
+    if (!result.ok) throw new Error(result.failure.kind);
+    const tokensUsed = Object.values(result.usage.modelUsage)
+      .reduce((sum, u) => sum + u.inputTokens + u.outputTokens, 0);
+    return { content: result.output, tokensUsed };
+  },
+};
+```
+
+`runAgent` has no system prompt field and budgets in turns and dollars, not tokens. The
+adapter therefore folds the system message into the prompt and ignores `maxTokens`.
+Throwing on a failed run is what lets the enricher record the failure and carry on.
+
+## Dependencies
+
+`web-tree-sitter` is a peer dependency, for the same reason code-parser makes it one:
+`ParsedFile.tree` is a web-tree-sitter `Tree`, and the extractors walk it with that
+package's `Node` type, so the parser and the extractors must see one copy. This package
+imports it for types only. `@jscpd/core` 3.5.10 and `@jscpd/tokenizer` 3.5.4 stay pinned
+at the original's versions.
+
+## Gotchas
+
+- `IdiomsExtractor.extract` and `ReviewVoiceExtractor.extract` return `[]`. Their real
+  inputs are a set of sources and a list of review comments, not one parsed file.
+- `FormattingExtractor` works on text with regular expressions, so it also reports
+  semicolons and quote style for Python files.
+- `extractFromConfig` swallows every error, including a missing file or malformed JSON,
+  and returns `[]`.
+- Review-voice observations use `file: "_reviews"` and `line: 0`.
+- `STABILITY_MAP` uses spellings the extractors do not emit. Examples are
+  `naming.variables` against the emitted `naming.variable`, and `controlFlow.*` against
+  `control-flow.*`. Those types fall back to `medium`. This is the original's behaviour.
+
+The worked example and the full observation list are in the site reference page,
+`site/reference/style-analyzer.md`.

package/dist/index.d.ts

@@ -0,0 +1,351 @@
+import { Extractor as Extractor$1, ParsedFile } from '@titan-design/code-parser';
+export { ParsedFile, getLanguageFromPath, getSupportedLanguages, parseFile, shouldIncludeFile } from '@titan-design/code-parser';
+import { ProfileCategory, SeverityThresholds, Severity } from '@titan-design/style-profile';
+export { Severity, SeverityThresholds } from '@titan-design/style-profile';
+
+interface IngestConfig {
+    repos: string[];
+    since?: string;
+    until?: string;
+    languages: string[];
+    githubToken: string;
+    cacheDir?: string;
+}
+interface CodeFile {
+    path: string;
+    content: string;
+    language: string;
+    repo: string;
+    sha: string;
+}
+interface ReviewComment$1 {
+    body: string;
+    path: string;
+    line: number | null;
+    author: string;
+    prNumber: number;
+    repo: string;
+    createdAt: string;
+}
+interface PullRequest {
+    number: number;
+    title: string;
+    repo: string;
+    author: string;
+    files: PullRequestFile[];
+    comments: ReviewComment$1[];
+}
+interface PullRequestFile {
+    filename: string;
+    status: "added" | "modified" | "removed" | "renamed";
+    patch?: string;
+    additions: number;
+    deletions: number;
+}
+interface CodeCorpus {
+    files: CodeFile[];
+    pullRequests: PullRequest[];
+    reviewComments: ReviewComment$1[];
+    metadata: IngestMetadata;
+}
+interface IngestMetadata {
+    repos: string[];
+    author: string;
+    since?: string;
+    until?: string;
+    fetchedAt: string;
+    totalCommits: number;
+    totalFiles: number;
+    totalReviewComments: number;
+}
+
+/**
+ * Categories that extractors emit. Includes all ProfileCategory values
+ * plus extractor-specific categories that don't map directly to profile sections.
+ */
+type ObservationCategory = ProfileCategory | "control-flow" | "error-handling" | "reviewVoice" | "idioms" | "complexity";
+interface Observation {
+    /** Feature type, e.g. "naming.variable", "naming.function" */
+    type: string;
+    /** Top-level category, e.g. "naming", "structure" */
+    category: ObservationCategory;
+    /** Detected value, e.g. "camelCase", true, 28 */
+    value: string | number | boolean;
+    /** Source file path */
+    file: string;
+    /** Line number (1-based) */
+    line: number;
+    /** Additional context for aggregation */
+    metadata?: Record<string, unknown>;
+}
+/** Style extractor — produces per-file style Observations. */
+type StyleExtractor = Extractor$1<Observation>;
+/** @deprecated Use StyleExtractor. Retained for backward compatibility. */
+type Extractor = StyleExtractor;
+
+declare class NamingExtractor implements StyleExtractor {
+    readonly name = "naming";
+    extract(file: ParsedFile): Observation[];
+    private processNode;
+    private processTypeScriptNode;
+    private processTypeScriptVariable;
+    private processTypeScriptParameter;
+    private processPythonNode;
+    private processPythonAssignment;
+    private processPythonParameters;
+    private observeVariable;
+    private observeDeclarationName;
+    private detectPrivateMembers;
+    private addObservation;
+}
+
+declare class StructureExtractor implements StyleExtractor {
+    readonly name = "structure";
+    extract(file: ParsedFile): Observation[];
+    private extractImports;
+    private addImportOrder;
+    private importSource;
+    private extractExports;
+    private processExport;
+    private exportProximity;
+    private detectBarrelFile;
+}
+
+declare class ControlFlowExtractor implements StyleExtractor {
+    readonly name = "control-flow";
+    extract(file: ParsedFile): Observation[];
+    private walk;
+    private processNode;
+    private processBranch;
+    private processLoop;
+    private processCall;
+    private processMemberCall;
+    private detectGuardClause;
+    private isFunctionBody;
+    private detectElseAfterReturn;
+    private containsReturn;
+    private emit;
+}
+
+declare class DocumentationExtractor implements StyleExtractor {
+    readonly name = "documentation";
+    extract(file: ParsedFile): Observation[];
+    private walkDeclarations;
+    private isDeclaration;
+    private processDeclaration;
+    private hasLeadingDoc;
+    private hasJSDoc;
+    private hasPythonDocstring;
+    private extractTags;
+    private extractPythonDocTags;
+    private walkForComments;
+    private getCommentPlacement;
+    private isExported;
+    private getLeadingComment;
+    private emit;
+}
+
+declare class ErrorHandlingExtractor implements StyleExtractor {
+    readonly name = "error-handling";
+    extract(file: ParsedFile): Observation[];
+    private walk;
+    private processNode;
+    private processDeclaration;
+    private processFunctionCheck;
+    private analyzeCatchClauses;
+    private hasInstanceofCheck;
+    private detectCustomErrorClass;
+    private detectResultType;
+    private detectResultReturnType;
+    private detectAssertNever;
+    private detectExhaustiveSwitch;
+    private emit;
+}
+
+declare class FormattingExtractor implements StyleExtractor {
+    readonly name = "formatting";
+    extract(file: ParsedFile): Observation[];
+    extractFromConfig(configPath: string): Promise<Observation[]>;
+    extractFromSource(source: string, filePath: string): Observation[];
+    private detectSemicolons;
+    private detectQuoteStyle;
+    private detectTrailingCommas;
+    private detectBraceStyle;
+    private detectIndentation;
+    private countIndentation;
+    private isComment;
+    private isStructuralLine;
+    private isStatementStart;
+    private findGcdOfArray;
+    private gcd;
+}
+
+declare class ComplexityExtractor implements StyleExtractor {
+    readonly name = "complexity";
+    extract(file: ParsedFile): Observation[];
+    private functionObservations;
+    private getFunctionTypes;
+    private findFunctions;
+    private analyzeFunctionNode;
+    private countStatements;
+    private isStatement;
+    private isTypeScriptStatement;
+    private isPythonStatement;
+    private measureNestingDepth;
+    private measureCyclomaticComplexity;
+    private branchIncrement;
+}
+
+interface SourceFile {
+    content: string;
+    path: string;
+    language: string;
+}
+declare class IdiomsExtractor implements StyleExtractor {
+    readonly name = "idioms";
+    private minLines;
+    private minTokens;
+    constructor(options?: {
+        minLines?: number;
+        minTokens?: number;
+    });
+    extract(_file: ParsedFile): Observation[];
+    extractFromSources(sources: SourceFile[]): Promise<Observation[]>;
+    private cloneObservation;
+    private detectClones;
+    private runDetector;
+    private toCloneGroup;
+    private toInstance;
+    private extractFragment;
+    private languageToFormat;
+    private groupClones;
+    private mergeInstances;
+    private normalizeFragment;
+    private summarizeClone;
+}
+
+interface ReviewComment {
+    body: string;
+    file?: string;
+}
+declare class ReviewVoiceExtractor implements StyleExtractor {
+    readonly name = "reviewVoice";
+    extract(_file: ParsedFile): Observation[];
+    extractFromComments(comments: ReviewComment[]): Observation[];
+    private categorizeTopics;
+    private countTopics;
+    private matchTopics;
+    private extractKeywords;
+}
+
+/**
+ * Canonical set of style extractors. Single source of truth — CLI commands,
+ * scripts, and tests should import this rather than reconstructing the list.
+ */
+declare function createStyleExtractors(): StyleExtractor[];
+
+type Stability = "high" | "medium" | "low";
+declare function lookupStability(type: string): Stability;
+
+interface StabilityWeights {
+    high: number;
+    medium: number;
+    low: number;
+}
+declare function computeConfidence(consistency: number, stability: Stability, weights?: StabilityWeights): number;
+declare function mapSeverity(confidence: number, thresholds?: SeverityThresholds): Severity;
+
+interface FrequencyDistribution {
+    values: Map<string | number | boolean, number>;
+    total: number;
+    dominant: string | number | boolean;
+    consistency: number;
+}
+
+interface AggregatedFeature {
+    type: string;
+    category: ObservationCategory;
+    convention: string | number | boolean | string[];
+    distribution: FrequencyDistribution;
+    confidence: number;
+    stability: Stability;
+    severity: Severity;
+    needsReview: boolean;
+    examples: Observation[];
+}
+interface AggregatorConfig {
+    stabilityWeights?: StabilityWeights;
+    severityThresholds?: SeverityThresholds;
+    reviewThreshold?: number;
+    maxExamples?: number;
+}
+interface AggregatorResult {
+    features: Map<string, AggregatedFeature>;
+    reviewQueue: AggregatedFeature[];
+    summary: {
+        totalObservations: number;
+        totalFeatures: number;
+        avgConfidence: number;
+        featuresNeedingReview: number;
+    };
+}
+declare class Aggregator {
+    private stabilityWeights;
+    private severityThresholds;
+    private reviewThreshold;
+    private maxExamples;
+    constructor(config?: AggregatorConfig);
+    aggregate(observations: Observation[]): AggregatorResult;
+    private buildFeature;
+    private extractCategory;
+}
+
+interface LlmMessage {
+    role: "system" | "user" | "assistant";
+    content: string;
+}
+interface LlmResponse {
+    content: string;
+    tokensUsed: number;
+}
+interface LlmProvider {
+    name: string;
+    generate(messages: LlmMessage[], options: {
+        maxTokens: number;
+    }): Promise<LlmResponse>;
+}
+
+declare const AI_ENRICHED_FEATURES: string[];
+declare function needsAiEnrichment(featureType: string): boolean;
+
+interface EnrichmentEntry {
+    featureType: string;
+    description: string;
+    tokensUsed: number;
+}
+interface EnrichmentError {
+    featureType: string;
+    error: string;
+}
+interface EnrichmentResult {
+    enriched: Map<string, EnrichmentEntry>;
+    errors: EnrichmentError[];
+    totalTokensUsed: number;
+    budgetExceeded: boolean;
+    skipped: boolean;
+}
+interface EnricherConfig {
+    provider: LlmProvider;
+    enabled?: boolean;
+    totalTokenBudget?: number;
+}
+declare class Enricher {
+    private runner;
+    private enabled;
+    constructor(config: EnricherConfig);
+    enrich(features: Map<string, AggregatedFeature>): Promise<EnrichmentResult>;
+    private buildJobs;
+    private buildPromptInput;
+}
+
+export { AI_ENRICHED_FEATURES, type AggregatedFeature, Aggregator, type AggregatorConfig, type AggregatorResult, type CodeCorpus, type CodeFile, ComplexityExtractor, ControlFlowExtractor, DocumentationExtractor, Enricher, type EnricherConfig, type EnrichmentEntry, type EnrichmentError, type EnrichmentResult, ErrorHandlingExtractor, type Extractor, FormattingExtractor, type FrequencyDistribution, IdiomsExtractor, type IngestConfig, type IngestMetadata, type LlmMessage, type LlmProvider, type LlmResponse, NamingExtractor, type Observation, type ObservationCategory, type PullRequest, type PullRequestFile, type ReviewComment$1 as ReviewComment, ReviewVoiceExtractor, type Stability, type StabilityWeights, StructureExtractor, type StyleExtractor, computeConfidence, createStyleExtractors, lookupStability, mapSeverity, needsAiEnrichment };