shadscan-vue 0.0.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+Every entry below is generated by release-please from conventional commits. The
+`0.0.0` bootstrap publish exists only so npm can attach a trusted publisher to
+the package; it is deprecated once the first real release lands.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vinayak Kulkarni
+
+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,110 @@
+# shadscan-vue
+
+> Find the UI fundamentals your shadcn-vue app forgot.
+
+Deterministic checks. Evidence. Agent-ready fixes. Static audit — no AI required.
+
+`shadscan-vue` audits **shadcn-vue** (Vue 3 + Vite) and **shadcn-nuxt** (Nuxt 4)
+applications for the fundamentals that are easy to skip and expensive to miss:
+theme wiring, command menus, route and error states, accessible controls, form
+feedback, metadata, and mobile behavior.
+
+```bash
+npx shadscan-vue
+```
+
+It never starts your app, never edits files, never calls a model, and never
+uploads your source. Every finding cites a file and a line.
+
+## What you get
+
+```
+shadscan-vue v0.1.0
+my-app · nuxt · pnpm
+
+Score 66/100 · Grade D
+
+Foundation             ████████████████░░░░ 84
+Interaction            ██████████░░░░░░░░░░ 52
+States                 ████████████████░░░░ 84
+Accessibility          ████████████░░░░░░░░ 61
+Forms and Data Entry   ███░░░░░░░░░░░░░░░░░ 18
+Production Polish      ████████████████░░░░ 78
+
+Findings
+
+  FAIL images-have-alt (accessibility, error)
+    <img> is missing alternative text.
+      app/pages/index.vue:23
+      fix: Add an alt attribute describing the image, or bind :alt to dynamic content.
+```
+
+## Scoring
+
+52 rules across six weighted categories:
+
+| Category             | Weight |
+| -------------------- | -----: |
+| Foundation           |     20 |
+| Interaction          |     20 |
+| States               |     20 |
+| Accessibility        |     20 |
+| Forms and Data Entry |     10 |
+| Production Polish    |     10 |
+
+Findings fall into four buckets. **Fixes** are provable failures that cost
+points. **Advisories** are lower-confidence observations that never subtract
+points. **Passes** are verified. **Not applicable** rules leave the score
+untouched — a project without forms is not penalised for form rules.
+
+Grades: A ≥ 90, B ≥ 80, C ≥ 70, D ≥ 60, otherwise F.
+
+## Usage
+
+```bash
+shadscan-vue [path]                      # audit a project (defaults to .)
+shadscan-vue --json                      # machine-readable report
+shadscan-vue --prompt                    # paste-ready prompt for an AI agent
+shadscan-vue --category accessibility    # run one category
+shadscan-vue --fail-under 70             # exit 1 below a threshold
+shadscan-vue rules                       # print the rule catalog
+shadscan-vue setup --pre-commit          # install a git pre-commit hook
+```
+
+Exit codes are `0` (completed) and `1` (threshold not met, or an error).
+
+### Continuous integration
+
+```yaml
+- run: npx shadscan-vue --fail-under 70 --no-interactive
+```
+
+`--fail-under` also fails when the score is unassessed or when source coverage
+was partial, so a silently-skipped scan cannot pass a gate.
+
+### Agent handoff
+
+`--prompt` emits a remediation brief with the machine-readable report embedded
+in a delimited block, marked as untrusted data rather than instructions.
+
+## Supported projects
+
+| Adapter       | Detected by                   |
+| ------------- | ----------------------------- |
+| `nuxt`        | a `nuxt` dependency           |
+| `vite-vue`    | `vue` and `vite` dependencies |
+| `generic-vue` | a `vue` dependency            |
+
+shadcn components are recognised through `components.json` aliases, through the
+`components/ui` convention, and through `shadcn-nuxt` auto-imports.
+
+## Credits
+
+shadscan-vue is a Vue and Nuxt port of [shadscan](https://github.com/TheOrcDev/shadscan)
+by [TheOrcDev](https://github.com/TheOrcDev), built with the original author's
+permission. The rule taxonomy, scoring model, and product concept originate
+there. See [THIRD_PARTY_NOTICES.md](./THIRD_PARTY_NOTICES.md).
+
+## License
+
+[MIT](./LICENSE.md) © Vinayak Kulkarni. Portions derived from shadscan, MIT © 2026 TheOrcDev.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,33 @@
+# Third-Party Notices
+
+## shadscan
+
+shadscan-vue is a Vue/Nuxt port of [shadscan](https://github.com/TheOrcDev/shadscan)
+by [TheOrcDev](https://github.com/TheOrcDev), created with the original author's
+permission. The rule taxonomy, scoring model, CLI contract, and product concept
+originate from shadscan. Portions of this software are derived from or
+substantially based on shadscan, which is licensed under the MIT License:
+
+```
+MIT License
+
+Copyright (c) 2026 TheOrcDev
+
+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/bin/shadscan-vue.mjs

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import { run } from '../dist/index.js';
+
+const code = await run(process.argv);
+process.exit(code);

package/dist/index.d.ts

@@ -0,0 +1,309 @@
+import { SFCDescriptor, SFCParseResult } from "@vue/compiler-sfc";
+import { RootNode } from "@vue/compiler-dom";
+import ts from "typescript";
+//#region src/cli.d.ts
+declare const run: (argv: readonly string[]) => Promise<number>;
+//#endregion
+//#region src/discovery.d.ts
+type AdapterId = 'nuxt' | 'vite-vue' | 'generic-vue';
+type PackageManagerId = 'pnpm' | 'yarn' | 'npm' | 'bun' | 'unknown';
+interface ShadcnAliases {
+  utils?: string;
+  components?: string;
+  ui?: string;
+  lib?: string;
+  composables?: string;
+}
+interface ShadcnDiscovery {
+  /** components.json exists and parsed cleanly. */
+  configPresent: boolean;
+  confidence: 'high' | 'low';
+  style?: string;
+  tailwindCss?: string;
+  aliases: ShadcnAliases;
+  /** Resolved alias for ui components (aliases.ui or `${aliases.components}/ui`). */
+  uiAlias?: string;
+  /** shadcn-nuxt module dependency detected. */
+  nuxtModule: boolean;
+  /** Statically-read shadcn-nuxt component prefix, when determinable. */
+  nuxtPrefix?: string;
+}
+interface ProjectDiscovery {
+  /** Absolute real path of the scanned project root. */
+  rootDir: string;
+  packageName: string;
+  packageManager: PackageManagerId;
+  adapter: AdapterId;
+  /** Merged dependencies + devDependencies from package.json. */
+  dependencies: Record<string, string>;
+  shadcn: ShadcnDiscovery;
+  warnings: string[];
+}
+declare const discoverProject: (inputPath: string) => Promise<ProjectDiscovery>;
+//#endregion
+//#region src/source-requirements.d.ts
+type CoverageStatus = 'complete' | 'partial';
+interface SourceCoverage {
+  status: CoverageStatus;
+  fileCount: number;
+  totalBytes: number;
+  warnings: string[];
+}
+//#endregion
+//#region src/rules/source-files.d.ts
+type SourceKind = 'vue' | 'ts' | 'js' | 'html';
+interface SourceFile {
+  /** Absolute path. */
+  path: string;
+  /** Project-root-relative posix path. */
+  relPath: string;
+  kind: SourceKind;
+  text: string;
+}
+interface StyleFile {
+  path: string;
+  relPath: string;
+  text: string;
+}
+interface CollectedSources {
+  files: SourceFile[];
+  styles: StyleFile[];
+  coverage: SourceCoverage;
+}
+//#endregion
+//#region src/parse/sfc.d.ts
+interface ParsedSfc {
+  descriptor: SFCDescriptor;
+  templateAst?: RootNode;
+  errors: SFCParseResult['errors'];
+}
+//#endregion
+//#region src/parse/typescript.d.ts
+interface ScriptImport {
+  moduleSpecifier: string;
+  /** Imported binding names (local names after `as` renames use original name). */
+  named: string[];
+  defaultName?: string;
+  namespaceName?: string;
+  line: number;
+}
+//#endregion
+//#region src/parse/project-files.d.ts
+interface ParsedFile {
+  relPath: string;
+  path: string;
+  kind: SourceFile['kind'];
+  text: string;
+  /** Present for .vue files that parsed. */
+  sfc?: ParsedSfc;
+  /** TS AST of .ts/.js files, or of the SFC's script/scriptSetup content. */
+  scriptAst?: ts.SourceFile;
+  imports: ScriptImport[];
+  parseError?: string;
+}
+//#endregion
+//#region src/rules/rule-result.d.ts
+interface Evidence {
+  path: string;
+  line?: number;
+}
+interface Finding {
+  message: string;
+  evidence: Evidence[];
+  remediation?: string;
+}
+type RuleStatus = 'pass' | 'fail' | 'advisory' | 'not-applicable';
+interface RuleResult {
+  status: RuleStatus;
+  findings: Finding[];
+}
+declare const pass: () => RuleResult;
+declare const fail: (findings: Finding[]) => RuleResult;
+declare const advisory: (findings: Finding[]) => RuleResult;
+declare const notApplicable: () => RuleResult;
+//#endregion
+//#region src/audit.d.ts
+type AuditCategoryId = 'foundation' | 'interaction' | 'states' | 'accessibility' | 'forms' | 'production-polish';
+type Severity = 'error' | 'warning' | 'info';
+type Confidence = 'high' | 'medium' | 'low';
+interface CategoryDefinition {
+  id: AuditCategoryId;
+  title: string;
+  weight: number;
+}
+declare const CATEGORIES: readonly CategoryDefinition[];
+interface AuditContext {
+  discovery: ProjectDiscovery;
+  sources: () => Promise<ParsedFile[]>;
+  styles: () => Promise<StyleFile[]>;
+  /** Reserved for the Vue component render graph (later wave). */
+  componentRenderGraph: () => never;
+  helpers: {
+    /**
+     * True when a module specifier resolves to the project's shadcn ui
+     * directory (`.../ui/<module>` or the configured ui alias).
+     */
+    isShadcnUiImport: (moduleSpecifier: string) => boolean;
+  };
+  result: {
+    pass: typeof pass;
+    fail: typeof fail;
+    advisory: typeof advisory;
+    notApplicable: typeof notApplicable;
+  };
+}
+interface AuditRule {
+  id: string;
+  title: string;
+  description: string;
+  category: AuditCategoryId;
+  severity: Severity;
+  confidence: Confidence;
+  maxScore: number;
+  adapters: readonly AdapterId[];
+  run: (context: AuditContext) => Promise<RuleResult> | RuleResult;
+}
+interface RuleOutcome {
+  rule: AuditRule;
+  status: RuleStatus;
+  findings: Finding[];
+  /** Points awarded (0 for fail; maxScore for pass/advisory). */
+  score: number;
+  impactsScore: boolean;
+}
+interface CategoryScore {
+  id: AuditCategoryId;
+  title: string;
+  weight: number;
+  /** 0-100 within the category, or undefined when no applicable scored rules. */
+  score?: number;
+  rawScore: number;
+  rawMax: number;
+  ruleCount: number;
+}
+interface AuditReport {
+  score?: number;
+  grade?: string;
+  categories: CategoryScore[];
+  outcomes: RuleOutcome[];
+  warnings: string[];
+  durationMs: number;
+}
+declare const gradeFor: (score: number) => string;
+interface RunAuditOptions {
+  category?: AuditCategoryId;
+}
+declare const runAudit: (discovery: ProjectDiscovery, rules: readonly AuditRule[], options?: RunAuditOptions) => Promise<AuditReport & {
+  collected: CollectedSources;
+}>;
+//#endregion
+//#region src/scan.d.ts
+declare const RULESET_VERSION = "0.1.0";
+interface ScanResult {
+  discovery: ProjectDiscovery;
+  report: AuditReport & {
+    collected: CollectedSources;
+  };
+}
+interface ScanOptions {
+  category?: AuditCategoryId;
+}
+declare const scanProject: (inputPath: string, options?: ScanOptions) => Promise<ScanResult>;
+//#endregion
+//#region src/rules/index.d.ts
+/**
+ * Canonical ordered rule registry. Order is part of the deterministic output
+ * contract: rules run and render in registry order.
+ */
+declare const defaultRules: readonly AuditRule[];
+//#endregion
+//#region src/render-json.d.ts
+declare const JSON_SCHEMA_VERSION = 1;
+interface JsonReport {
+  schemaVersion: number;
+  engineVersion: string;
+  rulesetVersion: string;
+  score: number | null;
+  maxScore: number;
+  grade: string | null;
+  framework: {
+    adapter: string;
+    packageName: string;
+  };
+  packageManager: string;
+  shadcn: {
+    configPresent: boolean;
+    confidence: string;
+    style?: string;
+    uiAlias?: string;
+    nuxtModule: boolean;
+  };
+  coverage: {
+    status: string;
+    fileCount: number;
+    warnings: string[];
+  };
+  categories: {
+    id: string;
+    title: string;
+    weight: number;
+    score: number | null;
+    ruleCount: number;
+  }[];
+  findings: {
+    id: string;
+    title: string;
+    category: string;
+    severity: string;
+    confidence: string;
+    status: string;
+    score: number;
+    maxScore: number;
+    impactsScore: boolean;
+    message: string | null;
+    evidence: {
+      path: string;
+      line?: number;
+    }[];
+    remediation: string | null;
+  }[];
+  warnings: string[];
+  durationMs: number;
+}
+declare const buildJsonReport: (result: ScanResult, engineVersion: string) => JsonReport;
+declare const renderJson: (result: ScanResult, engineVersion: string) => string;
+//#endregion
+//#region src/terminal-capabilities.d.ts
+/**
+ * Terminal capability resolution. Rich rendering (color, unicode) only on a
+ * capable interactive TTY; deterministic plain ASCII when piped or in CI.
+ */
+interface TerminalCapabilities {
+  isTTY: boolean;
+  isCI: boolean;
+  color: boolean;
+  unicode: boolean;
+}
+//#endregion
+//#region src/render-human.d.ts
+declare const renderHuman: (result: ScanResult, engineVersion: string, caps?: TerminalCapabilities, roast?: boolean) => string;
+//#endregion
+//#region src/render-agent-prompt.d.ts
+declare const PROMPT_VERSION = 1;
+declare const renderAgentPrompt: (result: ScanResult, engineVersion: string) => string;
+//#endregion
+//#region src/cli-error.d.ts
+/**
+ * Stable, typed CLI failures. Every expected failure path throws a `CliError`
+ * with a machine-readable `code`; anything else is an internal error.
+ */
+type CliErrorCode = 'invalid-path' | 'not-a-project' | 'invalid-package-json' | 'unsupported-project' | 'invalid-flag' | 'conflicting-flags' | 'threshold-not-met' | 'internal-error';
+declare class CliError extends Error {
+  readonly code: CliErrorCode;
+  readonly exitCode: number;
+  constructor(code: CliErrorCode, message: string, exitCode?: number);
+}
+declare const isCliError: (error: unknown) => error is CliError;
+//#endregion
+export { type AdapterId, type AuditCategoryId, type AuditContext, type AuditReport, type AuditRule, CATEGORIES, type CategoryScore, CliError, type CliErrorCode, type Confidence, type Evidence, type Finding, JSON_SCHEMA_VERSION, PROMPT_VERSION, type PackageManagerId, type ProjectDiscovery, RULESET_VERSION, type RuleOutcome, type RuleResult, type RuleStatus, type ScanOptions, type ScanResult, type Severity, type ShadcnDiscovery, advisory, buildJsonReport, defaultRules, discoverProject, fail, gradeFor, isCliError, notApplicable, pass, renderAgentPrompt, renderHuman, renderJson, run, runAudit, scanProject };
+//# sourceMappingURL=index.d.ts.map