@frame12/lint 0.0.0-stage → 0.2.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Laqwan Brodie
+
+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

@@ -1,3 +1,226 @@
-# Temporary Holding Version
+# `@frame12/lint`
 
-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.
+Zero-dependency design-grammar checker for [FRAME/12](../../README.md) across TypeScript/JSX (`.tsx`, `.ts`, `.jsx`, `.js`), CSS (`.css`), and generated HTML (`lintHtml()`).
+
+> **Distribution status:** `@frame12/lint` is currently a workspace package in the `lbrodie11/frame12` monorepo (`packages/lint`) and is not yet published to the public npm registry.
+
+---
+
+## Usage
+
+### Library API
+
+```ts
+import {
+  lintSource,
+  lintFiles,
+  lintDirectory,
+  collectFiles,
+  lintHtml,
+  RULES,
+  type RuleId,
+  type Violation,
+} from '@frame12/lint';
+
+// 1. Lint TSX / JSX / TS / JS / CSS source text
+const tsxViolations: Violation[] = lintSource(code, 'src/app/page.tsx');
+
+// 2. Lint generated HTML documents or fragments
+const htmlViolations: Violation[] = lintHtml(htmlString, {
+  file: 'report.html',
+  tokenStyleIds: ['f12-tokens'], // <style id="f12-tokens"> or <style data-f12-tokens> is exempt
+});
+
+// 3. Lint directories or file paths on disk (.tsx, .ts, .jsx, .js, .css, .html, .htm)
+const { files, violations } = lintDirectory(['src/components', 'src/app', 'dist/report.html']);
+```
+
+### CLI (`@frame12/lint` / `frame12-lint`)
+
+```bash
+npx @frame12/lint src/app src/components dist/report.html
+# PASS  check-frame12: 43 file(s) checked, 0 violations.
+```
+
+The CLI accepts `.tsx`, `.ts`, `.jsx`, `.js`, `.css`, `.html`, and `.htm` files or directories (routing `.html` / `.htm` files to `lintHtml()`), and exits with code `1` if violations are found or if `0` lintable files match the target paths.
+
+### Optional `typescript` Peer Dependency
+
+`typescript` (`>=5.0.0`) is an **optional** peer dependency:
+- When `typescript` is installed, `lintSource()` parses JSX/TSX with the TypeScript compiler AST (`ts.createSourceFile`) to trace `cut-order` and `explicit-cut-in-autocut` through spread props, local variable identifiers, and `<PanelPair>` slots.
+- When `typescript` is not installed (for example, in a standalone HTML generator that only calls `lintHtml()`), `lintHtml()` and all CSS/regex source rules work with zero dependencies, and `lintSource()` emits a one-time `WARN  [@frame12/lint]` notice on `stderr` (suppressible via `{ quietFallbackWarning: true }`) before falling back to its built-in regex cut scanner.
+
+---
+
+## Rules
+
+Every violation carries a stable `rule` ID (`RuleId`), `file`, 1-based `line` and `column`, human-readable `message`, and `snippet`.
+
+| Rule ID | Summary |
+| :--- | :--- |
+| [`color-literal`](#color-literal) | Forbid hard-coded color literals (`#hex`, `rgb`/`hsl`/`oklch`, CSS gradients, font names) outside token definitions; use `var(--f-*)` tokens. |
+| [`illegal-gutter`](#illegal-gutter) | Permit only `0`, `12px` (`--f-gutter-pair`), `20px` (`--f-gutter-scene`), or `32px` (`--f-gutter-change`) gutters on `gap`, `grid-gap`, `row-gap`, and `column-gap`. |
+| [`marker-misuse`](#marker-misuse) | Permit `--f-marker` (`#ffd60a`) only as a surface background paired with `color: var(--f-marker-ink)` in the same rule; never on text, borders, outlines, shadows, or SVG strokes/fills. |
+| [`cut-order`](#cut-order) | Require panel cut labels (`C-01`, `C-02`, …) to use two-digit formatting and appear in strict sequential reading order starting at `C-01` without gaps or duplicates. |
+| [`explicit-cut-in-autocut`](#explicit-cut-in-autocut) | Forbid explicit `cut` props on `Panel`/`PanelPair` inside `<Sheet autoCut>` where cuts are numbered automatically. |
+| [`raw-shadcn-import`](#raw-shadcn-import) | Forbid raw `@/components/ui/*`, `@radix-ui/*`, or third-party chart/motion imports where a FRAME/12 component or adapter exists. |
+| [`unsafe-html`](#unsafe-html) | Forbid external resource loads (`<script src>`, `<link href>`, `<img src>`, CSS `@import`/`url()`), embedded frames (`<iframe>`, `<object>`, `<embed>`, `srcdoc`), `<meta http-equiv="refresh">`, `<base href>`, inline `on*=` handlers, and `javascript:` URLs in generated HTML. |
+
+---
+
+### `color-literal`
+
+Forbid hard-coded color literals (`#hex`, `rgb()`, `hsl()`, `oklch()`, CSS gradients, and raw font-family names) outside token files (`frame12.css`, `frame12-tokens.css`, `<style data-f12-tokens>`, or `opts.tokenStyleIds`). Use `var(--f-*)` and `var(--font-f-*)` tokens instead.
+
+**Bad:**
+```css
+.card {
+  background: #ffffff;
+  color: rgb(18, 18, 18);
+  background-image: linear-gradient(180deg, #fff, #eee);
+  font-family: "Dela Gothic One", sans-serif;
+}
+```
+
+**Good:**
+```css
+.card {
+  background: var(--f-panel);
+  color: var(--f-ink);
+  font-family: var(--font-f-display);
+}
+```
+
+---
+
+### `illegal-gutter`
+
+Permit only `0`, `12px` (`--f-gutter-pair`), `20px` (`--f-gutter-scene`), or `32px` (`--f-gutter-change`) gutters on `<Scene gutter="...">`, CSS `gap` / `grid-gap` / `row-gap` / `column-gap`, inline styles, and Tailwind `gap-*` classes.
+
+**Bad:**
+```html
+<div class="grid gap-4" style="gap: 14px"></div>
+```
+
+**Good:**
+```html
+<div class="grid gap-gutter-scene" style="gap: var(--f-gutter-pair)"></div>
+```
+
+---
+
+### `marker-misuse`
+
+Permit `--f-marker` (`#ffd60a`) only as a surface background paired with `color: var(--f-marker-ink)` in the same CSS rule or inline style object. Never use `--f-marker` on `color`, `border`, `outline`, `box-shadow`, or SVG `stroke` / `fill`.
+
+**Bad:**
+```css
+.focus-ring:focus-visible {
+  outline: var(--f-stroke) solid var(--f-marker);
+}
+.badge {
+  background: var(--f-marker);
+}
+```
+
+**Good:**
+```css
+.focus-ring:focus-visible {
+  outline: var(--f-stroke) solid var(--f-rule);
+}
+.badge {
+  background: var(--f-marker);
+  color: var(--f-marker-ink);
+}
+```
+
+---
+
+### `cut-order`
+
+Require panel cut labels (`C-01`, `C-02`, `C-03`, …) to use two-digit `C-NN` formatting, start at `C-01`, and increase sequentially by 1 in DOM/reading order without gaps or duplicates. Quiet panels (`variant="quiet"`) must not carry cut labels, and `data-cut="auto"` (or empty `data-cut=""`) is ignored.
+
+**Bad:**
+```html
+<section class="panel" data-cut="1">First</section>
+<section class="panel" data-cut="C-03">Skipped C-02</section>
+```
+
+**Good:**
+```html
+<section class="panel" data-cut="C-01">First</section>
+<section class="panel" data-cut="C-02">Second</section>
+```
+
+---
+
+### `explicit-cut-in-autocut`
+
+Forbid explicit `cut`, `topCut`, or `bottomCut` props on `<Panel>` or `<PanelPair>` inside `<Sheet autoCut>` where cut numbers are assigned automatically.
+
+**Bad:**
+```tsx
+<Sheet autoCut>
+  <Panel cut="C-01" title="Overview">...</Panel>
+</Sheet>
+```
+
+**Good:**
+```tsx
+<Sheet autoCut>
+  <Panel title="Overview">...</Panel>
+</Sheet>
+```
+
+---
+
+### `raw-shadcn-import`
+
+Forbid raw `@/components/ui/*` imports, `@radix-ui/*` primitives, or third-party chart/animation libraries (`recharts`, `chart.js`, `d3`, `framer-motion`, `gsap`) where a FRAME/12 component, adapter, or hook exists.
+
+**Bad:**
+```tsx
+import { Button } from '@/components/ui/button';
+import * as DialogPrimitive from '@radix-ui/react-dialog';
+```
+
+**Good:**
+```tsx
+import { Button, Dialog, DialogContent } from '@/components/frame12';
+```
+
+---
+
+### `unsafe-html`
+
+Active in `lintHtml()` (and when linting `.html` / `.htm` files via `lintFiles()`, `lintDirectory()`, or the CLI). Forbid external `<script src="…">` tags, external resource loads (`<link rel="stylesheet" href="…">`, `<img src="https://…">`, `<source>`, `<video>`, `<audio>`, `<track>`, `<image>`, CSS `@import`, and external CSS `url(https://…)`), embedded frames (`<iframe>`, `<object>`, `<embed>`, `srcdoc`), `<meta http-equiv="refresh">`, `<base href="…">`, inline event handler attributes (`onclick=`, `onload=`, `onerror=`, …), and `javascript:` / `vbscript:` URLs in attribute values. Self-contained inline `<script>` elements without `src` (such as the on-twos pose clock), relative/anchor `<a href="…">` links, and `data:` URIs are permitted.
+
+**Bad:**
+```html
+<script src="https://cdn.example.com/tracker.js"></script>
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Inter" />
+<iframe src="https://example.com/embed"></iframe>
+<button onclick="doSomething()">Run</button>
+<a href="javascript:alert(1)">Link</a>
+```
+
+**Good:**
+```html
+<script>
+  // Self-contained on-twos motion pose clock
+</script>
+<button type="button" id="run-btn">Run</button>
+<a href="#details">Link</a>
+```
+
+---
+
+## `lintHtml()` Scanner Scope & Limits
+
+`lintHtml(html, opts)` uses a fast, zero-dependency HTML tag/attribute/style scanner rather than a full WHATWG HTML5 parser:
+- **Supported constructs:** `<!-- comments -->`, `<![CDATA[ ... ]]>`, `<!DOCTYPE ...>`, `<style>` and `<script>` raw-text blocks, single-quoted / double-quoted / unquoted attributes, boolean attributes, HTML void elements (`<img>`, `<meta>`, `<br>`, etc.), and self-closing SVG/HTML tags (`<line />`).
+- **Token `<style>` exemption:** `<style data-f12-tokens>` and any `<style id="...">` whose `id` is listed in `opts.tokenStyleIds` (for example `{ tokenStyleIds: ['f12-tokens'] }`) are skipped by the CSS literal rules.
+- **Known limits:**
+  - CSS rules inside `<style>` inspect single-level `{ ... }` declaration blocks; deeply nested CSS rules (`@layer` / native CSS nesting with `--f-marker` split across parent and nested blocks) are evaluated per declaration block.
+  - Dynamic DOM mutations performed at runtime by inline `<script>` code are not executed or inspected.
+  - Malformed HTML with unescaped `<` followed immediately by an ASCII letter in raw text (e.g. `a <b` instead of `a &lt; b`) is tokenized as an opening tag.

package/dist/cli.mjs

@@ -0,0 +1,4 @@
+#!/usr/bin/env node
+import { runCli } from './index.js';
+
+process.exit(runCli());

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+export type RuleId =
+  | 'color-literal'
+  | 'illegal-gutter'
+  | 'marker-misuse'
+  | 'cut-order'
+  | 'explicit-cut-in-autocut'
+  | 'raw-shadcn-import'
+  | 'unsafe-html';
+
+export interface Violation {
+  rule: RuleId;
+  message: string;
+  file: string;
+  line: number;
+  column: number;
+  snippet?: string;
+}
+
+export interface LintHtmlOptions {
+  /**
+   * File name reported in returned `Violation` entries.
+   * @default "input.html"
+   */
+  file?: string;
+  /**
+   * `<style id="...">` element IDs whose contents define design tokens and
+   * should be exempt from CSS literal rules (in addition to `<style data-f12-tokens>`).
+   */
+  tokenStyleIds?: string[];
+}
+
+export interface LintSourceOptions {
+  /**
+   * Force fallback behavior as if the optional `typescript` peer dependency is not installed.
+   */
+  disableTypeScript?: boolean;
+  /**
+   * Suppress the one-time console warning when falling back to regex cut-order checks.
+   */
+  quietFallbackWarning?: boolean;
+}
+
+export declare const RULES: Readonly<Record<RuleId, string>>;
+export declare const FORBIDDEN_SHADCN_MODULES: ReadonlySet<string>;
+export declare const FORBIDDEN_EXTERNAL_PACKAGES: ReadonlySet<string>;
+
+export declare function lintSource(
+  content: string,
+  filePath?: string,
+  opts?: LintSourceOptions
+): Violation[];
+
+export declare function collectFiles(targetPaths: string[]): string[];
+
+export declare function lintFiles(targetPaths: string[]): {
+  files: string[];
+  violations: Violation[];
+};
+
+export declare const lintDirectory: typeof lintFiles;
+
+export declare function lintHtml(
+  /** HTML text, or an object whose string form is HTML (e.g. an `@frame12/static` `Html`). */
+  html: string | { toString(): string },
+  opts?: LintHtmlOptions
+): Violation[];
+
+export declare function runCli(argv?: string[], cwd?: string): number;