npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@titan-design/style-analyzer

v0.1.7

Published

Tree-sitter style extractors that turn source files into observations, and the aggregator that turns observations into a style profile with confidence and stability

Downloads

651

Readme

@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 from codewatch's @codewatch/analyzer, with two bug fixes since: stability keys and Python constants (see Gotchas).

npm install @titan-design/style-analyzer web-tree-sitter@^0.26.6 zod
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 JSON .prettierrc (or .prettierrc.json) or an .editorconfig from disk. It reads only JSON .prettierrc: prettier.config.* and JS, TS, YAML or TOML .prettierrc.* files return []. From .editorconfig it reads only the [*] section. 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, seven emitted feature types; 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:

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:

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 keys are the exact emitted types, and stability.test.ts fails in both directions when they drift. UNRATED_TYPES lists the three emitted types the taxonomy never rated (control-flow.if-else, .promise-then, .else-after-return); they take medium on purpose. The original codewatch map used taxonomy spellings that matched none of 30 emitted types, so those types all fell back to medium (TP-172).
  • A Python assignment counts as naming.constant only at module scope (TP-173). Module scope means top level, or inside a module-level if, elif, else, try, except, finally or with block. Annotated and chained forms count. Class, function and loop bodies do not.
  • In both languages, a constant name is SCREAMING_SNAKE or one capitalised word of two or more characters (DEBUG, VERSION). A single letter such as T = TypeVar("T") or const K = 1 stays naming.variable PascalCase. A two-letter TypeVar such as KT = TypeVar("KT") counts as a constant.

The worked example and the full observation list are in the site reference page, site/reference/style-analyzer.md.